53 Introduction to XML Mappings

An XML mapping transforms object data members to the XML nodes of an XML document whose structure is defined by an XML schema document (XSD).

This chapter includes the following sections:

XML Mapping Types
XML Mapping Concepts
XML Direct Mapping
XML Composite Direct Collection Mapping
XML Composite Object Mapping
XML Composite Collection Mapping
XML Any Object Mapping
XML Any Collection Mapping
XML Transformation Mapping
XML Object Reference Mapping
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

For information on mapping concepts and features common to more than one type of TopLink mappings, see Chapter 17, "Introduction to Mappings".

53.1 XML Mapping Types

TopLink supports the XML mappings listed in Table 53-1.

Table 53-1 TopLink XML Mapping Types

Mapping Type	Description	Oracle JDeveloper	TopLink Workbench	Java
XML direct mapping (see Section 53.3, "XML Direct Mapping")	Map a simple object attribute to an XML attribute or text node.
XML composite direct collection mapping (see Section 53.4, "XML Composite Direct Collection Mapping")	Map a collection of simple object attributes to XML attributes or text nodes.
XML composite object mapping (see Section 53.5, "XML Composite Object Mapping")	Map any attribute that contains a single object to an XML element. The TopLink runtime uses the descriptor for the referenced object to populate the contents of that element.
XML composite collection mapping (see Section 53.6, "XML Composite Collection Mapping")	Map an attribute that contains a homogenous collection of objects to multiple XML elements. The TopLink runtime uses the descriptor for the referenced object to populate the contents of those elements.
XML any object mapping (see Section 53.7, "XML Any Object Mapping")	The any object XML mapping is similar to the composite object XML mapping (see Section 53.5, "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 (see Section 53.8, "XML Any Collection Mapping")	The any collection XML mapping is similar to the composite collection XML mapping (see Section 53.6, "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 (see Section 53.9, "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 (see Section 53.10, "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 (see Section 53.11, "XML Collection Reference Mapping"	This mapping is similar to the XML object reference mapping (see Section 53.10, "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 (see Section 53.12, "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 (see Section 53.13, "XML Binary Data Collection Mapping"	This mapping is similar to the XML binary data mapping (see Section 53.12, "XML Binary Data Mapping"), except that it maps a collection of binary data in the object model to XML.
XML fragment mapping (see Section 53.14, "XML Fragment Mapping"	Keep a part of an XML tree as a node.
XML fragment collection mapping (see Section 53.15, "XML Fragment Collection Mapping"	This mapping is similar to the XML fragment mapping (see Section 53.14, "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 (see Section 53.16, "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 (see Section 53.17, "XML Choice Collection Mapping"	This mapping is similar to the XML choice object mapping (see Section 53.16, "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 (see Section 53.18, "XML Any Attribute Mapping"	Map to an attribute in an object to any XML attributes contained on a specific element in the XML document.

53.2 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.

TopLink stores XML mappings for each class in the class descriptor. TopLink 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, Oracle recommends that you use Oracle JDeveloper TopLink Editor or TopLink Workbench and their GUI environment to set the descriptor properties and configure the mappings.

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

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

53.2.1 Mapping to Simple and Complex Types

Consider the XML document shown in Example 53-1.

Example 53-1 XML Document

<EMPLOYEE ID="123">
    <NAME>Jane Doe</NAME>
    <ADDRESS>
        <STREET>123 Any St.</STREET>
        <CITY>MyCity</CITY>
    </ADDRESS>
</EMPLOYEE>

In general, using TopLink 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).

Table 53-2 summarizes the XML simple and complex types supported by each TopLink XML mapping.

Table 53-2 XML Mapping Support for XML Simple and Complex Types

Mapping	XML Attribute	XML Text Node	XML Element
XML direct (see Section 53.3, "XML Direct Mapping")
XML composite direct collection (see Section 53.4, "XML Composite Direct Collection Mapping")
XML composite object (see Section 53.5, "XML Composite Object Mapping")
XML composite collection (see Section 53.6, "XML Composite Collection Mapping")
XML any object (see Section 53.7, "XML Any Object Mapping")
XML any collection (see Section 53.8, "XML Any Collection Mapping")
XML transformation (see Section 53.9, "XML Transformation Mapping")
XML object reference (see Section 53.10, "XML Object Reference Mapping")
XML collection reference (see Section 53.11, "XML Collection Reference Mapping")
XML binary data (see Section 53.12, "XML Binary Data Mapping")
XML binary data collection (see Section 53.13, "XML Binary Data Collection Mapping")
XML fragment (see Section 53.14, "XML Fragment Mapping")
XML fragment collection (see Section 53.15, "XML Fragment Collection Mapping")
XML choice object (see Section 53.16, "XML Choice Object Mapping")
XML choice collection (see Section 53.17, "XML Choice Collection Mapping")
XML any attribute (see Section 53.18, "XML Any Attribute Mapping")

53.2.2 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 TopLink (whether in Oracle JDeveloper TopLink Editor, TopLink Workbench, or in Java code) including the order in which you define mapping components such as Transformers (see Section 53.9, "XML Transformation Mapping") is reflected in the order, in which TopLink persists data in an XML document.

53.2.3 XPath Support

TopLink 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 Section 17.2.7, "Mappings and XPath".

53.2.4 xsd:list and xsd:union Support

You can use XML direct (see Section 53.3, "XML Direct Mapping") and composite direct collection (see Section 53.4, "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 Section 17.2.8, "Mappings and xsd:list and xsd:union Types".

53.2.5 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.

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

Table 53-3 XML Mappings and XML Schema xs:any and xs:anyType

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

Use XML Mapping...	To Map XML Schema Definition...
See Section 53.7, "XML Any Object Mapping"	Element with a single^Foot 1 unnamed complex type specified as `xs:any`.
See Section 53.8, "XML Any Collection Mapping"	Element with an unnamed sequence^Footref 2 of complex types specified as `xs:any`. Element with a named sequence^Foot 2 of complex types of type `xs:anyType`. Root element of type `xs:anyType`.

See Section 53.7, "XML Any Object Mapping"

Element with a single^Foot 1 unnamed complex type specified as xs:any.

See Section 53.8, "XML Any Collection Mapping"

Element with an unnamed sequence^Footref 2 of complex types specified as xs:any.

Element with a named sequence^Foot 2 of complex types of type xs:anyType.

Root element of type xs:anyType.

^Footnote 1minOccurs and maxOccurs are both equal to 1.

^Footnote 2maxOccurs is greater than 1.

53.2.6 jaxb:class Support

You can configure an XML composite object mapping (see Section 53.5, "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 Section 17.2.9, "Mappings and the jaxb:class Customization".

53.2.7 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 Section 17.2.10, "Mappings and JAXB Typesafe Enumerations"

53.2.8 Mapping Extensions

If existing TopLink 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 Section 17.2.6, "Mapping Converters and Transformers".

53.2.9 Key On Source-Based Mapping Support

TopLink 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 oracle.toplink.ox.mappings.XMLObjectReferenceMapping and XMLCollectionReferenceMapping for the key on source.

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

For more information, see the following:

XML Object Reference Mapping
XML Collection Reference Mapping

53.2.10 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 TopLink XMLChoiceObjectMapping (see Section 53.16, "XML Choice Object Mapping") and XMLChoiceCollectionMapping (see Section 53.17, "XML Choice Collection Mapping") to handle substitution groups.

53.2.11 Mixed Content Mapping

To handle mixed content, such as reading in XML text nodes as strings, use TopLink XMLAnyCollectionMapping (see Section 53.8, "XML Any Collection Mapping").

Enable this functionality through the setMixedContent method.

53.2.12 XML Adapter

TopLink 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

53.3 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 Chapter 55, "Configuring an XML Direct Mapping" for more information.

Note:

Do not confuse an XML direct mapping with a relational direct-to-XMLType mapping (see Section 27.4, "Direct-to-XMLType Mapping").

53.3.1 Mapping to a Text Node

This section describes using an XML direct mapping when:

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

53.3.1.1 Mapping to a Simple Text Node

Given the XML schema in Example 53-2, Figure 53-1 illustrates an XML direct mapping to a simple text node in a corresponding XML document. Example 53-3 shows how to configure this mapping in Java.

Example 53-2 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>

Figure 53-1 XML Direct Mapping to Simple Text Node

Description of "Figure 53-1 XML Direct Mapping to Simple Text Node"

Example 53-3 Java for XML Direct Mapping to Simple Text Node

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

53.3.1.2 Mapping to a Text Node in a Simple Sequence

Given the XML schema in Example 53-4, Figure 53-2 illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document. Example 53-5 shows how to configure this mapping in Java.

Example 53-4 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>

Figure 53-2 XML Direct Mapping to a Text Node in a Simple Sequence

Description of "Figure 53-2 XML Direct Mapping to a Text Node in a Simple Sequence"

Example 53-5 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()");

53.3.1.3 Mapping to a Text Node in a Subelement

Given the XML schema in Example 53-6, Figure 53-3 illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document. Example 53-7 shows how to configure this mapping in Java.

Example 53-6 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>

Figure 53-3 XML Direct Mapping to a Text Node in a Subelement

Description of "Figure 53-3 XML Direct Mapping to a Text Node in a Subelement"

Example 53-7 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()");

53.3.1.4 Mapping to a Text Node by Position

Given the XML schema in Example 53-8, Figure 53-4 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 53-9 shows how to configure this mapping in Java.

Example 53-8 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>

Figure 53-4 XML Direct Mapping to Text Node by Position

Description of "Figure 53-4 XML Direct Mapping to Text Node by Position"

Example 53-9 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()");

53.3.2 Mapping to an Attribute

Given the XML schema in Example 53-10, Figure 53-5 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 53-11 shows how to configure this mapping in Java.

Example 53-10 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>

Figure 53-5 XML Direct Mapping to an Attribute

Description of "Figure 53-5 XML Direct Mapping to an Attribute"

Example 53-11 Java for XML Direct Mapping to an Attribute

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

53.3.3 Mapping to a Specified Schema Type

In most cases, TopLink 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 TopLink 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 Example 53-12, Figure 53-6 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 53-13 shows how to configure this mapping in Java.

Example 53-12 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>

Figure 53-6 XML Direct Mapping to a Specified Schema Type

Description of "Figure 53-6 XML Direct Mapping to a Specified Schema Type"

Example 53-13 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);

53.3.4 Mapping to a List Field with an XML Direct Mapping

Given the XML schema in Example 53-14, Figure 53-7 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. Example 53-15 shows how to configure this mapping in Java.

Example 53-14 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>

Figure 53-7 XMLDirect Mapping to a List Field

Description of "Figure 53-7 XMLDirect Mapping to a List Field"

Example 53-15 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);

53.3.5 Mapping to a Union Field with an XML Direct Mapping

Given the XML schema in Example 53-16, Figure 53-8 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.

Example 53-16 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>

Figure 53-8 Java Class for XML Direct Mapping to a Union Field

Description of "Figure 53-8 Java Class for XML Direct Mapping to a Union Field"

Figure 53-9 illustrates an XML direct mapping to a union field in an XML document that conforms to the schema in Example 53-16. When TopLink 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, TopLink converts the value to the appropriate type. If the Object attribute is specific enough to trigger an appropriate value, TopLink will use that type instead. Otherwise, TopLink uses a default (in this case BigDecimal). You can override this behavior in Java code.

Figure 53-9 XML Direct Mapping to the First Valid Union Type

Description of "Figure 53-9 XML Direct Mapping to the First Valid Union Type"

Figure 53-10 illustrates an XML direct mapping to union field in another XML document that conforms to the schema in Example 53-16. 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.

Figure 53-10 XML Direct Mapping to Another Valid Union Type

Description of "Figure 53-10 XML Direct Mapping to Another Valid Union Type"

Example 53-17 shows how to configure this mapping in Java.

Example 53-17 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);

53.3.6 Mapping to a Union of Lists with an XML Direct Mapping

Given the XML schema in Example 53-18, Figure 53-11 illustrates an XML direct mapping to a union of lists in a corresponding XML document. Example 53-19 shows how to configure this mapping in Java.

Example 53-18 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>

Figure 53-11 XML Direct Mapping to Union of Lists

Description of "Figure 53-11 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.

Example 53-19 Java for XML Direct Mapping to Union of Lists

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

53.3.7 Mapping to a Union of Unions with an XML Direct Mapping

Given the XML schema in Example 53-20, Figure 53-12 illustrates a Java class that can be mapped to a corresponding XML document. Example 53-21 shows how to configure this mapping in Java.

Example 53-20 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>

Figure 53-12 Java Class for XML Direct Mapping to a Union of Unions

Description of "Figure 53-12 Java Class for XML Direct Mapping to a Union of Unions"

Example 53-21 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);

53.3.8 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 Example 53-22, Figure 53-13 illustrates a Java class that can be mapped to a corresponding XML document.

Example 53-22 Schema for XML Direct Mapping with Simple Type Translator

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

Figure 53-13 Java Class for XML Direct Mapping with Simple Type Translator

Description of "Figure 53-13 Java Class for XML Direct Mapping with Simple Type Translator"

Figure 53-14 illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema in Example 53-22.

Figure 53-14 XML Direct Mapping with a Simple Type Translator

Description of "Figure 53-14 XML Direct Mapping with a Simple Type Translator"

Example 53-23 shows how to configure this mapping in Java.

Example 53-23 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 Section 17.2.6.4, "Simple Type Translator".

53.4 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 Chapter 56, "Configuring an XML Composite Direct Collection Mapping" for more information.

53.4.1 Mapping to Multiple Text Nodes

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

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

53.4.1.1 Mapping to a Simple Sequence

Given the XML schema in Example 53-24, Figure 53-15 illustrates a composite direct collection XML mapping to a simple sequence of text nodes in a corresponding XML document. Example 53-25 shows how to configure this mapping in Java.

Example 53-24 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>

Figure 53-15 Composite Direct Collection XML Mapping to a Simple Sequence

Description of "Figure 53-15 Composite Direct Collection XML Mapping to a Simple Sequence"

Example 53-25 Java for Composite Direct Collection XML Mapping to a Simple Sequence

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

53.4.1.2 Mapping to a Sequence in a Subelement

Given the XML schema in Example 53-26, Figure 53-16 illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. Example 53-27 shows how to configure this mapping in Java.

Example 53-26 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>

Figure 53-16 Composite Direct Collection XML Mapping to a Subelement Sequence

Description of "Figure 53-16 Composite Direct Collection XML Mapping to a Subelement Sequence"

Example 53-27 Java for Composite Direct Collection XML Mapping to a Subelement Sequence

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

53.4.2 Mapping to Multiple Attributes

Given the XML schema in Example 53-28, Figure 53-17 illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. Example 53-29 shows how to configure this mapping in Java.

Example 53-28 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>

Figure 53-17 Composite Direct Collection XML Mapping to Multiple Attributes

Description of "Figure 53-17 Composite Direct Collection XML Mapping to Multiple Attributes"

Example 53-29 Java for Composite Direct Collection XML Mapping to Multiple Attributes

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

53.4.3 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 Example 53-30, Figure 53-18 illustrates a composite direct collection XML mapping to a single text node in a corresponding XML document. Example 53-31 shows how to configure this mapping in Java.

Example 53-30 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>

Figure 53-18 XML Composite Direct Collection Mapping to a Single Text Node

Description of "Figure 53-18 XML Composite Direct Collection Mapping to a Single Text Node"

Example 53-31 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);

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

Given the XML schema in Example 53-32, Figure 53-19 illustrates a composite direct collection XML mapping to a single attribute in a corresponding XML document. Example 53-33 shows how to configure this mapping in Java.

Example 53-32 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>

Figure 53-19 XML Composite Direct Collection Mapping to a Single Attribute

Description of "Figure 53-19 XML Composite Direct Collection Mapping to a Single Attribute"

Example 53-33 Java for XML Composite Direct Collection Mapping to a Single Attribute

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

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

Given the XML schema in Example 53-34, Figure 53-20 illustrates a composite direct collection XML mapping to a list of unions in a corresponding XML document. Example 53-35 shows how to configure this mapping in Java.

Example 53-34 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>

Figure 53-20 Composite XML Direct Collection Mapping to List of Unions

Description of "Figure 53-20 Composite XML Direct Collection Mapping to List of Unions"

Example 53-35 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);

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

Given the XML schema in Example 53-36, Figure 53-21 illustrates an XML composite direct collection mapping to a union of lists in a corresponding XML document. Example 53-37 shows how to configure this mapping in Java.

Example 53-36 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>

Figure 53-21 XML Composite Direct Collection Mapping to a Union of Lists

Description of "Figure 53-21 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.

Example 53-37 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);

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

By default, TopLink 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 Example 53-38, Figure 53-22 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. Example 53-39 shows how to configure this mapping in Java.

Example 53-38 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>

Figure 53-22 XML Composite Direct Collection Mapping with Specified Content Type

Description of "Figure 53-22 XML Composite Direct Collection Mapping with Specified Content Type"

Example 53-39 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);

53.5 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 Chapter 57, "Configuring an XML Composite Object Mapping" for more information.

53.5.1 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 Example 53-40, Figure 53-23 illustrates an XML composite object mapping into the parent record in a corresponding XML document. Example 53-41 shows how to configure this mapping in Java.

Example 53-40 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>

Figure 53-23 XML Composite Object Mapping into the Parent Record

Description of "Figure 53-23 XML Composite Object Mapping into the Parent Record"

Example 53-41 Java for XML Composite Object Mapping into the Parent Record

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

53.5.2 Mapping to an Element

Given the XML schema in Example 53-42, Figure 53-24 illustrates an XML composite object mapping to an element in a corresponding XML document. Example 53-43 shows how to configure this mapping in Java.

Example 53-42 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>

Figure 53-24 XML Composite Object Mapping to an Element

Description of "Figure 53-24 XML Composite Object Mapping to an Element"

Example 53-43 Java for XML Composite Object Mapping to an Element

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

53.5.3 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 Example 53-44, Figure 53-25 illustrates an XML composite object mapping to different elements by name in a corresponding XML document. Example 53-45 shows how to configure this mapping in Java.

Example 53-44 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>

Figure 53-25 XML Composite Object Mapping to Elements by Name

Description of "Figure 53-25 XML Composite Object Mapping to Elements by Name"

Example 53-45 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);

53.5.4 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 Example 53-46, Figure 53-26 illustrates an XML composite object mapping to different elements by position in a corresponding XML document. Example 53-47 shows how to configure this mapping in Java.

Example 53-46 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>

Figure 53-26 XML Composite Object Mapping to Elements by Position

Description of "Figure 53-26 XML Composite Object Mapping to Elements by Position"

Example 53-47 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);

53.6 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 a TopLink 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 XMLCompositeCollectionMapping class allows a reference to the mapped class and the indexing type for that class.

Given the XML schema in Example 53-48, Figure 53-27 illustrates an XML composite collection mapping to different elements by position in a corresponding XML document. Example 53-49 shows how to configure this mapping in Java for a Collection attribute, and Example 53-50 shows how to configure this mapping in Java for a Map attribute.

Example 53-48 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>

Figure 53-27 XML Composite Collection Mapping

Description of "Figure 53-27 XML Composite Collection Mapping"

Example 53-49 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);

Example 53-50 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 Chapter 58, "Configuring an XML Composite Collection Mapping" for more information.

53.7 XML Any Object Mapping

The XML any object mapping is similar to the composite object XML mapping (see Section 53.5, "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 Section 16.2.12, "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 Example 53-51, Figure 53-28 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.

Example 53-51 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>

Figure 53-28 Java Classes for XML Any Object Mapping

Description of "Figure 53-28 Java Classes for XML Any Object Mapping"

Figure 53-29, Figure 53-30, and Figure 53-31 illustrate how the XML any object mapping maps to an Address, PhoneNumber, and String (respectively) in XML documents that conform to the schema in Example 53-51.

Figure 53-29 XML Any Object Mapping to Address Type

Description of "Figure 53-29 XML Any Object Mapping to Address Type"

Figure 53-30 XML Any Object Mapping to PhoneNumber Type

Description of "Figure 53-30 XML Any Object Mapping to PhoneNumber Type"

Figure 53-31 XML Any Object Mapping to String Type

Description of "Figure 53-31 XML Any Object Mapping to String Type"

Example 53-52 shows how to configure this mapping in Java.

Example 53-52 Java for XML Any Object Mapping

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

For more information about TopLink XML mapping support for xs:any and xs:anyType, see Section 53.2.5, "xs:any and xs:anyType Support".

See Chapter 59, "Configuring an XML Any Object Mapping" for more information.

53.8 XML Any Collection Mapping

The XML any collection mapping is similar to the composite collection XML mapping (see Section 53.6, "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 Section 16.2.12, "Default Root Element").

Given the XML schema in Example 53-53, Figure 53-32 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.

Example 53-53 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>

Figure 53-32 Java Classes for XML Any Collection Mapping

Description of "Figure 53-32 Java Classes for XML Any Collection Mapping"

Figure 53-33 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 Example 53-53.

Figure 53-33 XML Any Collection Mapping

Description of "Figure 53-33 XML Any Collection Mapping"

Example 53-54 shows how to configure this mapping in Java.

Example 53-54 Java for XML Any Collection Mapping

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

For more information about TopLink XML mapping support for xs:any and xs:anyType, see Section 53.2.5, "xs:any and xs:anyType Support".

See Chapter 60, "Configuring an XML Any Collection Mapping" for more information.

53.9 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 oracle.toplink.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 Figure 53-34 illustrates, you configure the transformation mapping with an oracle.toplink.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 oracle.toplink.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.

Figure 53-34 XML Transformation Mappings

Description of "Figure 53-34 XML Transformation Mappings "

See Chapter 61, "Configuring an XML Transformation Mapping" for more information.

53.10 XML Object Reference Mapping

The oracle.toplink.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, TopLink provides support for composite keys, as well as for foreign key grouping elements.

Note:

You should group together elements mapped to keys. Also, TopLink 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 Section 53.2.3, "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.

See Chapter 62, "Configuring an XML Object Reference Mapping" for more information.

53.10.1 Mapping Using a Single Key

Figure 53-35, Example 53-55, Example 53-56 and Example 53-57 demonstrate how to map one element to another using a single key.

Figure 53-35 Class Diagram

Description of "Figure 53-35 Class Diagram"

Example 53-55 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>
...

Example 53-56 shows how to create an XMLObjectReferenceMapping, set a single key on source, and then add the mapping to the descriptor.

Example 53-56 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);
...

Example 53-57 shows how to define the primary key field on the descriptor.

Example 53-57 Using Single Key - Project Class - Project Descriptor

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

53.10.2 Mapping Using a Composite Key

Figure 53-35, Example 53-58, Example 53-59 and Example 53-60 demonstrate how to map one element to another using a composite key.

Example 53-58 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>
...

Example 53-59 shows how to create an XMLObjectReferenceMapping, set a composite key on source, and then add the mapping to the descriptor.

Example 53-59 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);
...

Example 53-60 shows how to define a composite primary key field on the descriptor.

Example 53-60 Using Composite Key - Project Class - Project Descriptor

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

53.10.3 Mapping Using JAXB

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

Note:

The JAXB 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.

Figure 53-35, Example 53-61, Example 53-62, Example 53-63 and Example 53-64 demonstrate how to map one XML element to another using JAXB annotations.

Example 53-61 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;
    ...
}

Example 53-62 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>
...

Example 53-63 shows how to create an XMLObjectReferenceMapping, set a key on source, and then add the mapping to the descriptor.

Example 53-63 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);
...

Example 53-64 shows how to define the primary key field on the descriptor.

Example 53-64 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
Chapter 47, "Introduction to XML Projects"

53.11 XML Collection Reference Mapping

The oracle.toplink.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, TopLink provides support for foreign key grouping elements.

Note:

You should group together elements mapped to keys. Also, TopLink 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 Section 53.2.3, "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.

Figure 53-36, Example 53-65, Example 53-66 and Example 53-67 demonstrate how to map one element to another using a single key.

Figure 53-36 Class Diagram

Description of "Figure 53-36 Class Diagram"

Example 53-65 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>
...

Example 53-66 shows how to create an XMLCollectionReferenceMapping, set a single key on source, and then add the mapping to the descriptor.

Example 53-66 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);
...

Example 53-67 shows how to define the primary key field on the descriptor.

Example 53-67 Using a Single Key - Project Class - Project Descriptor

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

Figure 53-36, Example 53-68, Example 53-69 and Example 53-70 demonstrate how to map one element to another using a single key as a space-separated list.

Example 53-68 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>
...

Example 53-69 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.

Example 53-69 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);
...

Example 53-70 shows how to define the primary key field on the descriptor.

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

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

See Chapter 63, "Configuring an XML Collection Reference Mapping" for more information.

53.12 XML Binary Data Mapping

The oracle.toplink.ox.mappings.XMLBinaryDataMapping is a direct mapping (see Section 53.3, "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 Section 12.16, "Optimizing Storage and Retrieval of Binary Data in XML".

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

Example 53-71 shows how to create an XMLBinaryDataMapping, set some of its properties, and then add the mapping to a descriptor.

Example 53-71 Creating an XML Binary Data Mapping

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

See Chapter 64, "Configuring an XML Binary Data Mapping" for more information.

53.13 XML Binary Data Collection Mapping

The oracle.toplink.ox.mappings.XMLBinaryDataCollectionMapping is very similar to the XMLBinaryDataMapping (see Section 53.12, "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:

Example 53-72 shows how to create an XMLBinaryDataCollectionMapping, set some of its properties, and then add the mapping to a descriptor.

Example 53-72 Creating an XML Binary Data Collection Mapping

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

For more information, see the following:

53.14 XML Fragment Mapping

The oracle.toplink.ox.mappings.XMLFragmentMapping is a direct mapping (see Section 53.3, "XML Direct Mapping") that provides you a means to keep a part of an XML tree as a node.

The XMLFragmentMapping also lets you set the XPath (see Section 53.2.3, "XPath Support").

Example 53-73 shows how to create an XMLFragmentMapping, set some of its properties, and then add the mapping to a descriptor.

Example 53-73 Creating an XML Fragment Mapping

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

See Chapter 66, "Configuring an XML Fragment Mapping" for more information.

53.15 XML Fragment Collection Mapping

The oracle.toplink.ox.mappings.XMLFragmentCollectionMapping is similar to the XMLFragmentMapping (see Section 53.14, "XML Fragment Mapping,"), except that it allows you to keep a part of an XML tree as a collection of nodes.

Example 53-74 shows how to create an XMLFragmentMapping, set the XPath (see Section 53.2.3, "XPath Support"), and then add the mapping to a descriptor.

Example 53-74 Creating an XML Fragment Collection Mapping

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

See Chapter 67, "Configuring an XML Fragment Collection Mapping" for more information.

53.16 XML Choice Object Mapping

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

Unlike other TopLink XML mappings, instead of setting a single XPath, you use the addChoiceElement method to specify an XPath 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 (see Section 53.2.10, "Substitution Groups") in an XML schema.

Example 53-75 shows how to create an XMLChoiceObjectMapping, set the XPath (see Section 53.2.3, "XPath Support"), and then add the mapping to a descriptor.

Example 53-75 Creating an XML Choice Object Mapping

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

See Chapter 68, "Configuring an XML Choice Object Mapping" for more information.

53.17 XML Choice Collection Mapping

The oracle.toplink.ox.mappings.XMLChoiceCollectionMapping is similar to XMLChoiceObjectMapping (see Section 53.16, "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 (see Section 53.2.10, "Substitution Groups") elements.

Example 53-76 shows how to create an XMLChoiceCollectionMapping, set the XPath, and then add the mapping to a descriptor.

Example 53-76 Creating an XML Choice Collection Mapping

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

See Chapter 69, "Configuring an XML Choice Collection Mapping" for more information.

53.18 XML Any Attribute Mapping

The oracle.toplink.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, TopLink will ignored that attribute during the unmarshall operation.

The XMLAnyAttributeMapping lets you set the XPath (see Section 53.2.3, "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.

Example 53-77 shows how to create an XMLAnyAttributeMapping, set the XPath, and then add the mapping to a descriptor.

Example 53-77 Creating an XML Any Attribute Mapping

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

See Chapter 70, "Configuring an XML Any Attribute Mapping" for more information.