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 TopLink Workbench and its rich graphical user interface (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

Mapping to Simple and Complex Types

Consider the XML document shown in Example 65-1.

Example 65-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 65-2 summarizes the XML simple and complex types supported by each TopLink XML mapping.

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

Mapping	XML Attribute	XML Text Node	XML Element
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

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 TopLink 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 TopLink persists data in an XML document.

XPath Support

TopLink uses XPath statements to efficiently map the attributes of a Java object to locations in an XML document. 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 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.

Table 65-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 65-3 XML Mappings and XML Schema xs:any and xs:anyType

Use XML Mapping ...	To Map XML Schema Definition ...
see "XML Any Object Mapping"	Element with a singleFoot 1  unnamed complex type specified as xs:any.
see "XML Any Collection Mapping"	Element with an unnamed sequenceFootref 2 of complex types specified as xs:any. Element with a named sequenceFoot 2  of complex types of type xs:anyType. Root element of type xs:anyType.

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

^Footnote 2 maxOccurs is greater than 1.

jaxb:class Support

You can configure an XML composite object mapping (see "XML Composite Object Mapping") 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 or XMLCompositeDirectCollectionMapping with XML documents.

For more information, see "Mappings and JAXB Typesafe Enumerations"

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 "Mapping Converters and Transformers".