EclipseLink/Examples/MOXy/EclipseLink-OXM.XML

In addition to using Java annotations, EclipseLink provides an XML mapping configuration file called eclipselink-oxm.xml. This mapping file can be used in place of or to override JAXB annotations in source. In addition to allowing all of the standard JAXB mapping capabilities it also includes advanced mapping types and options.

Note: Usage of this mapping file will enable many advanced features but may prevent the persistence unit from being portable to other JAXB implementations

XML Configuration

The EclipseLink OXM schema (eclipselink_oxm_2_3.xsd) can be used with the following header to define JAXB and EclipseLink's advanced mappings.

<?xml version="1.0"?>
<xml-bindings
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/oxm http://www.eclipse.org/eclipselink/xsds/eclipselink_oxm_2_3.xsd"
	version="2.3">
</xml-bindings>

EclipseLink automatically resolves the xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm" to its internally packaged schema. The following header will not cause the parser to attempt to access the XSD from the web. Using this however will require you to add the eclipselink_oxm_2_3.xsd to your IDE's catalog in order to have XML completion available.

<?xml version="1.0"?>
<xml-bindings
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	version="2.3">
</xml-bindings>

Configuring usage in JAXBContext

A JAXBContext can use one of these mapping files per Java package. The mapping files are passed to the JAXBContext through the properties parameter.

Specify the externalized metadata:

Map<String, Source> metadata = new HashMap<String,Source>();
metadata.put("example.order", new StreamSource("order-metadata.xml"));
metadata.put("example.customer", new StreamSource("customer-metadata.xml"));

Create the properties object to pass to the JAXBContext:

Map<String,Object> properties = new HashMap<String,Object>();
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, metadata);

Create the JAXBContext:

JAXBContext.newInstance("example.order:example.customer", aClassLoader, properties);

To specify the EclipseLink MOXy JAXB implementation you need to have a jaxb.properites with the following entry in at least one of the packages.

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

Example using eclipselink-oxm.xml

The Customer JAXB Example using XML metadata illustrates how XML can be used exclusively (no annotations) to configure JAXB usage. This example includes the usage of this EclipseLink specific JAXB mapping XML file.

EclipseLink OXM Features

In addition to supporting all capabilities of JAXB's annotations with similarly named elements and attributes the EclipseLink mapping file also offers many additional configuration capabilities.