Using XML Bindings

In addition to standard JAXB 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:

The root of the XML Bindings document. This is also where you can define top-level properties for your JAXB system, such as the package-name of your classes, specify a default xml-accessor-type, and so on.

<xml-schema>

Defines properties related to the schema-level of your JAXB system. Corresponds to the JAXB @XmlSchema annotation.

<java-types>

Defines mapping information for each of your Java classes.

<xml-enums>

Defines Java enumerations that can be used with your Java types.

<xml-registries>

Defines an ObjectFactory for use in your JAXB system.

Bootstrapping with XML Bindings

When instantiating a JAXBContext, links to Bindings documents are passed in via the properties parameter, using a special key, JAXBContextProperties.OXM_METADATA_SOURCE. The value of this key will be a handle to the Bindings document, in the form of one of the following:

java.io.File

java.io.InputStream

java.io.Reader

java.net.URL

javax.xml.stream.XMLEventReader

javax.xml.stream.XMLStreamReader

javax.xml.transform.Source

org.w3c.dom.Node

org.xml.sax.InputSource

To bootstrap from multiple XML Bindings documents:

Maps of the above inputs are supported, keyed on Java package name.

Lists of the above inputs are acceptable as well (<xml-bindings> must have package attribute).

Using XML Bindings with Annotations

The most typical use of an XML Bindings document is in conjunction with JAXB annotations. You may have situation where you are not permitted to edit your Java domain classes, but want to add additional mapping functionality. Or, you may wish to avoid importing any EclipseLink code into your domain model, but still take advantage of MOXy's advanced mapping features. When Bindings metadata is provided during context creation, its mapping information will be combined with any JAXB annotation information.

Understanding Override Rules

When multiple sources of metadata are encountered for the same package, a unified set of mappings will be created by merging the complete set of metadata. First, the annotations from the Java class will be processed, and then any XML Bindings information will be applied. The order that Bindings are specified is relevant; values in subsequent documents will override the ones defined in previous ones.

The following rules will be used for merging:

xml-schema

For values such as namespace, elementform, attributeform, the later file will override.

The list of namespace declarations from XmlNs will be merged into a single list containing all entries from all files.

In the case of conflicting entries (the same prefix bound to multiple namespaces), the last file will override the declarations from previous files.

java-types

The merged bindings will contain all unique java-type entries from all bindings files.

If the same java-type occurs in multiple files, any values that are set in the later file will override values from the previous file.

Properties on each java-type will be merged into a unified list. If the same property is referenced in multiple files, this will be an exception case.

Class-level XmlJavaTypeAdpater entries will be overridden if specified in a later bindings file.

Class-level XmlSchemaTypes will create a merged list. If an entry for the same type is listed in multiple bindings files at this level, the last file's entry will override all previous ones.

xml-enums

The merged bindings will contain all unique xml-enum entries from all bindings files.

For any duplicated java-enums, a merged list of XmlEnumValues will be created. If an entry for the same enum facet occurs in multiple files, the last file will override the value for that facet.

xml-java-type-adapters

Package-level Java type adapters will be merged into a single list. In the case that an adapter is specified for the same class in multiple files, the last file's entry will win.

xml-registries

Each unique XmlRegistry entry will be added to the final merged list of XmlRegistries.

For any duplicated XmlRegistry entries, a merged list of XmlElementDecls will be created.

In the case that an XmlElementDecl for the same XmlRegistry class appears in multiple bindings files, that XmlElementDecl will be replaced with the one from the later bindings.

xml-schema-types

XmlSchemaType entries will be merged into a unified list.

In the case that an XmlSchemaType entry for the same java-type appears at the package level in multiple bindings files, the merged bindings will only contain the entry for the last one specified.

Using Complete Metadata

If you would like to store all of your metadata in XML Bindings and ignore any JAXB annotations in your Java class, you can include the xml-mapping-metadata-complete attribute in the <xml-bindings> element of your Bindings document. Default JAXB mappings will still be generated (the same as if you were using a completely un-annotated class with JAXB), and then any mapping data defined in the XML Bindings will be applied.

This could be used, for example, to map the same Java class to two completely different XML representations: the annotations on the actual Java class would define the first XML representation, and then a second XML representation could be defined in an XML Bindings document with xml-mapping-metadata-complete="true". This would essentially give you a "blank canvas" to remap your Java class.

If you would like to ignore the default mappings that JAXB generates, you can specify xml-accessor-type="NONE" in your <java-type> element. Using this approach, only mappings that are explicitly defined in Bindings document will be applied.

Using the Customer example from above, the following examples demonstrate the XML representations that will be generated when using xml-mapping-metadata-complete:

Specifying xml-accessor-type="NONE" will prevent any default mappings from being generated

The XML representation contains only the mappings defined in the XML Bindings document

Using Virtual Mappings

XML Bindings can also be used to specify virtual mappings – mappings that do not correspond to a concrete Java field. For example, you might want to use a HashMap as the underlying structure to hold data for certain mappings. For information on using Virtual Mappings, see "Using Virtual Access Methods".