Thank you for your feedback!Categories
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:
For information on mapping concepts and features common to more than one type of TopLink mappings, see Chapter 17, "Introduction to Mappings".
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" |
|
|
|
|
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" |
|
|
|
|
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" 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" |
|
|
|
|
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" |
|
|
|
|
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" |
|
|
|
|
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. |
|
|
|
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:
Consider the XML document shown in Example 53-1.
Sign In<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
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.
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".
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".
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... |
|---|---|
|
Element with a singleFoot 1 |
|
|
Element with an unnamed sequenceFootref 2 Element with a named sequenceFoot 2 Root element of type |
Footnote 1 minOccurs and maxOccurs are both equal to 1.
Footnote 2 maxOccurs is greater than 1.
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".
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"
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".
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:
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.
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.
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
XML direct mappings map a Java attribute directly to XML text nodes. You can use an XML direct mapping in the following scenarios:
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").This section describes using an XML direct mapping when:
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
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
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()");
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
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()");
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
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()");
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
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
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);
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
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
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
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
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);
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
Note that in this example, valid XML documents contain either all xsd:double, all xsd:date, or all xsd:integer values.
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
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);
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
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
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".
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 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.
This section describes using a composite direct collection XML mapping when doing the following:
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
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
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
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
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
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
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);
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
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);
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
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);
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:
See Chapter 57, "Configuring an XML Composite Object Mapping" for more information.
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
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
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
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);
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
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);
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
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.
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
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
Figure 53-30 XML Any Object Mapping to PhoneNumber Type
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.
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
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.
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.
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.
See Chapter 61, "Configuring an XML Transformation Mapping" for more information.
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.
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.
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.
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.
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
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.
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.
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.
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:
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.
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.
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.
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.
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.