At this point we have a fairly empty type description that's been added to a list that we'll build up as we go along so we can submit the list of type descriptions to the TypeHelper's define method later. Adding property descriptions to type descriptions is something we do a few times so we'll create another little utility method to do the basics for us:

private DataObject addPropertyDescription(
    DataObject containerTypeDescription,
    Object propertyType,
    String propertyName
) {
    DataObject property =
      containerTypeDescription.createDataObject("property");
    property.set("type", propertyType);
    property.setString("name", propertyName);
    property.setBoolean("containment", true);
    return property;
}

This method takes our new unpopulated type description and adds to it a basic description of a new property that we want the type to have. For example:

Type stringType = typeHelper.getType("commonj.sdo", "String");
addPropertyDescription(personTypeDesc, stringType, "name");

The personType now has a property "name" that has a type of the pre-existing SDO String type. We could go on adding new properties to the description using existing types; but note how the second argument for adding property descriptions to our utility method, "propertyType," used the abstract Object Java class. This is because the method is suitable as it stands to accept a type described by a data object (as above), rather than a real Type instance.

Here's an example of why this is important. In our schema definition a person has a list of relatives. A relative is described by a relationship name and a reference to another person. So the Person type has a dependency on the Relative type and the Relative type has a dependency on the Person type. If we weren't able to use a description of a type in this way (rather than a real type instance) then we wouldn't be able to represent these commonly occurring circular dependencies.

A point of note about the TypeHelper interface's define methods is that the process of creating a true type instance is logically atomic, i.e., once a Type is created you can't go adding properties to it. This is helpful because it ensures that once a data object has been created, you can be sure its type won't be altered. The upshot of this is that for types such as Person and Relative that are interdependent we have to create them in one call to TypeHelper.define() so we have to build a list of type descriptions and submit it to the variant of the TypeHelper's define method that takes a list of descriptions and produces a list of types in one method call.

Leaving aside the remaining simple typed properties of the type Person, here's how we complete the type description:

DataObject relativeType = createTypeDescription(
    peopleURI, "Relative");
DataObject rp = addPropertyDescription(
    personTypeDesc, relativeType, "relative");
rp.setBoolean("many", true);
personTypeDesc.set("open", Boolean.TRUE);

First we create a new unpopulated description of the Relative type that we can use as a "forward declaration" of the type. This lets us add a "relative" property description to the Person type. The "relative" property is modified to allow multiple values and finally the Person type is described as being open just as we saw in the earlier XML Schema definition of the type system to permit things such as a medical condition to be added to an instance of the Person type.

The rest of the simple typed properties of the Relative type are added to its description, and all the other types we require are described this way. Eventually, when the description is complete, and all the descriptions are collected in the list, we submit the list of descriptions to a TypeHelper for compilation into a type system:

List types = TypeHelper.INSTANCE.define(typeDeclarations);

The types are returned as a list but more importantly they're known to the environment. So returning to the first line of code of our scenario following the creation of the type system:

DataObject person1 = DataFactory.INSTANCE.create(
    "www.example.org/people", "Person");

So the example can be executed using a type system that was created programatically, rather than by using the XML Schema-to-SDO conversion process.

A TypeHelper can be regarded as an instrument for controlling the scope for a set of types. There are known issues with the singleton pattern and so the recently published SDO 2.1 specification has addressed this issue by introducing a new HelperContext class. The HelperContext provides access to a consistent set of SDO helpers all referencing a specific TypeHelper instance.

Generating Java Classes to Represent the Type System
So far in our example we've only been using the dynamic SDO API, but in many environments, when the type system can be defined at application development time, it's better to use generated Java classes to represent the data objects in a data graph. When using generated classes, the performance is better and the code is more natural; and yet the full power of the dynamic API is available to be used on the generated classes if needed.

The SDO API defines a mapping from the XML Schema-to-Java classes. There's no current specification to define the tooling for generating SDO classes. In the Apache Tuscany implementation of SDO this is done with the XSD2JavaGenerator class:

java org.apache.tuscany.sdo.generate. XSD2JavaGenerator MedicalTest.xsd

This creates an interface and implementation packaged for each of the namespaces in the XML Schema and any imported schemata. An interface class is generated per XML Schema type, and a Factory interface for crating instanes of the types is created along with the correponding implementations.

And now we can begin coding in an altogether different style, using the property-specific getter and setter methods of the generated classes:

Person p1 = PeopleFactory.INSTANCE.createPerson();
p1.setId("1");
p1.setName("Joe Johnson Snr.");
p1.setGender("male");
XMLHelper.INSTANCE.save(
    (DataObject)p1,
    "www.example.org/people",
    "person", System.out);

Summary
In this two-part article we've seen how SDO provides a standardized approach to data programming that's particularly well suited to Service Oriented Architectures, presenting a single consistent view of data obtained from a variety of sources such as relational databases and XML. Version 2.1 of the SDO specification was released at the end of 2006 and work has already started on the next version.

References

• G. Winn and K. Goodson. "What Is SDO?" Java Developer Journal. Vol. 11, Issue 12.
• "Service Data Objects for Java Specification Version 2.1.0." November 2006. Available from www.osoa.org/