Introduction to TopLink Object-XML Mapping
By Blaise Doughan

Object-XML Impedance Mismatch

XML is a common format for the exchange of data. XML is human readable and it is portable making it the perfect format for exchanging data between applications running on different platforms (i.e. Web Services).

However, for many applications objects are the preferred programmatic representation not XML. XML has become pervasive in the modern software world, so to work at the object-level, the data needs to be converted to object form. Analogous to the better-known object-relational impedance mismatch, a similar mismatch also exists with objects and XML.

Why not just use DOM, SAX, or StAX?

These APIs only provide low-level access to XML data and for many applications; a higher level of object abstraction is required. Even though DOM provides an in memory tree structure that can be navigated these are not the domain objects that developers are used to dealing with.

Example

In this example, a small schema fragment is examined to demonstrate things to be wary of when interacting directly with XML. When large documents are used these types of issues cause the code to access the XML data to be complex and cumbersome.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
	xmlns="urn:customer-example"
	targetNamespace="urn:customer-example"
	elementFormDefault="unqualified">
	<xs:element name="customer">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="personal-info">
					<xs:complexType>
						<xs:sequence>
							<xs:element name="first-name" type="xs:string"/>
							...
							<xs:element name="date-of-birth" type="xs:date"/>
						</xs:sequence>
					</xs:complexType>
				</xs:element>
				<xs:element ref="contact-info"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	...
</xs:schema>

In this example there are several details we need to know from the XML schema just to retrieve the first name data. First we need to know to access the first-name element, which is nested below the personal-info element that , which is nested below the customer element. This information cannot be obtained from the XML document. Also we need to know that the date-of-birth element is typed as an XML schema date. This means that the String that we get back from the XML parser will be in the following format yyyy-mm-dd. We can then use that information to correctly convert the String to a java.util.Calendar.

There are also some XML schema rules that we need to be aware of. In the XML schema fragment shown above the elementFormDefault attribute is set to "unqualified" and a target namespace is set. This means that globally declared elements must be namespace qualified and locally declared elements must not be namespace qualified.

The low level parser APIs are cumbersome to use and couple application code with XML schema details. This code is difficult to maintain if any changes are made to the schema.

What about JAXB?

JAXB allows the user to interact with XML using domain-like objects. Unlike DOM objects the JAXB content model provides insight into the XML document based on the XML schema. If the XML schema defines XML documents that contain customer information you will see objects like Customer, Address, and PhoneNumber in your content model that reflect the corresponding types in the XML schema. One class is generated for every type found in the XML schema.

With the XML data in object form it becomes easier to navigate the data structure, you can discover what attributes a content class has and navigate them accordingly. The content model also solves the typing problem by using the rules in the specification XML data to convert to the corresponding types in Java. JAXB hides many of the XML schema rules. The logic for handling such things as namespace qualification are encapsulated in the artifacts generated by the JAXB compiler.

However, there are a number of limitations when using JAXB. With JAXB you must start from an XML schema. The XML schema is the input to the JAXB compiler and a set of model classes are output based on the specification. The generated content classes may only be used to produce documents that conform to a single XML schema, a new JAXB content model must be generated for each XML representation.

If a change is made to the XML schema, then the corresponding content classes need to be regenerated. This impacts each application that makes use of these content classes since they need to be updated. Existing Java classes cannot be used with JAXB to represent a schema, only the generated classes can be used and may not be changed.

While JAXB is easier to use than the standard XML APIs there are better, more flexible ways of interacting with XML data.

Introducing TopLink's Object to XML Functionality

TopLink includes a JAXB 1.0 implementation as part of its object to XML support, but with TopLink you are able to go well beyond what you can do with JAXB. TopLink includes support for mapping your existing Java objects to XML. These mappings use similar principles as TopLink's object-to-relational mappings. A visual mapping editor called the TopLink Mapping Workbench can be used to create and customize these mappings. TopLink provides developers maximum flexibility with the ability to control how their object model is mapped to an XML schema.

There are many advantages to having control over your own object model:

• The domain classes can be designed specifically for your application using the appropriate patterns and practices.
• Can instantiate objects in a way that is appropriate to your application (i.e. using the default constructor). JAXB requires that objects in the content model are instantiating using a generated factory class.
• Can control your own class path dependencies. Most JAXB implementations put vendor specific code in the generated classes that add class path dependencies to your application.

One of TopLink's key advantages is that the mapping information is stored externally and does not require any changes to the Java classes or XML schema. This means that you may map your domain objects to more than one schema or if your schema changes you can simply update the mapping metadata instead of modifying your domain classes.

The objects produced by the TopLink JAXB compiler are essentially POJOs, the only difference is that they implement the necessary interfaces required by the JAXB specification. The TopLink JAXB compiler produces meta-data that allows the generated classes and mappings to be customized with the TopLink Mapping Workbench. Even with the custom mappings the JAXB run-time API can still be used to marshal and unmarshal objects

The base concept is that classes are mapped to complex types, object relationships map to XML elements, and simple attributes map to text nodes and XML attributes. The real power is that when mapping an object attribute to an XML document, XPath statements are used to specify the location of the XML data. The following is a sample of how this can be used.

TopLink Example

In this example using an XPath statement in the mapping allows us to avoid mapping an object to the personal-info element.

In this example the XPath contains positional information, this allows the user to place significance on an element based on the position it occurs within a document. TopLink also supports storing the values from elements with the same name in a Java Collection.

This just highlights one of the seven mappings provided by TopLink which along with the three data converter plug-ins provide enormous flexibility and productivity advantages for working with XML data.

Summary and Next Steps

TopLink provides powerful and flexible object-XML capabilities that complement the existing object-relational mapping functionality many are already familiar with. While TopLink goes well-beyond JAXB 1.0 to provide developers with a rich object-level programmatic environment to work with XML data, it is important to note that TopLink is JAXB compliant. Many of the value added features are being proposed as part of JAXB 2.0 JSR 222 on which the author is a member of the expert committee.

Download Oracle TopLink 10g Release 3 (10.1.3)

The object-to-XML functionality is included in the TopLink 10g Release 3 (10.1.3) download.

Getting started with TopLink OXM

If you would like to find out more about TopLink OXM functionality, the following page provides a complete overview, including a step-by-step guide to try out our examples and how to create object-to-XML mappings for yourself:

http://www.oracle.com/technology/products/ias/toplink/technical/tips/ox/index.htm

Try the Examples

There are two TopLink OXM examples included with TopLink's Foundation examples. The first example demonstrates JAXB 1.0 support TopLink provides, and the second example shows how to use the new object-to-XML mappings to map an existing object model to an XML Schema.

http://www.oracle.com/technology/products/ias/toplink/examples/index.html

Are you using Web Services?

Learn how to use Oracle TopLink as a custom serialization mechanism for a Web service.

http://www.oracle.com/technology/products/ias/toplink/technical/tips/jaxRpc11/index.htm

Author Bio

Blaise Doughan is a senior software engineer and is the team leader for TopLink's OXM project. He is a member of JSR 222 JAXB 2.0 expert committee.