SDO Code Details | SOA for the Business Developer: Concepts, BPEL, and SCA (Business Developers series)

At this time (March 2007), the most advanced SDO specification is Service Data Objects for Java Specification Version 2.1.0. The rest of this chapter gives details from that document and from the Apache Tuscany project. We also provide Java examples, and they reveal aspects of SDO that are likely to be true in any language. For example, you'll always register Data Object types to the SDO runtime.

If you're unfamiliar with Java, we can offer a pair of tutorials. They even introduce you to Eclipse, which is an open-source development environment that supports a variety of languages:

http://www.ibm.com/developerworks/edu/j-dw-java-intjava-i.html
http://www.ibm.com/developerworks/edu/j-dw-java-intermed-i.html

If you wish to avoid the code detail, we suggest you skip to Appendix A, which is of more general interest.

Helper Interfaces

Implementations of SDO for Java provide the following interfaces:

CopyHelper has methods for copying one Data Object to another in either of two ways:
- A deep copy reproduces not only the Data Object but every Data Object contained in the Object being copied.
- A shallow copy reproduces only the Data Object.
DataFactory has methods for creating Data Objects.
DataHelper has methods for converting data from one type to another.
EqualityHelper has methods for comparing one Data Object to another or for comparing one data graph to another.
TypeHelper has methods to create a new type, to create a Data Object from a type, to identify the type of a Object, or to list Object properties that were specified at run time.
XMLHelper has methods to serialize a Data Object to an XML source (as shown earlier) or to de-serialize XML source to a Data Object.
XSDHelper has methods to retrieve data descriptions from XML Schema Definitions and to create new XSDs from types and from Data Object properties.

In addition, a HelperContext interface gives you access to a set of instances of other Helper classes. Those Helper instances in turn provide access to data that is specific to a set of Data Object types. You might create Data Object types by using an XSDHelper instance from one HelperContext, for example, and use a DataFactory instance from the same HelperContext instance to create Data Objects based on those types. You can't create Data Objects based on registered types, however, if you try to use a DataFactory instance retrieved from a HelperContext instance other than the HelperContext instance used to create the types.

The SDO HelperProvider class gives you access to a globally scoped HelperContext instance, as shown in a later example.

Example Code

This section shows snippets of the XML Schema definitions that describe an insurance quote. Also shown is Java code for defining Data Objects that reflect the XML Schema. We'll start with a few general points:

The preferred way to create Data Objects statically is to use Java factory classes.
The only way to create Data Objects dynamically is to use such classes.
When you work with the Apache Tuscany implementation of SDO, one option is to use the factory classes that are specific to Tuscany.

Type Definition of an Insurance Quote

Listing 10.2 shows the XSD that holds the complex type Quote. An Object of this type might be passed from one service to another.

Listing 10.2: XSD for the complex type Quote

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"        xmlns:Q1="http://com/highlight"        targetNamespace="http://com/highlight">    <xsd:include schemaLocation="CustomerQuoteInformation.xsd"/>    <xsd:complexType name="Quote">      <xsd:sequence>       <xsd:element name="quoteID" type="xsd:string"               minOccurs="0" />       <xsd:element name="dateOfQuote" type="xsd:dateTime"               minOccurs="0" />       <xsd:element name="customerInformation"                    type="Q1:CustomerQuoteInformation"               minOccurs="0" />       </xsd:sequence>    </xsd:complexType> </xsd:schema>

Listing 10.3 shows the XSD that holds the complex type CustomerQuoteInformation.

Listing 10.3: XSD for the complex type CustomerQuoteInformation

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"        xmlns:Q1="http://com/highlight"        targetNamespace="http://com/highlight">   <xsd:include schemaLocation="Auto.xsd"/>   <xsd:include schemaLocation="NameAddress.xsd"/>   <xsd:complexType name="CustomerQuoteInformation">    <xsd:sequence>      <xsd:element name="applicant" type="Q1:NameAddress"              minOccurs="0"/>      <xsd:element name="dependents" type="Q1:NameAddress"              minOccurs="0" maxOccurs="unbounded" />      <xsd:element name="auto" type="Q1:Auto"              minOccurs="0" maxOccurs="unbounded" />    </xsd:sequence>   </xsd:complexType> </xsd:schema>

Listing 10.4 shows the XSD that holds the complex type NameAddress.

Listing 10.4: XSD for the complex type NameAddress

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"             targetNamespace="http://com/highlight">    <xsd:complexType name="NameAddress">       <xsd:sequence>          <xsd:element name="first" type="xsd:string" />          <xsd:element name="last" type="xsd:string" />       </xsd:sequence>    </xsd:complexType> </xsd:schema>

Listing 10.5 shows the XSD that holds the complex type Auto.

Listing 10.5: XSD for the complex type Auto

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"             targetNamespace="http://com/highlight">    <xsd:complexType name="Auto">       <xsd:sequence>          <xsd:element name="VIN" type="xsd:string" />          <xsd:element name="licensePlate" type="xsd:string" />          <xsd:element name="model" type="xsd:string" />          <xsd:element name="year" type="xsd:int" />       </xsd:sequence>    </xsd:complexType> </xsd:schema>

Static Definition

When you review our sample code for defining Data Objects statically, be aware of naming conventions from the Apache Tuscany project. First, each generated method that gets or sets properties has a name like quote.getQuoteID() in accordance with the following rules:

The method name begins with the characters get (for getting a value) or set (for setting a value).
Append the init-capped property name (use getQuoteID instead of getquoteID, for example).

Second, the name of a generated factory class (in this case, HighlightFactory) is derived from the last qualifier (in this case, highlight) in the target namespace of the XML Schema.

 <xsd:schema xmlns:bo="http://com/highlight"             xmlns:xsd="http://www.w3.org/2001/XMLSchema"             targetNamespace="http://com/highlight">

Listing 10.6 shows the Java code.

Listing 10.6: Java code to define Data Objects statically

 import java.util.Date; import commonj.sdo.DataObject; import commonj.sdo.helper.DataHelper; import commonj.sdo.helper.XMLHelper; import commonj.sdo.helper.HelperContext; import commonj.sdo.impl.HelperProvider; import com.highlight.CustomerQuoteInformation; import com.highlight.HighlightFactory; import com.highlight.NameAddress; import com.highlight.Quote; import com.highlight.impl.HighlightFactoryImpl; public class StaticDataAPI {    private HelperContext scope = HelperProvider.getDefaultContext();    public static void main(String[] args) throws Exception    {       HighlightFactory.register(scope);       Quote quote = HighlightFactory.INSTANCE.createQuote();       quote.setQuoteID("0001");       quote.setDateOfQuote(DataHelper.INSTANCE.toDateTime(new Date()));       CustomerQuoteInformation customerInfo =          HighlightFactory.INSTANCE.createCustomerQuoteInformation();       quote.setCustomerInformation(customerInfo);       NameAddress applicantNameAddr =          HighlightFactory.INSTANCE.createNameAddress();       applicantNameAddr.setFirst("John");       applicantNameAddr.setLast("Doe");       customerInfo.setApplicant(applicantNameAddr);       XMLHelper.INSTANCE.save((DataObject)quote,          HighlightFactoryImpl.NAMESPACE_URI, "quote", System.out);    } }

The example

imports the Java Date class, a set of SDO classes, and a set of application-specific, generated interface classes.
creates a HelperContext instance, which is how we expect the Apache Tuscany project to register SDO-generated types to the SDO runtime.
creates quote, which is a Data Object of type Quote. The code uses the Tuscany-generated factory class.
sets the properties quoteID and dateOfQuote. (SDO uses an Object property of type string to handle an XSD element of type dateTime.)
creates customerInfo, which is a Data Object of type CustomerQuoteInformation, and references that Object from quote.
creates applicantNameAddr, which is a Data Object of type NameAddress; sets the properties first and last; and references that Object from customerInfo.
uses the SDO XMLHelper class to serialize (create text from) the quote object and to write that text to the standard output. The arguments are as follows:
- the Data Object being serialized.
- the namespace of the root element in the output XML. (That namespace came from the XML Schema definition.)
- the name of the root element.
- the output destination.

Here is the serialized XML, formatted for easy reading.

 <?xml version="1.0" encoding="ASCII"?> <highlight:quote    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xmlns:highlight="http://com/highlight"    xsi:type="highlight:Quote">    <quoteID>0001</quoteID>    <dateOfQuote>2006-11-29T18:35:26.464 EST</dateOfQuote>    <customerInformation>       <applicant>          <first>John</first>          <last>Doe</last>       </applicant>    </customerInformation> </highlight:quote>

Dynamic Definition

Listing 10.7 shows Java code that defines Data Objects dynamically.

Listing 10.7: Java code to define Data Objects dynamically

 import java.io.InputStream; import java.net.URL; import java.util.Date; import commonj.sdo.DataObject; import commonj.sdo.Type; import commonj.sdo.helper.DataHelper; import commonj.sdo.helper.HelperContext; public class DynamicDataAPI {    public static void main(String[] args) throws Exception {        URL url = DynamicDataAPI.class.getResource        ("/xsd-includes/http.com.highlight.xsd");        InputStream inputStream = url.openStream();        HelperContext hc = SDOUtil.createHelperContext();        hc.getXSDHelper().define(inputStream, url.toString());        inputStream.close();        Type quoteType =        hc.getTypeHelper.getType("http://com/highlight", "Quote");        DataObject quote = hc.getDataFactory.create(quoteType);        quote.set("quoteID", "0001");        quote.set("dateOfQuote", DataHelper.INSTANCE.toDateTime(new Date()));        DataObject customerInfo =                         quote.createDataObject("customerInformation");        DataObject applicantNameAddr =            customerInfo.createDataObject("applicant");        applicantNameAddr.set("first", "John");        applicantNameAddr.set("last", "Doe");        hc.getXMLHelper.save           (quote, quote.getType().getURI(), "quote", System.out);        System.out.println("Dear " + quote.getString("applicant/first"));        }        private static HelperContext methodToGetHelperContext() {          return /* application logic goes here */;        } }

The example

imports a set of standard Java classes and SDO classes, but no application-specific interface or implementation classes.
accesses a HelperContext instance, which registers all the retrieved Object types. The SDO specification does not specify the details for creating the HelperContext instance, and the Apache Tuscany project uses SDOUtil.createHelperContext().
isolates the Quote type from the TypeHelper class.
creates quote, which is a Data Object of type Quote.
sets the properties quoteID and dateOfQuote, referring to the properties by name.
creates the Object customerInfo in relation to the quote Object. The type for customerInfo is identified by the name customerInformation, which is the name of an element in the XML Schema complex type called Quote.

 <xsd:sequence>    <xsd:element name="quoteID" type="xsd:string"                 minOccurs="0" />    <xsd:element name="dateOfQuote" type="xsd:dateTime"                 minOccurs="0" />    <xsd:element name="customerInformation"                 type="Q1:CustomerQuoteInformation"                 minOccurs="0" /> </xsd:sequence>

The created object is based on the complex type CustomerQuoteInformation.

similarly, creates the Object applicantNameAddr in relation to the customerInfo Object. The type for applicantNameAddr is identified by the name applicant, which is the name of an element in CustomerQuoteInformation.

 <xsd:sequence>    <xsd:element name="applicant" type="Q1:NameAddress"                 minOccurs="0"/>    <xsd:element name="dependents" type="Q1:NameAddress"                 minOccurs="0" maxOccurs="unbounded"/>    <xsd:element name="auto" type="Q1:Auto"                 minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence>

The created object is based on the complex type NameAddress.

sets the properties first and last, referring to the properties by name.
uses the SDO XMLHelper class to serialize the quote object and to write that text to the standard output. In this case, the namespace is provided by quote.getType().getURI(), which is a dynamic API call that gets the type of the Object as well as the namespace of the type.

Advanced SDO Capabilities in Java

For a Java example that demonstrates more advanced capabilities, see Kelvin Goodson and Geoffrey Winn's two-part article called "SOA and Web Services - What Is SDO?" in Java Developer's Journal. Part 1 is in volume 11, issue 12: http://java.sys-con.com/read/313547.htm.