Understanding EclipseLink, 2.5
  Go To Table Of Contents
 Search
 PDF

About Object-XML Mapping

The Object-XML component, supplied by EclipseLink, enables you to efficiently bind Java classes to XML schemas. Object-XML implements JAXB, enabling you to provide your mapping information through annotations and providing support for storing the mappings in XML format.

JAXB (Java Architecture for XML Binding—JSR 222) is the standard for XML Binding in Java. JAXB covers 100 percent of XML Schema concepts. EclipseLink provides a JAXB implementation with many extensions.

When using EclipseLink Object-XML as the JAXB provider, no metadata is required to convert your existing object model to XML. You can supply metadata (using annotations or XML) if you want to fine-tune the XML representation.

Object-XML includes many advanced mappings that let you handle complex XML structures without having to mirror the schema in your Java class model.

For more information, see Developing JAXB Applications Using EclipseLink MOXy.

The following sections describe many of these features.

Using EclipseLink Object-XML as the JAXB Provider

To use Object-XML as your JAXB provider, you must identify the entry point to the JAXB runtime. This entry point is the EclipseLink JAXBContextFactory class.

Create a text file called jaxb.properties and enter the path to the JAXBContextFactory class as the value of the javax.xml.bind.context.factory context parameter, for example:

javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory 

The jaxb.properties file must appear in the same package as the domain classes.

Understanding Object-XML Architecture

In the sample Object-XML architecture illustrated in Figure 2-2, the starting point is an XML schema. A binding compiler binds the source schema to a set of schema-derived program classes and interfaces. JAXB-annotated classes within the application are generated either by a schema compiler or the result of a developer adding JAXB annotations to existing Java classes. The application can either marshal data to an XML document or unmarshal the data to a tree of content objects. Each content object is an instance of either a schema derived or an existing program element mapped by the schema generator and corresponds to an instance in the XML.

Figure 2-2 A Sample Object-XML Architecture

Process in an Object-XML project.
Description of "Figure 2-2 A Sample Object-XML Architecture"

JAXB Contexts and JAXB Context Factories

The JAXBContextFactory class is the entry point into the EclipseLink JAXB runtime. It provides the required factory methods and can create new instances of JAXBContext objects.

The JAXBContextFactory class has the ability to:

  • Create a JAXBContext object from an array of classes and a properties object

  • Create a JAXBContext object from a context path and a classloader

The JAXBContext class provides the client's entry point to the JAXB API. The JAXBContext class is responsible for interpreting the metadata, generating schema files, and for creating instances of these JAXB objects: Marshaller, Unmarshaller, Binder, Introspector, and Validator.

Object-XML offers several options when creating the JAXBContext object. You have the option of booting from:

  • A list of one or more JAXB-annotated classes

  • A list of one or more EclipseLink XML Bindings documents defining the mappings for your Java classes

  • A combination of classes and XML Bindings

  • A list of context paths

  • A list of session names, referring to EclipseLink sessions defined in sessions.xml

Serving Metadata for Object-XML

In addition to the input options described in JAXB Contexts and JAXB Context Factories, Object-XML provides the concept of a MetadataSource object. This object lets you to store mapping information outside of your application and retrieve it when the application's JAXBContext object is being created or refreshed. For information on implementing MetadataSource, see Developing JAXB Applications Using EclipseLink MOXy.

About XML Bindings

EclipseLink enables you to use all of the standard JAXB annotations. In addition to the standard annotations, EclipseLink offers another way of expressing your metadata—the EclipseLink XML Bindings document. Not only can XML Bindings separate your mapping information from your actual Java class, it can also be used for more advanced metadata tasks such as:

  • Augmenting or overriding existing annotations with additional mapping information.

  • Specifying all mappings information externally, without using Java annotations.

  • Defining your mappings across multiple Bindings documents.

  • Specifying virtual mappings that do not correspond to concrete Java fields.

For more information, see Developing JAXB Applications Using EclipseLink MOXy.

Specifying EclipseLink Object-XML Mappings Using eclipselink-oxm.xml

You can use Java annotations to specify JAXB features in your projects. In addition to Java annotations, EclipseLink provides an XML mapping configuration file called eclipselink-oxm.xml. This mapping file contains the standard JAXB mappings and configuration options for advanced mapping types. You can use the eclipselink-oxm.xml file in place of or to override JAXB annotations in source code.


NoteNote:

Using this mapping file will enable many advanced features but it can prevent the model from being portable to other JAXB implementations.


About Object-XML Data Type Mappings

XML mappings transform object data members to the XML elements of an XML document whose structure is defined by an XML Schema Document (XSD). You can map the attributes of a Java object to a combination of XML simple and complex types using a wide variety of XML mapping types.

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 in using Object-XML is that when mapping an object attribute to an XML document, XPath statements are used to specify the location of the XML data.

EclipseLink stores XML mappings for each class in the class descriptor. EclipseLink uses the descriptor to instantiate objects mapped from an XML document and to store new or modified objects as XML documents.

EclipseLink provides XML mappings that are not defined in the JAXB specification. Some of the Object-XML extensions are available through EclipseLink annotations; others require programmatic changes to the underlying metadata.

For more information on these mappings, see Developing JAXB Applications Using EclipseLink MOXy.

Querying Objects by XPath

In addition to using conventional Java access methods to get and set your object's values, EclipseLink Object-XML also lets you access values using an XPath statement. There are special APIs on EclipseLink's JAXBContext object that enable you to get and set values by XPath. For more information, see Developing JAXB Applications Using EclipseLink MOXy.