Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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".