Feeds

Implementing platform independent data with SDO

A practical example of using Service Data Objects

Build a business case: developing custom apps

Hands on In my last column, we looked at the concepts behind SDO or Service Data Objects. SDO is a language independent format for representing data. It is built around the concept of a DataGraph of DataObjects. The DataObjects hold both the actual data being represented and metadata that describes that data. As such, it represents self-describing, platform independent, data. It also represents a separation between the data (in the DataGraph) and the logic that is applied to that data (within an application that uses the SDO).

In this column, we will look at a concrete example of a SDO DataGraph, how a Data Mediation Service (or DMS) might generate a DataGraph and how a DataGraph may be manipulated and stored. We will also look at how custom DataObject classes can be created based on an XSD definition (conceptually these could also be generated form Java interfaces but this functionality is not yet available. We will conclude by looking at the relationship between SDO and SCA (or Service Component Architecture) as well as SDO and JavaBeans.

SDO Implementation

As was mentioned in the last column, SDO is actually a specification (currently managed by the Open SOA organisation but soon to be managed by OASIS and the JCP process). You must obtain an implementation of SDO from an appropriate Application Server vendor (such as IBM with WebSphere or BEA with WebLogic). Alternatively, you can use the Apache Tuscany SDO implementation – which is the version used here.

To get the SDO implementation you should download the Tuscany version appropriate for your platform. From this file, you need to extract the lib jar files that contain the SDO specification as Java interfaces and the Tuscany implementation of those interfaces. In my case, using Windows, I created a lib directory within an Eclipse project containing the following files:

  • codegen-2.2.1.jar
  • ecore-xmi-2.2.1.jar
  • codegen-ecore-2.2.1.jar
  • sdo-api-r2.0.1-1.0-incubator-M2.jar
  • common-2.2.1.jar
  • tuscany-sdo-impl-1.0-incubator-M2.jar
  • ecore-2.2.1.jar
  • tuscany-sdo-tools-1.0-incubator-M2.jar
  • ecore-change-2.2.1.jar
  • xsd-2.2.1.jar

Note that some of these files relate to frameworks used within Tuscany’s implementation of SDO (such as the Eclipse EMF jars).

SDO Example

The simple SDO example presented below is comprised of two classes, the EmployeeDMS and the EmployeeSDOTestClient. The EmployeeDMS illustrates a very simple DMS that is used to create and receive a simple Employee DataGraph. The EmployeeSDOTestClient is a very simple test client that drives the DMS.

The EmployeeDMS

We will first look at the EmployeeDMS that provides a very simple example of how a DMS might work when used with an application that might consume or produce a simple Employee DataGraph. The EmployeeDMS class is presented below:

package com.cramer.sdo.dms;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

import org.apache.tuscany.sdo.util.SDOUtil;

import commonj.sdo.DataGraph;
import commonj.sdo.DataObject;
import commonj.sdo.helper.DataFactory;
import commonj.sdo.helper.XMLDocument;
import commonj.sdo.helper.XMLHelper;
import commonj.sdo.helper.XSDHelper;

public class EmployeeDMS {

        public static final String XSD_FILE = "employee.xsd";
        public static final String NAMESPACE = 
                                "http://www.regdeveloper.com";
        public static final String XML_DIR = "xml/data/";

        public EmployeeDMS() throws Exception {
                System.out.println("Creating EmployeeDMS");
                defineSDOTypes();
        }

        private void defineSDOTypes() throws Exception {
                System.out.println("Defining SDO Types for DMS");
                String xsdFilename = XML_DIR + XSD_FILE;
                File file = new File(xsdFilename);
                if (file.exists()) {
                        System.out.println("Type Def'ns gen'd from: " 
                                          + xsdFilename);
                        InputStream is = new FileInputStream(file);
                        XSDHelper.INSTANCE.define(is, null);
                        is.close();
                } else {
                        System.out.println("File Not Found: " 
                                            + xsdFilename);
                }
        }

        public DataGraph getEmployee() throws Exception {
                System.out.println("Programmatically Creating Data Objects");

                DataGraph dataGraph = SDOUtil.createDataGraph();
        
                DataObject employee = 
              DataFactory.INSTANCE.create(NAMESPACE, "EmployeeType");

                employee.setString("name", "John Hunt");
                employee.setInt("employeeId", 34255);

                DataObject address = 
                          employee.createDataObject("address");
                address.set("country", "GB");
                address.set("street", "12 No Street");
                address.set("city", "Nowhere");
                address.set("county", "Wiltshire");
                address.setString("postcode", "SNnn nJG");

                System.out.println("Created Data Objects");
                
                SDOUtil.setRootObject(dataGraph, employee);

                return dataGraph;
        }
        
        public void saveEmployeeToFile(DataGraph dg, String filename) throws IOException {
                System.out.println("Saving SDO objects to file");
                filename = XML_DIR + filename;
                OutputStream stream = new FileOutputStream(filename);
                DataObject employee = dg.getRootObject();
                XMLHelper.INSTANCE.save(employee, 
                                    NAMESPACE, 
                                    "Employee", 
                                    stream);
                System.out.println("Saved to file " + filename);
        }

        private static final String XML_STRING = 
            "<?xml version=\"1.0\" encoding=\"ASCII\"?>" +
            "<regdeveloper:Employee xmlns:regdeveloper=\"http://www.regdeveloper.com\">" +
                      "<name>John Hunt</name>" +
                      "<address country=\"GB\">" +
                         "<street>12 No Street</street>" +
                         "<city>Nowhere</city>" +
                         "<county>Wiltshire</county>" +
                         "<postcode>SNnn nJG</postcode>" +
                      "</address>" +
                      "<employeeId>34255</employeeId>" +
            "</regdeveloper:Employee>";

        public DataGraph getEmployeeFromString() {
                DataObject employee = 
                 XMLHelper.INSTANCE.load(XML_STRING).getRootObject();
                DataGraph dataGraph = SDOUtil.createDataGraph();
                SDOUtil.setRootObject(dataGraph, employee);
                return dataGraph;
        }

}

The EmployeeDMS is used to create an Employee DataGraph (containing a single Employee DataObject) in a number of ways.

The method defineSDOTypes uses an XSD file to define the types for the objects within the DataGraph. Conceptually the types can be defined in a number of ways including via Java classes. In my example, the XSD file defines the types for use within the DataGraph as this is potentially a useful way of doing this for an SOA system. The XSD file is presented below. As you can see form this file, the XSD is very simple and is intended merely to illustrate the concept:

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

    <xsd:element name="Employee" type="EmployeeType"/>
    <xsd:element name="comment" type="xsd:string"/>

    <xsd:complexType name="EmployeeType">
        <xsd:sequence>
            <xsd:element name="name" type="xsd:string"/>
            <xsd:element name="address" type="Address"/>
            <xsd:element name="employeeId" type="xsd:int"/>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="Address">
        <xsd:sequence>
            <xsd:element name="street" type="xsd:string"/>
            <xsd:element name="city"   type="xsd:string"/>
            <xsd:element name="county"  type="xsd:string"/>
            <xsd:element name="postcode"    type="xsd:string"/>
        </xsd:sequence>
        <xsd:attribute name="country" type="xsd:NMTOKEN" fixed="GB"/>

    </xsd:complexType>

 </xsd:schema> 

The data model define by the Schema is very simple; essentially an Employee object can have a name, an address and an employeId. A name is a string, an employeId is an integer and an address is another class that contains a street, city, county, postcode and country. Note that the method defineSDOTypes must be run before any DataObjects are created otherwise an exception will be thrown, as the current SDO environment will have no knowledge of the data types for the specified namespace.

The getEmployee method can then be used to programmatically create a very simple DataGraph containing one single DataObject that defines details about the employee “John Hunt”, including his employeeId, and address. Note that one of the utility classes provided in the Tuscany implementation is used to create the DataGraph and to allow the root object of the DataGraph to be set. It is possible to do both of these with the underlying SDO Core API but it is more complex than using the SDOUtilclass.

In contrast to the getEmployee method, the getEmployeeFromString method creates a DataGraph containing a single DataObject using an XML document defined within a string (this could also have been defined in an XML document). This illustrates how an XML payload may be converted into SDO objects with minimal intervention from the programmer.

Finally, the method saveEmployeeToFile take a DataGraph and a filename, and writes the DataGraph to the provided filename in XML format. This is done using the XMLHelper instance method save, that writes the SDO to an output stream in XML format.

The EmployeeSDOTestClient Class

Now that we have the EmployeeDMS, we can create an application that will use the facilities provided by it. This application, in our case, is the EmployeeSDOTestCLient class. This is a simple test harness containing a single main method. This main method exercises each of the public methods in the EmployeeDMS. The test harness class is presented below:

package com.cramer.sdo.client;

import com.cramer.sdo.dms.EmployeeDMS;
import commonj.sdo.DataGraph;
import commonj.sdo.DataObject;

public class EmployeeSDOTestClient {

        public static void main(String[] args) {
                try {
                        System.out.println("---------------------------");
                        EmployeeDMS dms = new EmployeeDMS();

                        System.out.println("---------------------------");
                        DataGraph dg = dms.getEmployee();
                        System.out.println("---------------------------");
                        dms.saveEmployeeToFile(dg, "tmpXMLFile.xml");
                        dg.getRootObject().setString("name", 
                                               "Denise Cooke");
                        dms.saveEmployeeToFile(dg, "tmpXMLFile2.xml");
                        System.out.println("---------------------------");
                        
                        dg = dms.getEmployeeFromString();
                        DataObject employee = dg.getRootObject();
                        System.out.println("Name: " + 
                                employee.getString("name") + 
                                "\n\t" + "Employee ID: " + 
                                employee.getInt("employeeId"));
                        DataObject address = 
                                employee.getDataObject("address");
                        System.out.println("\tAddress: ");
                        System.out.println("\t\t Street: " + 
                                     address.getString("street"));
                        System.out.println("\t\t City: " +  
                                     address.getString("city"));
                        System.out.println("\t\t County: " + 
                                     address.getString("county"));
                        System.out.println("\t\t Postcode: " + 
                                     address.getString("postcode"));
                        
                } catch (Exception e) {
                        System.out.println("Sorry an error occured " + 
                                      e.toString());
                        e.printStackTrace();
                }

        }

}

The first thing that this class does is to instantiate the EmployeeDMS,

EmployeeDMS dms = new EmployeeDMS();

This will cause the DMS to initialise the types defined for our SDO example. Next, the test harness uses the DMS to obtain a DataGraph for the Employee:

DataGraph dg = dms.getEmployee();

This DataGraph is then passed to the saveEmployeeToFile method which saves the contents of the DataGraph to a file called tmpXMLFile.xml.

dms.saveEmployeeToFile(dg, "tmpXMLFile.xml");

The result of this is that a new file is created with the following contents:

<?xml version="1.0" encoding="ASCII"?>
<regdeveloper:Employee xmlns:regdeveloper="http://www.regdeveloper.com">
  <name>John Hunt</name>
  <address country="GB">
    <street>12 No Street</street>
    <city>Nowhere</city>
    <county>Wiltshire</county>
    <postcode>SNnn nJG</postcode>
  </address>
  <employeeId>34255</employeeId>
</regdeveloper:Employee>

This is an XML file that contains the same information as was (programmatically_) created by the DMS.

Next, the test harness changes the name associated with the employee object within the DataGraph to “Denise Cooke” and re-saves the DataGraph to a different file name:

dg.getRootObject().setString("name", 
                             "Denise Cooke");
dms.saveEmployeeToFile(dg, "tmpXMLFile2.xml");

Note that the method setString is used to set the name of the root DataObject as name is a type of string. Also, note that the property name is used with the new value of the property. The new file created is presented below:

<?xml version="1.0" encoding="ASCII"?>
<regdeveloper:Employee xmlns:regdeveloper="http://www.regdeveloper.com">
  <name>Denise Cooke</name>
  <address country="GB">
    <street>12 No Street</street>
    <city>Nowhere</city>
    <county>Wiltshire</county>
    <postcode>SNnn nJG</postcode>
  </address>
  <employeeId>34255</employeeId>
</regdeveloper:Employee>

Note that this file is identical to the first, with the exception that the name has now been changed.

Finally, the test harness now obtains a DataGraph from the getEmployeeFromString method in the DMS and retrieves the root object from the DataGraph:

dg = dms.getEmployeeFromString();
DataObject employee = dg.getRootObject();

It now uses the accessor method to obtain the information held in the DataObject. In this case, it uses the getString method to obtain all the primitive string data, the getInt method to retrieve the single integer held in the DataObject and getDataObject to retrieve the DataObject associated with the employee DataObject.

Running the example

To execute the EmployeeSDOTestClient class we must ensure that the Tuscany jar files are on the class path and that we are at least using Java 5 SE. The output form this test application is presented below:

------------------------------
Creating EmployeeDMS
Defining SDO Types for DMS
Type Def'ns gen'd from: xml/data/employee.xsd
------------------------------
Programmatically Creating Data Objects
Created Data Objects
------------------------------
Saving SDO objects to file
Saved to file xml/data/tmpXMLFile.xml
Saving SDO objects to file
Saved to file xml/data/tmpXMLFile2.xml
------------------------------
Name: John Hunt
        Employee ID: 34255
        Address: 
                 Street: 12 No Street
                 City: Nowhere
                 County: Wiltshire
                 Postcode: SNnn nJG

Generating SDO classes

In the previous section, we have looked at how generic DataObjects can be used to represent data in a transportable, platform independent manner. Another approach is to generate custom SDO objects that will perform the same function but are semantically more meaningful. This can be done using the Tuscany projects Java Generator classes (see the abstract class JavaGenerator and its concrete subclasses Interface2JavaGenerator and XSD2JavaGenerator). For example, to generate Java classes directly from the XSD file presented earlier we can use the following command:

Java org.apache.tuscany.sdo.generate.XSD2JavaGenerator 
-targetDirectory tmp/sdo 
-javaPackage com.regdev xml/data/employee.xsd 

The output for this command is presented below:

 >>   Generating code
 >>   Generating packages
 >>   Generating package RegdevPackageImpl
 >>   Generating Java class com.regdev.impl.RegdevPackageImpl
 >>   Generating /TargetProject/com/regdev/impl/RegdevPackageImpl.java
 >>   Generating Java interface com.regdev.RegdevFactory
 >>   Generating /TargetProject/com/regdev/RegdevFactory.java
 >>   Generating Java class com.regdev.impl.RegdevFactoryImpl
 >>   Generating /TargetProject/com/regdev/impl/RegdevFactoryImpl.java
 >>   Generating Address
 >>   Generating Java interface com.regdev.Address
 >>   Generating /TargetProject/com/regdev/Address.java
 >>   Generating Java class com.regdev.impl.AddressImpl
 >>   Generating /TargetProject/com/regdev/impl/AddressImpl.java
 >>   Generating Employee Type
 >>   Generating Java interface com.regdev.EmployeeType
 >>   Generating /TargetProject/com/regdev/EmployeeType.java
 >>   Generating Java class com.regdev.impl.EmployeeTypeImpl
 >>   Generating /TargetProject/com/regdev/impl/EmployeeTypeImpl.java

This generates 4 classes in the specified com.regdev package within the tmp/sdo directory. These classes are:

com.regdev.impl.AddressImpl
com.regdev.impl.EmployeeTypeImpl
com.regdev.RegdevFactory
com.regdev.impl.RegdevPackageImpl

Uses these classes, we could now refactor the previous example to use the EmployeeType and Address classes explicitly.

SDO and SCA

Service Component Architecture or (SCA) is a set of specifications that describes a model for the construction of services. The Apache Tuscany project also provides an implementation of the SCA standard for the creation of operation SOA services. SDO is ideal as a compliment to the SCA standard as it provides a common way to access many different kinds of data, from many different sources. That is, SDO can provide the common data model used to share data between a client and a service – remember that an SDO model contains metadata that allows the data model to be self describing.

When used with SCA, SDO provides the common data representation for complex data that must be passed into the service as a parameter or returned as the result of that service. Such use of SDO does not require, or indeed preclude, use of the update facilities associated with SDO. However, this feature of SDO is not necessary for effective use within a service. Also, the use of a DMS is not required in the SOA scenario, although as mentioned earlier, using a DMS may be a useful pattern to follow within the client and/or the service.

SDO and JavaBeans

One thing that certainly came to my mind when I first looked at SDO was – isn’t this just JavaBeans with the in-built to be saved as an XML file. Actually, the answer is “no”. SDO goes beyond simple JavaBeans by incorporating a number of important features. First off is of course the metadata inherent to the DataObject that allows the data to be self describing. Another is the ability to navigate the graph of objects either use the API or by XPATH expressions. Added to this is the strong typing of the data model (based on the metadata), the inclusion of a change history, validation of data changes (and constraints upon those changes) and the application of relationship integrity. The end result is a very powerful model for representing data which indeed does go beyond simple JavaBeans.

Summary

Service Data Objects or SDO offers a platform and language independent format for exchanging data between applications. This standardised data format has been around for some time; however, its use within SOA represents a widening of its appeal. In combination with SCA, it offers a powerful, data transport mechanism that increases the simplicity and accessibility of services.

Resources

Boost IT visibility and business value

More from The Register

next story
The Return of BSOD: Does ANYONE trust Microsoft patches?
Sysadmins, you're either fighting fires or seen as incompetents now
Microsoft refuses to nip 'Windows 9' unzip lip slip
Look at the shiny Windows 8.1, why can't you people talk about 8.1, sobs an exec somewhere
Intel's Raspberry Pi rival Galileo can now run Windows
Behold the Internet of Things. Wintel Things
Linux Foundation says many Linux admins and engineers are certifiable
Floats exam program to help IT employers lock up talent
Microsoft cries UNINSTALL in the wake of Blue Screens of Death™
Cache crash causes contained choloric calamity
Eat up Martha! Microsoft slings handwriting recog into OneNote on Android
Freehand input on non-Windows kit for the first time
Linux kernel devs made to finger their dongles before contributing code
Two-factor auth enabled for Kernel.org repositories
prev story

Whitepapers

Implementing global e-invoicing with guaranteed legal certainty
Explaining the role local tax compliance plays in successful supply chain management and e-business and how leading global brands are addressing this.
7 Elements of Radically Simple OS Migration
Avoid the typical headaches of OS migration during your next project by learning about 7 elements of radically simple OS migration.
BYOD's dark side: Data protection
An endpoint data protection solution that adds value to the user and the organization so it can protect itself from data loss as well as leverage corporate data.
Consolidation: The Foundation for IT Business Transformation
In this whitepaper learn how effective consolidation of IT and business resources can enable multiple, meaningful business benefits.
High Performance for All
While HPC is not new, it has traditionally been seen as a specialist area – is it now geared up to meet more mainstream requirements?