Decorating SDO Type for Persistence

Basics of SDO Types

SDO defines its type system in terms of two abstractions Type and Property captured in SDO API as commonj.sdo.Type and commonj.sdo.Property interfaces.

A Type can be

  • primitive data type such as xsd:int or xsd:string
  • an extension of primitive type
  • a user defined type

Each Property has a Type. A Property can be single-valued or many-valued. It can be contained in an enclosing Type. A Property can be read-only. These features of Type or Property are available through interogative methods such as Type.isAbstract(), Type.isDataType() or Property.isMany().

SDO Types can be generated from XML Schema Definition. A very simple example of XML Schema Definition that can be used for SDO Type can be defined in a person.xsd:

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:example="http://www.example.com/Example" 
    targetNamespace="http://www.example.com/Example"
    xmlns:sdo="commonj.sdo">

    <xsd:complexType name="Person">
        <xsd:sequence>
            <xsd:element name="firstName" type="xsd:string"/>
            <xsd:element name="lastName"  type="xsd:string"/>
            <xsd:element name="age"       type="xsd:int"/>
         </xsd:sequence>
         <xsd:attribute name="ssn"     type="xsd:ID"/>
         <xsd:attribute name="version" type="xsd:int"/>
    </xsd:complexType>
</xsd:schema>

SDO API provides a XSDHelper object that can read a XML Schema Definition file and define SDO Type Person from this definition.

Adding Property to SDO Types for persistence

If instances of SDO Types are to be persisted and updated, two pieces of information becomes vital: identity and version. SDO Specification version 2.0 does not specify how to designated Property of a Type to carry identity or version information.

Hence, we devise a simple way described here.

Adding Identity Property

Unlike a database table definition that specifies a primary key to uniquely identify its rows, SDO Type does not specify a property whose value will uniquely identify an instance of that type. XML schema definition, however, defines xsd:ID, xsd:key and xsd:keyRef for the purpose of unique identification of SDO instances.

Persistent SDO Type must specify a identity property in either of the follwing two ways.

  1. Define a Property of xsd:ID type

    One way is to designate a Property of xsd:ID type. For example,

        <xsd:attribute name="ssn" type="xsd:ID"/>

    xsd:ID types represent the value as String, so the value of ssn property will be stored as a String.

  2. Define a Property with name id

    The other option to define a identity property (which is not neccessarily a String) is declare a property with name id (yes, it is harcoded, right now) and of primitive type. For example,

        <xsd:attribute name="id"  type="xsd:int"/>

    will deine id as identity property for Person and value of id will be integers.

Why xsd:key type is not used for Identity?

xsd:key is the right semantics to define a identity property for SDO Type. However, xsd:ID is used because of an implementation artifact.

Currently, SDO API does neither provide the identity property for a Type nor a means to determine the original xsd type for a Property (it is going to change in future SDO API specification). A specific SDO implementation may have some means to obtain that information. Tuscany SDO Implementation used here provides a way to determine whether a Property is declared as xsd:ID. Simply because of this reason, we use xsd:ID>.> rather than <,<<xsd:key to define identity property of a SDO Type.

Adding Version Property

A version property is required for update. JPA persistence service uses optimistic concurrency -- persistent instances are not locked in database and but concurrent modifications are detected by checking the version of in-memory instances against original database record. This is vital when a DataObject is updated. JPA provider will use the version information to determine whether the instance to be updated or a new instance to be created.

The version property is simply defined by declaring a property named version of xsd:int on SDO Type.

    <xsd:complexType name="Person">
         <!-- other definitions ommitted -->
         <xsd:attribute name="version" type="xsd:int"/>
    </xsd:complexType>

The property must be named version and always of type xsd:int. This is arbitrary decision but will be relaxed in future.

Identity and Version values are auto-generated

The value of identity and version property field is currently always auto-generated by JPA persistence service when the DataObject is persisted. So user application must not populate these values. Identity value set by user application are ignored when the instance is persisted. Setting version value will cause unpredictable behavior.