Jump to: navigation, search

Difference between revisions of "EclipseLink/Examples/MOXy/EclipseLink-OXM.XML"

(How to use eclipselink-orm.xml)
m (XML Configuration)
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
EclipseLink supports the use of JAXB with externalized mapping files. These mapping files support specifying the Object-XML binding of JAXB 2.2 annotations plus many of the advanced mapping and configuration options provided by EclipseLink MOXy.
+
[[Category:EclipseLink/Examples/MOXy|EclipseLink-OXM.XML]]
  
__TOC__
+
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.
  
== How to use eclipselink-orm.xml ==
+
'''Note: Usage of this mapping file will enable many advanced features but may prevent the persistence unit from being portable to other JAXB implementations'''
  
In order to specify the mappings between domain objects and an XSD an application must provide:
+
== XML Configuration ==
# An XML mapping file per package
+
 
# A JAXB.properties file specifying EclipseLink as the JAXB implementation
+
The [http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/trunk/moxy/org.eclipse.persistence.moxy/resource/org/eclipse/persistence/jaxb/eclipselink_oxm_2_3.xsd EclipseLink OXM schema (eclipselink_oxm_2_3.xsd)] can be used with the following header to define JAXB and EclipseLink's advanced mappings.
  
'''Example Mapping File''': /model/eclipselink-oxm.xml
 
 
<source lang="xml">
 
<source lang="xml">
<?xml version="1.0" encoding="US-ASCII"?>
+
<?xml version="1.0"?>
<xml-bindings  
+
<xml-bindings
        xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
+
xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_1.xsd"
+
xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/oxm http://www.eclipse.org/eclipselink/xsds/eclipselink_oxm_2_3.xsd"
        version="2.1">
+
version="2.3">
    <java-types>
+
        <java-type name="mynamespace.Person">
+
            <xml-root-element name="person"/>
+
            <java-attributes>
+
                <xml-element java-attribute="name" />
+
            </java-attributes>
+
        </java-type>
+
    </java-types>
+
 
</xml-bindings>
 
</xml-bindings>
 
</source>
 
</source>
  
=== Specifying the EclipseLink MOXy Runtime ===
+
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.
 +
 
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 
 +
== 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:
 +
 
 +
<source lang="java">
 +
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"));
 +
</source>
 +
 
 +
Create the properties object to pass to the JAXBContext:
 +
 
 +
<source lang="java">
 +
Map<String,Object> properties = new HashMap<String,Object>();
 +
properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, metadata);
 +
</source>
 +
 
 +
Create the JAXBContext:
 +
 
 +
<source lang="java">
 +
JAXBContext.newInstance("example.order:example.customer", aClassLoader, properties);
 +
</source>
 +
 
 +
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.
  
To specify the EclipseLink MOXy (JAXB) runtime should be used you need to add a file called jaxb.properties in the same package as the domain classes with the following entry.
 
 
<source lang="text">
 
<source lang="text">
 
javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory
 
javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory
 
</source>
 
</source>
  
=== Specifying the mapping files ===
+
== Example using eclipselink-oxm.xml ==
 +
 
 +
The [[EclipseLink/Examples/MOXy/GettingStarted/ExternalizedMetadata | 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 order to configure EclipseLink MOXy to use the mapping files ...
+
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.

Latest revision as of 13:17, 6 June 2011


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.