Introduction to XML Mappings (ELUG)

1 XML Mapping Types
2 XML Mapping Concepts
3 XML Direct Mapping
4 XML Composite Direct Collection Mapping
5 XML Composite Object Mapping
6 XML Composite Collection Mapping
7 XML Any Object Mapping
8 XML Any Collection Mapping
9 XML Transformation Mapping
10 XML Object Reference Mapping
11 XML Collection Reference Mapping
12 XML Binary Data Mapping
13 XML Binary Data Collection Mapping
14 XML Fragment Mapping
15 XML Fragment Collection Mapping
16 XML Choice Object Mapping
17 XML Choice Collection Mapping
18 XML Any Attribute Mapping

XML Mapping Types

EclipseLink supports the XML mappings listed in this table

Mapping Type	Description	EclipseLink Workbench	Java
XML direct mapping	Map a simple object attribute to an XML attribute or text node.
XML composite direct collection mapping	Map a collection of simple object attributes to XML attributes or text nodes.
XML composite object mapping	Map any attribute that contains a single object to an XML element. The EclipseLink runtime uses the descriptor for the referenced object to populate the contents of that element.
XML composite collection mapping	Map an attribute that contains a homogenous collection of objects to multiple XML elements. The EclipseLink runtime uses the descriptor for the referenced object to populate the contents of those elements.
XML any object mapping	The any object XML mapping is similar to the composite object XML mapping (see XML Composite Object Mapping), except that the reference object may be of different types (including `String`), not necessarily related to each other through inheritance or a common interface.
XML any collection mapping	The any collection XML mapping is similar to the composite collection XML mapping (see XML Composite Collection Mapping) except that the referenced objects may be of different types (including `String`), not necessarily related to each other through inheritance or a common interface.
XML transformation mapping	Create custom mappings where one or more XML nodes can be used to create the object to be stored in a Java class's attribute.
XML object reference mapping	Map a given element in an XML document to another element in that same XML document using key(s). Use this mapping when several objects reference the same instance of another object.
XML collection reference mapping	This mapping is similar to the XML object reference mapping (see XML Object Reference mapping), except that it deals with collections instead of single objects. Use this mapping when several objects reference the same instance of another object.
XML binary data mapping	Handle binary data: this mapping maps binary data in the object model to XML. Use this mapping to enable writing of binary data directly as inline binary data (base64 BLOB), or passing through as a MtOM or SwaRef attachment.
XML binary data collection mapping	This mapping is similar to the XML binary data mapping (see XML Binary Data mapping), except that it maps a collection of binary data in the object model to XML.
XML fragment mapping	Keep a part of an XML tree as a node.
XML fragment collection mapping	This mapping is similar to the XML fragment mapping (see XML Fragment mapping), except that it allows you to keep a part of an XML tree as a collection of nodes.
XML choice object mapping	Map a single attribute to a number of different elements in an XML document. Use this mapping to map to single choices or substitution groups in an XML schema.
XML choice collection mapping	This mapping is similar to the XML choice object mapping (see XML Choice Object mapping), except that you use it to handle reading and writing of XML documents containing a collection of choice or substitution group elements.
XML any attribute mapping	Map to an attribute in an object to any XML attributes contained on a specific element in the XML document.

XML Mapping Concepts

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.

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 an XML document.

To configure XML mappings, we recommend that you use the Workbench to set the descriptor properties and configure the mappings.

This section describes concepts unique to EclipseLink XML mappings, including the following:

Mapping to Simple and Complex Types
Mapping Order
Path Support
xsd:list and xsd:union Support
xs:any and xs:anyType Support
jaxb:class Support
Typesafe Enumeration Support
Mapping Extensions
Substitution Groups
Mixed Content Mapping
Key On Source-Based Mapping Support
XML Adapter

Mapping to Simple and Complex Types

Consider the XML document shown in this example:

XML Document

<EMPLOYEE ID="123">
    <NAME>Jane Doe</NAME>
    <ADDRESS>

        <STREET>123 Any St.</STREET>
        <CITY>MyCity</CITY>
    </ADDRESS>
</EMPLOYEE>

In general, using EclipseLink XML mappings, you can map a Java class to a simple type (such as NAME) or to a complex type (such as ADDRESS).

Specifically, you can map a Java object's simple attributes to XML attributes (such as ID) and text nodes (such as NAME). You can also map a Java object's relationships to XML elements (such as ADDRESS).

This table summarizes the XML simple and complex types supported by each EclipseLink XML mapping.

XML Mapping Support for XML Simple and Complex Types

Mapping	XML Attribute	XML Text Node	XML Element
XML direct
XML composite direct collection
XML composite object
XML composite collection
XML any object
XML any collection
XML transformation
XML object reference
XML collection reference
XML binary data
XML binary data collection
XML fragment collection
XML fragment collection
XML choice collection
XML choice collection
XML any attribute

Mapping Order

Unlike relational database mappings, the order in which mappings are persisted in XML is significant.

The order in which you define XML mappings in EclipseLink (whether in the Workbench or in Java code) including the order in which you define mapping components such as Transformers (see XML Transformation Mapping) is reflected in the order, in which EclipseLink persists data in an XML document.

XPath Support

EclipseLink uses XPath statements to efficiently map the attributes of a Java object to locations in an XML document.

The following are main characteristics of XPath:

Each XPath statement is relative to the context node specified in the descriptor.
The XPath may contain node type, path, and positional information.
The XPath is specified on a mapping using the setXPath method.

For more information about using XPath with XML mappings, see Mappings and XPath.

xsd:list and xsd:union Support

You can use XML direct (see XML Direct Mapping) and composite direct collection (see XML Composite Direct Collection Mapping) mappings, as well as their subclasses, to map to xsd:list and xsd:union types in an XML document.

For more information, see Mappings and xsd:list and xsd:union Types.

xs:any and xs:anyType Support

In an XML schema, you can define elements and complex types that correspond to any data type using xs:any and xs:anyType. You can map objects to such elements and complex types using XML mappings XMLAnyObjectMapping and XMLAnyCollectionMapping.

This table lists the XML mappings to use with common applications of xs:any and xs:anyType. For more details, see the specified XML mapping type.

XML Mappings and XML Schema xs:any and xs:anyType

Use XML Mapping... To Map XML Schema Definition...

XML Any Object Mapping

Element with a single ¹ unnamed complex type specified as xs:any.

XML Any Collection Mapping

Element with an unnamed sequence ² of complex types specified as xs:any.

Element with a named sequence ² of complex types of type xs:anyType.Root element of type xs:anyType.

¹minOccurs and maxOccurs are both equal to 1.
²maxOccurs is greater than 1.

jaxb:class Support

You can configure an XML composite object mapping (see XML Composite Object Mapping) and its subclasses to accommodate jaxb:class customizations with the following XSD structures:

all
sequence
choice
group

For more information, see Mappings and the jaxb:class Customization.

Typesafe Enumeration Support

You can map a Java attribute to such a typesafe enumeration using the JAXBTypesafeEnumConverter with an XMLDirectMapping, XMLCompositeDirectCollectionMapping or their subclasses with XML documents.

For more information, see Mappings and JAXB Typesafe Enumerations

Mapping Extensions

If existing EclipseLink XML mappings do not meet your needs, you can create custom XML mappings using XML mapping extensions, including object type, serialized object, type conversion converters, and a simple type translator. For more information, see Mapping Converters and Transformers.

Key On Source-Based Mapping Support

EclipseLink XML support for key on source-based mapping lets you use one-to-one and one-to-many mappings to map a given element in an XML document to another element in that same XML document using key(s).

You use this mapping when several objects reference the same instance of another object.

Use the org.eclipselink.persistence.ox.mappings.XMLObjectReferenceMapping and XMLCollectionReferenceMapping for the key on source.

You configure this mappings using the deployment XML and a project class.

Substitution Groups

Substitution groups is a mechanism provided by the XML schema. Using substitution groups, you can substitute elements for other elements. For more information, see XML Schema Primer at http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/#SubsGroups.

Use EclipseLink XMLChoiceObjectMapping and XMLChoiceCollectionMapping to handle substitution groups.

JAXB handles substitution groups with the following annotations, for which EclipseLink provides support:

XmlElementRef - the use of this annotation has a number of constrains. For more information, see JAXB 2.0 API Reference at https://jaxb.dev.java.net/nonav/jaxb20-pfd/api/index.html
XmlElementRefs - this annotation contains one of more XmlElementRef annotations.

Through the use of the org.eclipse.persistence.oxm.mappings.converters.XMLRootConverter, EclipseLink enables the JAXBElement and the org.eclipse.persistence.oxm.XMLRoot to act not only like root-level elements, but child elements.

Mixed Content Mapping

To handle mixed content, such as reading in text nodes as strings, use EclipseLink XMLAnyCollectionMapping. Enable this functionality through the setMixedContent method.

XML Adapter

EclipseLink supports the use of the javax.xml.bind.annotation.adapters.XmlAdapter<ValueType,BoundType> and its subclasses, which allow for arbitrary Java classes to be used with JAXB.

The XmlAdapter enables adaptation of a Java type for custom marshaling through its marshal and unmarshal methods.

For more information, refer to JAXB 2.0 Specification at https://jaxb.dev.java.net/nonav/jaxb20-pfd/api/index.html

XML Direct Mapping

XML direct mappings map a Java attribute directly to XML text nodes. You can use an XML direct mapping in the following scenarios:

Mapping to a Text Node
Mapping to an Attribute
Mapping to a Specified Schema Type
Mapping to a List Field with an XML Direct Mapping
Mapping to a Union Field with an XML Direct Mapping
Mapping to a Union of Lists with an XML Direct Mapping
Mapping to a Union of Unions with an XML Direct Mapping
Mapping with a Simple Type Translator

See Configuring an XML Direct Mapping for more information.

Note: Do not confuse an XML direct mapping with a relational direct-to-XMLType mapping (see Direct-to-XMLType Mapping).

Mapping to a Text Node

This section describes using an XML direct mapping when doing the following:

Mapping to a Simple Text Node
Mapping to a Text Node in a Simple Sequence
Mapping to a Text Node in a Subelement
Mapping to a Text Node by Position

Mapping to a Simple Text Node

Given the XML schema in the Schema for XML Direct Mapping to Simple Text Node example, the XML Direct Mapping to Simple Text Node figure illustrates an XML direct mapping to a simple text node in a corresponding XML document. The Java for XML Direct Mapping to Simple Text Node example shows how to configure this mapping in Java.

Schema for XML Direct Mapping to Simple Text Node

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="phone-number" type="xsd:string"/>
</xsd:schema>

XML Direct Mapping to Simple Text Node

Java for XML Direct Mapping to Simple Text Node

XMLDirectMapping numberMapping = new XMLDirectMapping();
numberMapping.setAttributeName("number");
numberMapping.setXPath("text()");

Mapping to a Text Node in a Simple Sequence

Given the XML schema in the Schema for XML Direct Mapping to a Text Node in a Simple Sequence example, the XML Direct Mapping to a Text Node in a Simple Sequence figure illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document. The Java for XML Direct Mapping to a Text Node in a Simple Sequence example shows how to configure this mapping in Java.

Schema for XML Direct Mapping to a Text Node in a Simple Sequence

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>
            <xsd:element name="first-name" type="xsd:string"/>
            <xsd:element name="last-name" type="xsd:string"/>
        </xsd:sequence>

    </xsd:complexType>
</xsd:schema>

XML Direct Mapping to a Text Node in a Simple Sequence

Java for XML Direct Mapping to a Text Node in a Simple Sequence

XMLDirectMapping firstNameMapping = new XMLDirectMapping();
firstNameMapping.setAttributeName("firstName");
firstNameMapping.setXPath("first-name/text()");

XMLDirectMapping lastNameMapping = new XMLDirectMapping();
lastNameMapping.setAttributeName("lastName");
lastNameMapping.setXPath("last-name/text()");

Mapping to a Text Node in a Subelement

Given the XML schema in the Schema for XML Direct Mapping to a Text Node in a Subelement example, the XML Direct Mapping to a Text Node in a Subelement figure illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document. The Java for XML Direct Mapping to a Text Node in a Subelemen example shows how to configure this mapping in Java.

Schema for XML Direct Mapping to a Text Node in a Subelement

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="personal-info">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="first-name" type="xsd:string"/>
                        <xsd:element name="last-name" type="xsd:string"/>
                    <xsd:sequence>

                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

XML Direct Mapping to a Text Node in a Subelement

Java for XML Direct Mapping to a Text Node in a Subelement

XMLDirectMapping firstNameMapping = new XMLDirectMapping();
firstNameMapping.setAttributeName("firstName");
firstNameMapping.setXPath("personal-info/first-name/text()");

XMLDirectMapping lastNameMapping = new XMLDirectMapping();
lastNameMapping.setAttributeName("lastName");
lastNameMapping.setXPath("personal-info/last-name/text()");

Mapping to a Text Node by Position

Given the XML schema in the Schema for XML Direct Mapping to Text Node by Position exampple, the XML Direct Mapping to Text Node by Position figure illustrates an XML direct mapping to a text node by position in a corresponding XML document. The Java for XML Direct Mapping to Text Node by Position example shows how to configure this mapping in Java.

' Schema for XML Direct Mapping to Text Node by Position

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>
            <xsd:element name="name" type="xsd:string" maxOccurs="2"/>
        </xsd:sequence>

    </xsd:complexType>
</xsd:schema>

XML Direct Mapping to Text Node by Position

' Java for XML Direct Mapping to Text Node by Position

XMLDirectMapping firstNameMapping = new XMLDirectMapping();
firstNameMapping.setAttributeName("firstName");
firstNameMapping.setXPath("name[1]/text()");

XMLDirectMapping lastNameMapping = new XMLDirectMapping();
lastNameMapping.setAttributeName("lastName");
lastNameMapping.setXPath("name[2]/text()");

Mapping to an Attribute

Given the XML schema in this example, the XML Direct Mapping to an Attribute figure illustrates an XML direct mapping to a text node by position in a corresponding XML document. The Java for XML Direct Mapping to an Attribute exampple shows how to configure this mapping in Java.

Schema for XML Direct Mapping to an Attribute

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:attribute name="id" type="xsd:integer"/>
    </xsd:complexType>

</xsd:schema>

XML Direct Mapping to an Attribute

Java for XML Direct Mapping to an Attribute

XMLDirectMapping idMapping = new XMLDirectMapping();
idMapping.setAttributeName("id");
idMapping.setXPath("@id");

Mapping to a Specified Schema Type

In most cases, EclipseLink can determine the target format in the XML document. However, there are cases where you must specify which one of a number of possible targets EclipseLink should use. For example, a java.util.Calendar could be marshalled to a schema date, time, or dateTime node, or a byte[] could be marshalled to a schema hexBinary or base64Binary node.

Given the XML schema in this exmaple, the XML Direct Mapping to a Specified Schema Type figure illustrates an XML direct mapping to a text node by position in a corresponding XML document. The Java for XML Direct Mapping to a Specified Schema Type example shows how to configure this mapping in Java.

Schema for XML Direct Mapping to a Specified Schema Type

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>
            <xsd:element name="picture" type="xsd:hexBinary"/>
            <xsd:element name="resume" type="xsd:base64Binary"/>
        </xsd:sequence>

    </xsd:complexType>
</xsd:schema>

XML Direct Mapping to a Specified Schema Type

Java for XML Direct Mapping to a Specified Schema Type

XMLDirectMapping pictureMapping = new XMLDirectMapping();
pictureMapping.setAttributeName("picture");
pictureMapping.setXPath("picture/text()");
XMLField pictureField = (XMLField) pictureMapping.getField();
pictureField.setSchemaType(XMLConstants.HEX_BINARY_QNAME);

XMLDirectMapping resumeMapping = new XMLDirectMapping();
resumeMapping.setAttributeName("resume");
resumeMapping.setXPath("resume/text()");
XMLField resumeField = (XMLField) resumeMapping.getField();
resumeField.setSchemaType(XMLConstants.BASE_64_BINARY_QNAME);

Mapping to a List Field with an XML Direct Mapping

Given the XML schema in this exmaple, the XMLDirect Mapping to a List Field figure illustrates an XML direct mapping to an xsd:list type in a corresponding XML document when you represent the list in your object model as a String of white space delimited tokens. The Java for XML Direct Mapping to a List Field Node example shows how to configure this mapping in Java.

Schema for XML Direct Mapping to a List Field

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>

            <xsd:element name="tasks" type="tasks-type"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:simpleType name="tasks-type">
        <xsd:list itemType="xsd:string"/>
    </xsd:simpleType>

</xsd:schema>

XMLDirect Mapping to a List Field

Java for XML Direct Mapping to a List Field Node

XMLDirectMapping tasksMapping = new XMLDirectMapping();
tasksMapping.setAttributeName("tasks");
XMLField myField = new XMLField("tasks/text()"); // pass in the XPath

myField.setUsesSingleNode(true);
tasksMapping.setField(myField);

Mapping to a Union Field with an XML Direct Mapping

Given the XML schema in the Schema for XML Direct Mapping to a Union Field example, the Java Class for XML Direct Mapping to a Union Field figure illustrates a Java class that can be mapped to a corresponding XML document. Note the shoeSize attribute in this class: when using a union field, the corresponding attribute must be able to store all possible values.

Schema for XML Direct Mapping to a Union Field

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="shoe-size" type="size-type"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:simpleType name="size-type">
        <xsd:union memberTypes="xsd:decimal xsd:string"/>
    </xsd:simpleType>

</xsd:schema>

Java Class for XML Direct Mapping to a Union Field

The XML Direct Mapping to the First Valid Union Type figure illustrates an XML direct mapping to a union field in an XML document that conforms to the schema in the Schema for XML Direct Mapping to a Union Field example. When EclipseLink unmarshalls the XML document, it tries each of the union types until it can make a successful conversion. The first schema type in the union is xsd:decimal. Because "10.5" is a valid decimal, EclipseLink converts the value to the appropriate type. If the Object attribute is specific enough to trigger an appropriate value, EclipseLink will use that type instead. Otherwise, EclipseLink uses a default (in this case BigDecimal). You can override this behavior in Java code.

XML Direct Mapping to the First Valid Union Type

The XML Direct Mapping to Another Valid Union Type figure illustrates an XML direct mapping to union field in another XML document that conforms to the schema in Schema for XML Direct Mapping to a Union Field. In this document, the value "M" is not a valid xsd:decimal type so the next union type is tried. The next union type is xsd:string and a conversion can be done.

XML Direct Mapping to Another Valid Union Type

This example shows how to configure this mapping in Java.

Java for XML Direct Mapping to a Union Type

XMLDirectMapping shoeSizeMapping = new XMLDirectMapping();
shoeSizeMapping.setAttributeName("shoeSize");
XMLUnionField shoeSizeField = new XMLUnionField();
shoeSizeField.setXPath("shoe-size/text()");
shoeSizeField.addSchemaType(XMLConstants.DECIMAL_QNAME);
shoeSizeField.addSchemaType(XMLConstants.STRING_QNAME);
shoeSizeMapping.setField(shoeSizeField);

To override the default conversion, use the XMLUnionField method addConversion:

shoeSizeField.addConversion(XMLConstants.DECIMAL_QNAME, Float.class);

Mapping to a Union of Lists with an XML Direct Mapping

Given the XML schema in Schema for XML Direct Mapping to Union of Lists, the XML Direct Mapping to Union of Lists figure illustrates an XML direct mapping to a union of lists in a corresponding XML document. The Java for XML Direct Mapping to Union of Lists example shows how to configure this mapping in Java.

Schema for XML Direct Mapping to Union of Lists

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <xsd:element name="vacation" type="unionOfLists"/>
    <xsd:simpleType name="unionOfLists">
        <xsd:union memberTypes="xsd:double">
            <xsd:simpleType>
                <xsd:list itemType="xsd:date"/>
            </xsd:simpleType>

            <xsd:simpleType>
                <xsd:list itemType="xsd:integer"/>
            </xsd:simpleType>
        </xsd:union>
    </xsd:simpleType>
</xsd:schema>

XML Direct Mapping to Union of Lists

Note that in this example, valid XML documents contain either all xsd:double, all xsd:date, or all xsd:integer values.

Java for XML Direct Mapping to Union of Lists

XMLDirectMapping mapping = new XMLDirectMapping();
mapping.setAttributeName("vacation");
mapping.setXPath("UnionOfLists/text()");

Mapping to a Union of Unions with an XML Direct Mapping

Given the XML schema in the Schema for XML Direct Mapping to a Union of Unions example, the Java Class for XML Direct Mapping to a Union of Unions figure illustrates a Java class that can be mapped to a corresponding XML document. The Java for XML Direct Mapping to a Union of Unions example shows how to configure this mapping in Java.

Schema for XML Direct Mapping to a Union of Unions

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="vacation" type="unionOfUnions"/>
    <xsd:simpleType name="unionOfUnions">
        <xsd:union>

            <xsd:simpleType>
                <xsd:union>
                    <xsd:simpleType>
                        <xsd:list itemType="xsd:date"/>
                    </xsd:simpleType>
                    <xsd:simpleType>

                        <xsd:list itemType="xsd:integer"/>
                    </xsd:simpleType>
                </xsd:union>
            </xsd:simpleType>
            <xsd:simpleType>
                <xsd:union>

                    <xsd:simpleType>
                        <xsd:list itemType="xsd:string"/>
                    </xsd:simpleType>
                    <xsd:simpleType>
                        <xsd:list itemType="xsd:float"/>
                    </xsd:simpleType>

                </xsd:union>
            </xsd:simpleType>
        </xsd:union>
    </xsd:simpleType>
</xsd:schema>

Java Class for XML Direct Mapping to a Union of Unions

Java for XML Direct Mapping to a Union of Unions

XMLDirectMapping vacationMapping = new XMLDirectMapping();
vacationMapping.setAttributeName("vacation");
XMLUnionField vacationField = new XMLUnionField();
vacationField.setXPath("vacation/text()");
vacationField.addSchemaType(XMLConstants.DATE_QNAME);
vacationField.addSchemaType(XMLConstants.INTEGER_QNAME);
vacationField.addSchemaType(XMLConstants.STRING_QNAME);
vacationField.addSchemaType(XMLConstants.FLOAT_QNAME);
vacationMapping.setField(vacationField);

Mapping with a Simple Type Translator

If the type of a node is not defined in your XML schema, you can configure an XML direct mapping to use the xsi:type attribute to provide type information.

Given the XML schema fragment in the Schema for XML Direct Mapping with Simple Type Translator example, the Java Class for XML Direct Mapping with Simple Type Translator figure illustrates a Java class that can be mapped to a corresponding XML document.

Schema for XML Direct Mapping with Simple Type Translator

...
    <xs:element name="area-code" type="anySimpleType"/>
    <xs:element name="number" type="anySimpleType"/>
...

Java Class for XML Direct Mapping with Simple Type Translator

The following figure illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema in the Schema for XML Direct Mapping with Simple Type Translator example.

XML Direct Mapping with a Simple Type Translator

This example shows how to configure this mapping in Java.

Java for XML Direct Mapping with Simple Type Translator

XMLDirectMapping numberMapping = new XMLDirectMapping();
numberMapping.setAttributeName("number");
numberMapping.setXPath("number/text()");
XMLField numberField = (XMLField) numberMapping.getField();
numberField.setIsTypedTextField(true);

For more information, see Simple Type Translator.

XML Composite Direct Collection Mapping

XML composite direct collection mappings map a Java collection of simple object attributes to XML attributes and text nodes. Use multiplicity settings to specify an element as a collection. The XML schema allows you to define minimum and maximum occurrences. You can use a composite direct collection XML mapping in the following scenarios:

Mapping to Multiple Text Nodes
Mapping to Multiple Attributes
Mapping to a Single Text Node with an XML Composite Direct Collection Mapping
Mapping to a Single Attribute with an XML Composite Direct Collection Mapping
Mapping to a List of Unions with an XML Composite Direct Collection Mapping
Mapping to a Union of Lists with an XML Composite Direct Collection Mapping
Specifying the Content Type of a Collection with an XML Composite Direct Collection Mapping

See Configuring an XML Composite Direct Collection Mapping for more information.

Mapping to Multiple Text Nodes

This section describes using a composite direct collection XML mapping when:

Mapping to a Simple Sequence
Mapping to a Sequence in a Subelement

Mapping to a Simple Sequence

Given the XML schema in the Schema for Composite Direct Collection XML Mapping to a Simple Sequence example, the Composite Direct Collection XML Mapping to a Simple Sequence figure illustrates a composite direct collection XML mapping to a simple sequence of text nodes in a corresponding XML document. Java for Composite Direct Collection XML Mapping to a Simple Sequence shows how to configure this mapping in Java.

Schema for Composite Direct Collection XML Mapping to a Simple Sequence

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>
            <xsd:element name="task" type="xsd:string" maxOccurs="unbounded"/>
        </xsd:sequence>

    </xsd:complexType>
</xsd:schema>

Composite Direct Collection XML Mapping to a Simple Sequence

Java for Composite Direct Collection XML Mapping to a Simple Sequence

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("task/text()");

Mapping to a Sequence in a Subelement

Given the XML schema in this example, the Composite Direct Collection XML Mapping to a Subelement Sequence figure illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. The Java for Composite Direct Collection XML Mapping to a Subelement Sequence shows how to configure this mapping in Java.

Schema for Composite Direct Collection XML Mapping to a Subelement Sequence

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>

            <xsd:element name="tasks">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="task" type="xsd:string" maxOccurs="unbounded"/>
                    </xsd:sequence>
                </xsd:complexType>

            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

Composite Direct Collection XML Mapping to a Subelement Sequence

Java for Composite Direct Collection XML Mapping to a Subelement Sequence

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("tasks/task/text()");

Mapping to Multiple Attributes

Given the XML schema in the following example, the Composite Direct Collection XML Mapping to Multiple Attributes figure illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. The Java for Composite Direct Collection XML Mapping to Multiple Attributes exampleshows how to configure this mapping in Java.

Schema for Composite Direct Collection XML Mapping to Multiple Attributes

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <xsd:element name="employee" type="employee-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>
            <xsd:element name="tasks" maxOccurs="unbounded">
                <xsd:complexType>
                    <xsd:attribute name="task" type="xsd:string"/>

                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

Composite Direct Collection XML Mapping to Multiple Attributes

[img_text/dcxmma.htm Description of "Figure 58-17 Composite Direct Collection XML Mapping to Multiple Attributes"]

Java for Composite Direct Collection XML Mapping to Multiple Attributes

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks/@task");
tasksMapping.setXPath("task/text()");

Mapping to a Single Text Node with an XML Composite Direct Collection Mapping

When you map a collection to a single node, the contents of the node is treated as a space-separated list.

Given the XML schema in this example, the XML Composite Direct Collection Mapping to a Single Text Node figur eillustrates a composite direct collection XML mapping to a single text node in a corresponding XML document. The Java for XML Composite Direct Collection Mapping to a Single Text Node example shows how to configure this mapping in Java.

Schema for XML Composite Direct Collection Mapping to a Single Text Node

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>
            <xsd:element name="tasks" type="tasks-type"/>

        </xsd:sequence>
    </xsd:complexType>
    <xsd:simpleType name="tasks-type">
        <xsd:list itemType="xsd:string"/>
    </xsd:simpleType>
</xsd:schema>

XML Composite Direct Collection Mapping to a Single Text Node

Java for XML Composite Direct Collection Mapping to a Single Text Node

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("tasks/text()");
tasksMapping.setUsesSingleNode(true);

Mapping to a Single Attribute with an XML Composite Direct Collection Mapping

Given the XML schema in this example, the XML Composite Direct Collection Mapping to a Single Attribute figure illustrates a composite direct collection XML mapping to a single attribute in a corresponding XML document. The Java for XML Composite Direct Collection Mapping to a Single Attribute example shows how to configure this mapping in Java.

Schema for XML Composite Direct Collection Mapping to a Single Attribute

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:complexType name="employee-type">
        <xsd:attribute name="tasks" type="tasks-type"/>
    </xsd:complexType>

    <xsd:simpleType name="tasks-type">
        <xsd:list itemType="xsd:string"/>
    </xsd:simpleType>
</xsd:schema>

XML Composite Direct Collection Mapping to a Single Attribute

Java for XML Composite Direct Collection Mapping to a Single Attribute

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("@tasks");
tasksMapping.setUsesSingleNode(true);

Mapping to a List of Unions with an XML Composite Direct Collection Mapping

Given the XML schema in this example, the Composite XML Direct Collection Mapping to List of Unions figure illustrates a composite direct collection XML mapping to a list of unions in a corresponding XML document. The Java for XML Composite Direct Collection Mapping to List of Unions example shows how to configure this mapping in Java.

Schema for XML Composite Direct Collection Mapping to List of Unions

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="vacation" type="listOfUnions"/>
    <xsd:simpleType name="listOfUnions">
        <xsd:list>

            <xsd:simpleType>
                <xsd:union memberTypes="xsd:date xsd:integer"/>
            </xsd:simpleType>
        </xsd:list>
    </xsd:simpleType>
</xsd:schema>

Composite XML Direct Collection Mapping to List of Unions

Java for XML Composite Direct Collection Mapping to List of Unions

XMLCompositeDirectCollectionMapping mapping = new XMLCompositeDirectCollectionMapping();
mapping.setAttributeName("myattribute");
XMLUnionField field = new XMLUnionField("listOfUnions/text()");
mapping.addSchemaType(new Qname(url,"int"));
mapping.addSchemaType(new Qname(url,"date"));
mapping.setField(field);
mapping.useSingleElement(false);

Mapping to a Union of Lists with an XML Composite Direct Collection Mapping

Given the XML schema in this example, the XML Composite Direct Collection Mapping to a Union of Lists figure illustrates an XML composite direct collection mapping to a union of lists in a corresponding XML document. The Java for XML Composite Direct Collection Mapping to a Union of Lists example shows how to configure this mapping in Java.

Schema for XML Composite Direct Collection Mapping to a Union of Lists

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="vacation" type="unionOfLists"/>
    <xsd:simpleType name="unionOfLists">
        <xsd:union memberTypes="xsd:double">
            <xsd:simpleType>

                <xsd:list itemType="xsd:date"/>
            </xsd:simpleType>
            <xsd:simpleType>
                <xsd:list itemType="xsd:integer"/>
            </xsd:simpleType>
        </xsd:union>

    </xsd:simpleType>
</xsd:schema>

XML Composite Direct Collection Mapping to a Union of Lists

Note that in this example, valid XML documents contain either all xsd:double, all xsd:date, or all xsd:integer values.

Java for XML Composite Direct Collection Mapping to a Union of Lists

XMLCompositeDirectCollectionMapping mapping = new XMLCompositeDirectCollectionMapping();
mapping.setAttributeName("myattribute");
mapping.useSingleElement(false);
XMLUnionField unionField = new XMLUnionField("UnionOfLists/text()");
field.addSchemaType(new Qname(url," integer"))
field.addSchemaType (new Qname(url," date"))
field.addSchemaType (new Qname(url," double"))
field.setUsesSingleNode(false);

Specifying the Content Type of a Collection with an XML Composite Direct Collection Mapping

By default, EclipseLink will treat the node values read by a composite direct collection XML mapping as objects of type String. You can override this behavior by specifying the type of the collection's contents.

Given the XML schema in this example, the XML Composite Direct Collection Mapping with Specified Content Type figure illustrates an XML composite direct collection mapping to a simple sequence in a corresponding XML document. The mapping is configured to specify the content type of the collection as Calendar. The Java for XML Composite Direct Collection Mapping with Specified Content Type example shows how to configure this mapping in Java.

Schema for XML Composite Direct Collection Mapping with Specified Content Type

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="employee" type="employee-type"/>
    <xsd:complexType name="employee-type">
        <xsd:sequence>

            <xsd:element name="vacation" type="xsd:string" maxOccurs="unbounded"/>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

XML Composite Direct Collection Mapping with Specified Content Type

Java for XML Composite Direct Collection Mapping with Specified Content Type

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("vacationDays");
tasksMapping.setXPath("vacation/text()");
tasksMapping.setAttributeElementClass(Calendar.class);

XML Composite Object Mapping

XML composite object mappings represent a relationship between two classes. In XML, the "owned" class may be nested with the element tag representing the "owning" class. You can use a composite object XML mapping in the following scenarios:

Mapping into the Parent Record
Mapping to an Element
Mapping to Different Elements by Element Name
Mapping to Different Elements by Element Position

See Configuring an XML Composite Object Mapping for more information.

Mapping into the Parent Record

The composite object may be mapped to the same record as the parent.

Note: The nodes mapped to by the composite object must be sequential.

Given the XML schema in this exmaple, the XML Composite Object Mapping into the Parent Record figure illustrates an XML composite object mapping into the parent record in a corresponding XML document. The Java for XML Composite Object Mapping into the Parent Record example shows how to configure this mapping in Java.

Schema for XML Composite Object Mapping into the Parent Record

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="first-name" type="xsd:string"/>
            <xsd:element name="last-name" type="xsd:string"/>
            <xsd:element name="street" type="xsd:string"/>
            <xsd:element name="city" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

XML Composite Object Mapping into the Parent Record

Java for XML Composite Object Mapping into the Parent Record

XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();
addressMapping.setAttributeName("address");
addressMapping.setXPath(".");
addressMapping.setReferenceClass(Address.class);

Mapping to an Element

Given the XML schema in this example, theXML Composite Object Mapping to an Element figure illustrates an XML composite object mapping to an element in a corresponding XML document. The Java for XML Composite Object Mapping to an Element example shows how to configure this mapping in Java.

Schema for XML Composite Object Mapping to an Element

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="first-name" type="xsd:string"/>
            <xsd:element name="last-name" type="xsd:string"/>
            <xsd:element name="address">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="street" type="xsd:string"/>

                        <xsd:element name="city" type="xsd:string"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

XML Composite Object Mapping to an Element

XML Composite Object Mapping to an Element

Java for XML Composite Object Mapping to an Element

XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();
addressMapping.setAttributeName("address");
addressMapping.setXPath("address");
addressMapping.setReferenceClass(Address.class);

Mapping to Different Elements by Element Name

An object may have multiple composite object mappings to the same reference class. Each composite object mapping must have a unique XPath. This example uses unique XPaths by name.

Given the XML schema in this example, the XML Composite Object Mapping to Elements by Name figure illustrates an XML composite object mapping to different elements by name in a corresponding XML document. The Java for XML Composite Object Mapping to Elements by Name example shows how to configure this mapping in Java.

Schema for XML Composite Object Mapping to Elements by Name

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="first-name" type="xsd:string"/>
            <xsd:element name="last-name" type="xsd:string"/>
            <xsd:element name="billing-address" type="address-type"/>
            <xsd:element name="shipping-address" type="address-type"/>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="address-type">
        <xsd:sequence>
            <xsd:element name="street" type="xsd:string"/>
            <xsd:element name="city" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

XML Composite Object Mapping to Elements by Name

Java for XML Composite Object Mapping to Elements by Name

XMLCompositeObjectMapping billingAddressMapping = new XMLCompositeObjectMapping();
billingAddressMapping.setAttributeName("billingAddress");
billingAddressMapping.setXPath("billing-address");
billingAddressMapping.setReferenceClass(Address.class);

XMLCompositeObjectMapping shippingAddressMapping = new XMLCompositeObjectMapping();
shippingAddressMapping.setAttributeName("shippingAddress");
shippingAddressMapping.setXPath("shipping-address");
shippingAddressMapping.setReferenceClass(Address.class);

Mapping to Different Elements by Element Position

An object may have multiple composite object mappings to the same reference class. Each composite object mapping must have a unique XPath. This example uses unique XPaths by position.

Given the XML schema in this example, the XML Composite Object Mapping to Elements by Position figure illustrates an XML composite object mapping to different elements by position in a corresponding XML document. The Java for XML Composite Object Mapping to Elements by Position example shows how to configure this mapping in Java.

Schema for XML Composite Object Mapping to Elements by Position

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="first-name" type="xsd:string"/>
            <xsd:element name="last-name" type="xsd:string"/>
            <xsd:element name="address" maxOccurs="2">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="street" type="xsd:string"/>

                        <xsd:element name="city" type="xsd:string"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

XML Composite Object Mapping to Elements by Position

Java for XML Composite Object Mapping to Elements by Position

XMLCompositeObjectMapping billingAddressMapping = new XMLCompositeObjectMapping();
billinAddressMapping.setAttributeName("billingAddress");
billinAddressMapping.setXPath("address[1]");
billinAddressMapping.setReferenceClass(Address.class);

XMLCompositeObjectMapping shippingAddressMapping = new XMLCompositeObjectMapping();
shippingAddressMapping.setAttributeName("shippingAddress");
shippingAddressMapping.setXPath("address[2]");
shippingAddressMapping.setReferenceClass(Address.class);

XML Composite Collection Mapping

Use XML composite collection mappings to represent one-to-many relationships. Composite collection XML mappings can reference any class that has an EclipseLink descriptor. The attribute in the object mapped must implement either the Java Collection interface (for example, Vector or HashSet) or Map interface (for example, Hashtable or TreeMap). The CompositeCollectionMapping class allows a reference to the mapped class and the indexing type for that class.

Given the XML schema in this example, XML Composite Collection Mapping illustrates an XML composite collection mapping to different elements by position in a corresponding XML document. Java for XML Composite Collection Mapping for a Collection Attribute shows how to configure this mapping in Java for a Collection attribute and Java for XML Composite Collection Mapping for a Map Attribute shows how to configure this mapping in Java for a Map attribute.

Schema for XML Composite Collection Mapping

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="first-name" type="xsd:string"/>
            <xsd:element name="last-name" type="xsd:string"/>
            <xsd:element name="phone-number">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="number" type="xsd:string"/>

                    </xsd:sequence>
                    <xsd:attribute name="type" type="xsd:string"/>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

XML Composite Collection Mapping

Java for XML Composite Collection Mapping for a Collection Attribute

XMLCompositeCollectionMapping phoneNumbersMapping = new XMLCompositeCollectionMapping();
phoneNumbersMapping.setAttributeName("phoneNumbers");
phoneNumbersMapping.setXPath("phone-number");
phoneNumbersMapping.setReferenceClass(PhoneNumber.class);

Java for XML Composite Collection Mapping for a Map Attribute

XMLCompositeCollectionMapping phoneNumbersMapping = new XMLCompositeCollectionMapping();
phoneNumbersMapping.setAttributeName("phoneNumbers");           
phoneNumbersMapping.setXPath("phone-number");
phoneNumbersMapping.setReferenceClass(PhoneNumber.class);
phoneNumbersMapping.useMapClass(HashMap.class, "getType");

See Configuring an XML Composite Collection Mapping for more information.

XML Any Object Mapping

The XML any object mapping is similar to the composite object XML mapping (see XML Composite Object Mapping) except that the reference object may be of any type (including String). This type does not need to be related to any other particular type through inheritance or a common interface.

The corresponding object attribute value can be an instance of any object with a Descriptor, a java.lang.Object, a java.lang.String, a primitive object (such as java.lang.Integer), or a user defined type generic enough for all possible application values.

This mapping is useful with the following XML schema constructs:

any
choice
substitution groups

Referenced objects can specify a default root element on their descriptor (see Default Root Element).

Note: The undefined document root element of a referenced object is ignored during marshalling with an any collection mapping and object mapping.

Given the XML schema in Schema for XML Any Object Mapping, Java Classes for XML Any Object Mapping illustrates the Java classes used in this example. A single XML any object mapping is used to map Customer attribute contactMethod. This attribute must be generic enough to reference all possible values: in this example, instances of Address, PhoneNumber, and String.

Schema for XML Any Object Mapping

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="contact-method" type="xsd:anyType"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:element name="address">
        <xsd:complexType>
            <xsd:sequence>

                <xsd:element name="street" type="xsd:string"/>
                <xsd:element name="city" type="xsd:string"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="phone-number" type="xsd:string"/>

</xsd:schema>

Java Classes for XML Any Object Mapping

XML Any Object Mapping to Address Type, XML Any Object Mapping to PhoneNumber Type, and XML Any Object Mapping to String Type illustrate how the XML any object mapping maps to an Address, PhoneNumber, and String (respectively) in XML documents that conform to the schema in Schema for XML Any Object Mapping.

XML Any Object Mapping to Address Type

XML Any Object Mapping to PhoneNumber Type

XML Any Object Mapping to String Type

This example shows how to configure this mapping in Java.

Java for XML Any Object Mapping

XMLAnyObjectMapping contactMethodMapping = new XMLAnyObjectMapping();
contactMethodMapping.setAttributeName("contactMethod");
contactMethodMapping.setXPath("contact-method");

For more information about EclipseLink XML mapping support for xs:any and xs:anyType, see xs:any and xs:anyType Support.

See Configuring an XML Any Object Mapping for more information.

XML Any Collection Mapping

The XML any collection mapping is similar to the composite collection XML mapping (see XML Composite Collection Mapping), except that the referenced objects may be of different types (including String). These types need not be related to each other through inheritance or a common interface.

The corresponding object attribute value can be an instance of any object with a Descriptor, a java.lang.Object, a java.lang.String, a primitive object (such as java.lang.Integer), or a user defined type generic enough for all possible application values.

This mapping is useful with the following XML schema constructs:

any
choice
substitution groups

Each of the referenced objects (except String) must specify a default root element on their descriptor (see Default Root Element).

Given the XML schema in Schema for XML Any Collection Mapping, Java Classes for XML Any Collection Mapping illustrates the Java classes used in this example. A single XML any collection mapping is used to map Customer attribute contactMethods. This attribute must be generic enough to reference all possible values: in this example, instances of Address, PhoneNumber, and String.

Schema for XML Any Collection Mapping

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="customer" type="customer-type"/>
    <xsd:complexType name="customer-type">
        <xsd:sequence>

            <xsd:element name="contact-methods" type="xsd:anyType"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:element name="address">
        <xsd:complexType>
            <xsd:sequence>

                <xsd:element name="street" type="xsd:string"/>
                <xsd:element name="city" type="xsd:string"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="phone-number" type="xsd:string"/>

</xsd:schema>

Java Classes for XML Any Collection Mapping

XML Any Collection Mapping illustrate how the XML any collection mapping maps to a collection of Address, PhoneNumber, and String objects in an XML document that conforms to the schema in Schema for XML Any Collection Mapping.

XML Any Collection Mapping

This example shows how to configure this mapping in Java.

Java for XML Any Collection Mapping

XMLAnyCollectionMapping contactMethodsMapping = new XMLAnyCollectionMapping();
contactMethodsMapping.setAttributeName("contactMethods");
contactMethodsMapping.setXPath("contact-methods");

For more information about EclipseLink XML mapping support for xs:any and xs:anyType, see xs:any and xs:anyType Support.

See Configuring an XML Any Collection Mapping for more information.

XML Transformation Mapping

You can use an XML transformation mapping to create a custom mapping where one or more XML nodes can be used to create the object to be stored in a Java class's attribute. To handle the custom requirements at marshall (write) and unmarshall (read) time, a transformation mapping takes instances of org.eclipse.persistence.mappings.transformers (such as AttributeTransformer and FieldTransformer) that you provide. This provides a nonintrusive solution that avoids the need for your domain objects to implement special interfaces for this purpose.

As XML Transformation Mappings illustrates, you configure the transformation mapping with an org.eclipse.persistence.mappings.transformers.AttributeTransformer instance to perform the XML instance-to-Java attribute transformation at unmarshall time. In this example, the AttributeTransformer combines two XML text nodes into a single Java object.

Similarly, you also configure the transformation mapping with one or more org.eclipse.persistence.mappings.transformers.FieldTransformer instances to perform the Java attribute-to-XML instance transformation at marshall time. In this example, each FieldTransformer is responsible for mapping one of the Java object values to an XML text node.

XML Transformation Mappings

See Configuring an XML Transformation Mapping for more information.

XML Object Reference Mapping

The org.eclipse.persistence.ox.mappings.XMLObjectReferenceMapping is a key on source-based aggregate mapping. It allows you to use one-to-one mappings to map a given element in an XML document to another element in that same XML document using one or more keys.

Use this mapping when several objects reference the same instance of another object. In this case, one and only one of the mappings is to be a composite–the remaining mappings must be reference mappings. These references will be created based on one or more key values.

XML object reference mapping is fully supported in the deployment XML.

With this mapping, EclipseLink provides support for composite keys, as well as for foreign key grouping elements.

Note: You should group together elements mapped to keys. Also, EclipseLink supports grouping elements that wrap all of the keys (not the ones that wrap each individual key).

The XMLObjectReferenceMapping captures the following information:

Attribute name.
Reference class.
Map of source and target key pairs, such as XPath values (see XPath Support) in the following format:

["project-id/text()","@id"]

Use the addSourceToTargetKeyFieldAssociation method to add a source and target Xpath pair to the map.

List of source keys to maintain order.

For more information, see Configuring an XML Object Reference Mapping.

Mapping Using a Single Key

The following class diagram, as well as the following three examples, demonstrate how to map one element to another using a single key.

Class Diagram

Using Single Key - Instance Document

...
<employee id="12">
    <name>Joe Brown</name>
    <project-id>99</project-id>
</employee>
<project id="99">
    <name>Big Project</name>
    <budget>100,000</budget>
</project>
...

This example shows how to create an XMLObjectReferenceMapping, set a single key on source, and then add the mapping to the descriptor.

Using Single Key - Project Class - Employee Descriptor

...
XMLObjectReferenceMapping emp = new XMLObjectReferenceMapping();
emp.setAttributeName("project");
emp.setReferenceClass(Project.class);
emp.addSourceToTargetKeyFieldAssociation("project-id/text()","@id");   
empDescriptor.addMapping(emp);
...

This example shows how to define the primary key field on the descriptor.

Using Single Key - Project Class - Project Descriptor

...
XMLDescriptor prjDescriptor = new XMLDescriptor();
prjDescriptor.setJavaClass(Project.class);
prjDescriptor.addPrimaryKeyField("@id");
...

Mapping Using a Composite Key

The Class Diagram figure, as well as the following three examples, demonstrate how to map one element to another using a composite key.

Using Composite Key - Instance Document

...
<employee id="12">
    <name>Joe Brown</name>
    <prj-name>Big Project</prj-name>
    <prj-budget>100,000</prj-budget>
</employee>
<project id="99">
    <name>Big Project</name>
    <budget>100,000</budget>
</project>
...

This example shows how to create an XMLObjectReferenceMapping, set a composite key on source, and then add the mapping to the descriptor.

Using Composite Key - Project Class - Employee Descriptor

...
XMLObjectReferenceMapping emp = new XMLObjectReferenceMapping();
emp.setAttributeName("project");
emp.setReferenceClass(Project.class);
emp.addSourceToTargetKeyFieldAssociation("prj-name/text()","name/text()");
emp.addSourceToTargetKeyFieldAssociation("prj-budget/text()","budget/text()");
empDescriptor.addMapping(emp);
...

The following example shows how to define a composite primary key field on the descriptor.

Using Composite Key - Project Class - Project Descriptor

...
XMLDescriptor prjDescriptor = new XMLDescriptor();
prjDescriptor.setJavaClass(Project.class);
prjDescriptor.addPrimaryKeyField("name");
prjDescriptor.addPrimaryKeyField("budget");
...

Mapping Using JAXB

The JAXB generator generates a deployment descriptor based on annotations and default values.

Note: The JAXB 2.0 specification states that for the @XmlID annotation, the following restrictions apply:

The field type must be String.
The use of composite keys is not allowed.

The Class Diagram figure, as well as the following four examples, demonstrate how to map one XML element to another using JAXB annotations.

Using JAXB - Object Model

public class Employee {

    @XmlAttribute(name="id")
    public String id;
    public String name;

    @XmlElement(name="project-id")
    @XmlIDREF
    public Project project;
    ...
}


public class Project {

    @XmlElement(name="project-id")
    @XmlID
    public String id;

    public String name;
    public String budget;
    ...
}

Using JAXB - Instance Document

...
<employee id="12">
    <name>Joe Brown</name>
    <project-id>99</project-id>
</employee>
<project project-id="99">
    <name>Big Project</name>
    <budget>100,000</budget>
</project>
...

The following example shows how to create an XMLObjectReferenceMapping, set a key on source, and then add the mapping to the descriptor.

Using JAXB - Project Class - Employee Descriptor

...
XMLObjectReferenceMapping emp = new XMLObjectReferenceMapping();
emp.setAttributeName("project");
emp.setReferenceClass(Project.class);
emp.addSourceToTargetKeyFieldAssociation("project-id/text()","@pid");
empDescriptor.addMapping(emp);
...

This example shows how to define the primary key field on the descriptor.

Using JAXB - Project Class - Project Descriptor

...
XMLDescriptor prjDescriptor = new XMLDescriptor();
prjDescriptor.setJavaClass(Project.class);
prjDescriptor.addPrimaryKeyField("@pid");
...

For more information, see the following:

JAXB 2.0 Specification at http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html
Introduction to XML Projects

XML Collection Reference Mapping

The org.eclipse.persistence.ox.mappings.XMLCollectionReferenceMapping is a key on source-based aggregate mapping. It allows you to use one-to-many mappings to map a given element in an XML document to another element in that same XML document using one or more keys.

With this mapping, EclipseLink provides support for foreign key grouping elements.

Note: You should group together elements mapped to keys. Also, EclipseLink supports grouping elements that wrap all of the keys (not the ones that wrap each individual key).

The XMLCollectionReferenceMapping captures the following information:

Attribute name.
Reference class.
Map of source and target key pairs, such as XPath values (see XPath Support) in the following format:

["project-id/text()","@id"]

Use the addSourceToTargetKeyFieldAssociation method to add a source and target XPath pair to the map.

List of source keys to maintain order.

The following class diagram, as well as the following three examples, demonstrate how to map one element to another using a single key.

Class Diagram

Using a Single Key - Instance Document

...
<employee id="12">
    <name>Joe Brown</name>
    <project-id>99</project-id>
    <project-id>199</project-id>
</employee>
<project id="99">
    <name>Big Project</name>
    <budget>100,000</budget>
</project>
<project id="199">
    <name>Bigger Project</name>
    <budget>100,000,000</budget>
</project>
...

This example shows how to create an XMLCollectionReferenceMapping, set a single key on source, and then add the mapping to the descriptor.

Using a Single Key - Project Class - Employee Descriptor

...
XMLCollectionReferenceMapping prj = new XMLCollectionReferenceMapping();
prj.useCollectionClass(ArrayList.class);
prj.setAttributeName("projects");
prj.setReferenceClass(Project.class);
prj.addSourceToTargetKeyFieldAssociation("project-id/text()","@id");
empDescriptor.addMapping(prj);
...

The following example shows how to define the primary key field on the descriptor.

Using a Single Key - Project Class - Project Descriptor

...
XMLDescriptor prjDescriptor = new XMLDescriptor();
prjDescriptor.setJavaClass(Project.class);
prjDescriptor.addPrimaryKeyField("@id");
...

The Class Diagram figure, as well as the following three examples, demonstrate how to map one element to another using a single key as a space-separated list.

Using a Single Key as Space-Separated List - Instance Document

...
<employee id="12" project-ids="99 199">
    <name>Joe Brown</name>
</employee>
<project id="99">
    <name>Big Project</name>
    <budget>100,000</budget>
</project>
<project id="199">
    <name>Bigger Project</name>
    <budget>100,000,000</budget>
</project>
...

The following example shows how to create an XMLCollectionReferenceMapping, set a single key on source as a space-separated list, and then add the mapping to the descriptor.

Using a Single Key as Space-Separated List - Project Class - Employee Descriptor

...
XMLCollectionReferenceMapping prj = new XMLCollectionReferenceMapping();
prj.useCollectionClass(ArrayList.class);
prj.setAttributeName("projects");
prj.setReferenceClass(Project.class);
prj.addSourceToTargetKeyFieldAssociation("project-ids","@id");
empDescriptor.addMapping(prj);
...

This example shows how to define the primary key field on the descriptor.

Using a Single Key as Space-Separated List - Project Class - Project Descriptor

...
XMLDescriptor prjDescriptor = new XMLDescriptor();
prjDescriptor.setJavaClass(Project.class);
prjDescriptor.addPrimaryKeyField("@id");
...

For more information, see Configuring an XML Collection Reference Mapping.

XML Binary Data Mapping

The org.eclipse.persistence.ox.mappings.XMLBinaryDataMapping is a direct mapping (see XML Direct Mapping) that you use for handling binary data: it maps binary data in the object model to XML. This allows you to enable writing of binary data directly as inline binary data (base64 BLOB), or passing through as a MtOM or SwaRef attachment. For more information, see Optimizing Storage and Retrieval of Binary Data in XML.

The XMLBinaryDataMapping also lets you make callbacks to an attachment marshaller and unmarshaller (see How to Use an Attachment Marshaller and Unmarshaller), as well as set XPath (see XPath Support).

The following example shows how to create an XMLBinaryDataMapping, set some of its properties, and then add the mapping to a descriptor.

XMLBinaryDataMapping addressMapping = new XMLBinaryDataMapping();
addressMapping.setXPath("address");
addressMapping.setShouldInlineBinaryData(true);
descriptor.addMapping(addressMapping);
...

See Configuring an XML Binary Data Mapping for more information.

XML Binary Data Collection Mapping

The org.eclipse.persistence.ox.mappings.XMLBinaryDataCollectionMapping is very similar to the XMLBinaryDataMapping (see XML Binary Data Mapping), except that it maps a collection of binary data in the object model to XML.

For more information, see the following:

The following example shows how to create an XMLBinaryDataCollectionMapping, set some of its properties, and then add the mapping to a descriptor.

XMLBinaryDataCollectionMapping addressMapping = new XMLBinaryDataCollectionMapping();
addressMapping.setCollectionContentType(type);
addressMapping.setXPath("address");
addressMapping.setShouldInlineBinaryData(true);
descriptor.addMapping(addressMapping);
...

For more information, see the following:

XML Fragment Mapping

The org.eclipse.persistence.ox.mappings.XMLFragmentMapping is a direct mapping (see XML Direct Mapping) that provides you with a means to keep a part of an XML tree as a node.

This mapping also lets you set the XPath (see XPath Support).

The following example shows how to create an XMLFragmentMapping, set some of its properties, and then add the mapping to a descriptor.

XMLFragmentMapping addressMapping = new XMLFragmentMapping();
addressMapping.setXPath("address");
descriptor.addMapping(addressMapping);
...

See Configuring an XML Fragment Mapping for more information.

XML Fragment Collection Mapping

The org.eclipse.persistence.ox.mappings.XMLFragmentCollectionMapping is similar to the XMLFragmentMapping (see XML Fragment Mapping), except that it allows you to keep a part of an XML tree as a collection of nodes.

The following example shows how to create an XMLFragmentMapping, set the XPath (see XPath Support), and then add the mapping to a descriptor.

XMLFragmentCollectionMapping addressMapping = new XMLFragmentCollectionMapping();
addressMapping.setXPath("address");
descriptor.addMapping(addressMapping);
...

See Configuring an XML Fragment Collection Mapping for more information.

XML Choice Object Mapping

The org.eclipse.persistence.ox.mappings.XMLChoiceObjectMapping lets you map a single attribute to a number of different elements in an XML document.

Unlike other EclipseLink XML mappings, instead of setting a single XPath, you use the addChoiceElement method to specify an XPath (see XPath Support), as well as the type associated with this XPath, as follows:

xmlChoiceObjectMapping.addChoiceElement("mystring/text()", String.class);
xmlChoiceObjectMapping.addChoiceElement("myaddress", Address.class);

When any of these elements are encountered in the XML document, they are read in and set in the object as correct types.

Use this mapping to map to single choices or substitution groups in an XML schema.

The following example shows how to create an XMLChoiceObjectMapping, set the XPath, and then add the mapping to a descriptor.

XMLChoiceObjectMapping addressMapping = new XMLChoiceObjectMapping();
addressMapping.setXPath("address", Address.class);
descriptor.addMapping(addressMapping);
...

See Configuring an XML Choice Object Mapping for more information.

XML Choice Collection Mapping

The org.eclipse.persistence.ox.mappings.XMLChoiceCollectionMapping is similar to the XMLChoiceObjectMapping (see XML Choice Object Mapping), except that you use it to handle reading and writing of XML documents containing a collection of choice or substitution group elements.

The following example shows how to create an XMLChoiceCollectionMapping, set the XPath (see XPath Support), and then add the mapping to a descriptor.

XMLChoiceCollectionMapping addressMapping = new XMLChoiceCollectionMapping();
addressMapping.setXPath("address", Address.class);
descriptor.addMapping(addressMapping);
...

See Configuring an XML Choice Collection Mapping for more information.

XML Any Attribute Mapping

The org.eclipse.persistence.ox.mappings.XMLAnyAttributeMapping is a database mapping that you can use to map to an attribute in an object to any XML attributes contained on a specific element in the XML document. The attribute in the object will contain a map of attribute values keyed on a qualified name (javax.xml.namespace.QName). If one or more of the attributes found on the specified element is already mapped to another attribute in the object, EclipseLink will ignored that attribute during the unmarshall operation.

The XMLAnyAttributeMapping lets you set the XPath (see XPath Support), however, this operation is optional for this type of mapping: if you do not set the XPath, the mapping will look for any attribute children directly owned by the current element.

The following example shows how to create an XMLAnyAttributeMapping, set the XPath, and then add the mapping to a descriptor.

XMLAnyAttributeMapping addressMapping = new XMLAnyAttributeMapping();
addressMapping.setXPath("address", Address.class);
descriptor.addMapping(addressMapping);
...

See Configuring an XML Any Attribute Mapping for more information.

Copyright Statement

Breadcrumbs

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Introduction to XML Mappings (ELUG)

Contents

XML Mapping Types

XML Mapping Concepts

Mapping to Simple and Complex Types

Mapping Order

XPath Support

xsd:list and xsd:union Support

xs:any and xs:anyType Support

jaxb:class Support

Typesafe Enumeration Support

Mapping Extensions

Key On Source-Based Mapping Support

Substitution Groups

Mixed Content Mapping

XML Adapter

XML Direct Mapping

Mapping to a Text Node

Mapping to a Simple Text Node

Mapping to a Text Node in a Simple Sequence

Mapping to a Text Node in a Subelement

Mapping to a Text Node by Position

Mapping to an Attribute

Mapping to a Specified Schema Type

Mapping to a List Field with an XML Direct Mapping

Mapping to a Union Field with an XML Direct Mapping

Mapping to a Union of Lists with an XML Direct Mapping

Mapping to a Union of Unions with an XML Direct Mapping

Mapping with a Simple Type Translator

XML Composite Direct Collection Mapping

Mapping to Multiple Text Nodes

Mapping to a Simple Sequence

Mapping to a Sequence in a Subelement

Mapping to Multiple Attributes

Mapping to a Single Text Node with an XML Composite Direct Collection Mapping

Mapping to a Single Attribute with an XML Composite Direct Collection Mapping

Mapping to a List of Unions with an XML Composite Direct Collection Mapping

Mapping to a Union of Lists with an XML Composite Direct Collection Mapping

Specifying the Content Type of a Collection with an XML Composite Direct Collection Mapping

XML Composite Object Mapping

Mapping into the Parent Record

Mapping to an Element

Mapping to Different Elements by Element Name

Mapping to Different Elements by Element Position

XML Composite Collection Mapping

XML Any Object Mapping

XML Any Collection Mapping

XML Transformation Mapping

XML Object Reference Mapping

Mapping Using a Single Key

Mapping Using a Composite Key

Mapping Using JAXB

XML Collection Reference Mapping

XML Binary Data Mapping

XML Binary Data Collection Mapping

XML Fragment Mapping

XML Fragment Collection Mapping

XML Choice Object Mapping

XML Choice Collection Mapping

XML Any Attribute Mapping