Containment
Something to note here is that we have created a containment relationship between the person1 DataObject and the referrals DataObject. SDO treats containment relationships in a special way. In every data graph each data object apart from the root has a link to exactly one parent data object that is its container. The corresponding property from the parent to the child is marked as a containment property. So the containment relationships form a strict hierarchical structure whereby every data object in a graph is reachable by traversing only the containment links. To enable SDO to describe richer, more diverse graph structures, non-containment links can also be included into the graph. These non-containment links permit arbitrary references across the containment hierarchy.

SDO has behavior built in to preserve the containment hierarchy constraint; so, for example, if you assign a data object into a graph as the value of a containment property then any existing value at that location in the graph will be automatically displaced (the value of its parent property becomes null and the orphaned data object, along with any children it might have, becomes a separate data graph). In addition, if the data object that you're assigning to the graph is already contained in a data graph then it will be automatically removed from that containment association before being assigned to its new location.

Let's take a look at an example. Suppose that the institutions running the tests have learned from the mistakes of previous such projects in which patients already diagnosed with a condition have inadvertantly received letters intended for new referrals and this caused unnecessary distress. This was seen as sufficiently important for them to engineer their data models to ensure that referrals and patients were always disjoint sets. Listing 2 shows the XML schema used to model the test. It makes use of the schema shown earlier to model the people involved in the test.

This schema has a global element named "test," which is of type "Test," which contains three sets of people: referrals, patients, and relatives. We saw from the previous schema that a PersonSet contains a list of people so this arrangement of containment relationships ensures that if we assign a person who already exists in the set of referrals to be in the set of patients then by virtue of the preservation of containments constraint, that person is automatically removed from the referrals set by the SDO infrastructure. Let's see that in action.

DataObject test = DataFactory.INSTANCE.create("www.example.org/MedicalTest", "Test");
test.set("referrals", referrals);

At this point our entire test consists of a set of referrals with one member (we haven't yet initialized the set of patients or relatives so they take the default null value). Here's how it would serialize to XML.

<Test:test xmlns:Test="www.example.org/MedicalTest">
   <referrals>
     <person gender="male" id="1" name="Joe Johnson Snr">
       <dob>1 January 1950</dob>
     </person>
   </referrals>
</Test:test>

Having visited the hospital, Joe Johnson Sr. is found to have symptoms indicating one of the conditions that the test is investigating, so he's added to the set of patients.

      DataObject patients = test.createData-Object("patients");
    patients.getList("person").add(person1);

As an aside, note how we created the patients DataObject in a more concise way this time. The "test" DataObject knows the type of its "patients" property and so we don't need to use DataFactory to look up the type and create an instance.

Having made this assignment of person1 to the set of patients, this is how the whole test serializes.

<Test:Test xmlns:Test="www.example.org/MedicalTest">
   <referrals/>
   <patients>
     <person gender="male" id="1" name="Joe Johnson Snr."/>
   </patients>
</Test:Test>

So as a result of this one assignment, the patient's set has one member and the referrals set has been reduced to zero.

In part two of this article, we'll examine more SDO features, including the use of open content, change summaries, and references between objects that express more than containment.

References
¹ Williams, K., Daniel, B. "SOA Web Services - Data Access Service", Java Developer's Journal, August 2006, http://java.sys-con.com/read/260053.html