| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
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 describes the following:
TopLink supports the XML mappings listed in Table 62-1.
Table 62-1 TopLink XML Mapping Types
| Mapping Type | Description | Type | TopLink Workbench | Java |
|---|---|---|---|---|
|
|
Map a simple object attribute to an XML attribute or text node. |
Basic |
 |
|
|
"XML Composite Direct Collection Mapping" |
Map a collection of simple object attributes to XML attributes or text nodes. |
Basic |
|
|
|
"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. |
Basic |
|
|
|
"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. |
Basic |
|
|
|
|
The any object XML mapping is similar to the composite object XML mapping (see "XML Composite Object Mapping"), except that the reference object may be of different types (including |
Advanced |
|
|
|
|
The any collection XML mapping is similar to the composite collection XML mapping (see "XML Composite Collection Mapping") except that the referenced objects may be of different types (including |
Advanced |
|
|
|
|
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. |
Advanced |
|
|
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:
Consider the XML document shown in Example 62-1.
Example 62-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 62-2 summarizes the XML simple and complex types supported by each TopLink XML mapping.
Table 62-2 XML Mapping Support for XML Simple and Complex Types
| Mapping | XML Attribute | XML Text Node | XML Element |
|---|---|---|---|
|
|
|
|
|
|
XML Composite Direct Collection Mapping |
|
|
|
|
|
|
|
|
|
XML Composite Collection Mapping |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
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".
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".
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 62-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 62-3 XML Mappings and XML Schema xs:any and xs:anyType
| Use XML Mapping ... | To Map XML Schema Definition ... |
|---|---|
|
Element with a singleFoot 1 unnamed complex type specified as |
|
|
Element with an unnamed sequenceFootref 2 of complex types specified as Element with a named sequenceFoot 2 of complex types of type 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 "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".
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"
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".
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 64, "Configuring an XML Direct Mapping" for more information.
|
Note: Do not confuse an XML direct mapping with a relational direct-to-XMLType mapping (see "Direct-to-XMLType Mapping"). |
This section describes using an XML direct mapping when:
Given the XML schema in Example 62-2, Figure 62-1 illustrates an XML direct mapping to a simple text node in a corresponding XML document. Example 62-3 shows how to configure this mapping in Java.
Example 62-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 62-1 XML Direct Mapping to Simple Text Node
Given the XML schema in Example 62-4, Figure 62-2 illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document. Example 62-5 shows how to configure this mapping in Java.
Example 62-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 62-2 XML Direct Mapping to a Text Node in a Simple Sequence
Example 62-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 62-6, Figure 62-3 illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document. Example 62-7 shows how to configure this mapping in Java.
Example 62-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 62-3 XML Direct Mapping to a Text Node in a Subelement
Example 62-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 62-8, Figure 62-4 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 62-9 shows how to configure this mapping in Java.
Example 62-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 62-4 XML Direct Mapping to Text Node by Position
Example 62-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 62-8, Figure 62-4 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 62-9 shows how to configure this mapping in Java.
Example 62-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 62-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 62-8, Figure 62-4 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 62-9 shows how to configure this mapping in Java.
Example 62-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 62-6 XML Direct Mapping to a Specified Schema Type
Example 62-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 62-14, Figure 62-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 62-15 shows how to configure this mapping in Java.
Example 62-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 62-7 XMLDirect Mapping to a List Field
Given the XML schema in Example 62-16, Figure 62-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 62-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 62-8 Java Class for XML Direct Mapping to a Union Field
Figure 62-9 illustrates an XML direct mapping to a union field in an XML document that conforms to the schema in Example 62-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 62-9 XML Direct Mapping to the First Valid Union Type
Figure 62-10 illustrates an XML direct mapping to union field in another XML document that conforms to the schema in Example 62-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 62-10 XML Direct Mapping to Another Valid Union Type
Example 62-17 shows how to configure this mapping in Java.
Example 62-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 62-18, Figure 62-11 illustrates an XML direct mapping to a union of lists in a corresponding XML document. Example 62-19 shows how to configure this mapping in Java.
Example 62-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 62-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 62-20, Figure 62-12 illustrates a Java class that can be mapped to a corresponding XML document. Example 62-27 shows how to configure this mapping in Java.
Example 62-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 62-12 Java Class for XML Direct Mapping to a Union of Unions
Example 62-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 62-22, Figure 62-13 illustrates a Java class that can be mapped to a corresponding XML document.
Example 62-22 Schema for XML Direct Mapping with Simple Type Translator
...
<xs:element name="area-code" type="anySimpleType"/>
<xs:element name="number" type="anySimpleType"/>
...
Figure 62-13 Java Class for XML Direct Mapping with Simple Type Translator
Figure 62-14 illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema in Example 62-22.
Figure 62-14 XML Direct Mapping with a Simple Type Translator
Example 62-23 shows how to configure this mapping in Java.
Example 62-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 "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 65, "Configuring an XML Composite Direct Collection Mapping" for more information.
This section describes using a composite direct collection XML mapping when:
Given the XML schema in Example 62-24, Figure 62-15 illustrates a composite direct collection XML mapping to a simple sequence of text nodes in a corresponding XML document. Example 62-25 shows how to configure this mapping in Java.
Example 62-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 62-15 Composite Direct Collection XML Mapping to a Simple Sequence
Given the XML schema in Example 62-26, Figure 62-16 illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. Example 62-27 shows how to configure this mapping in Java.
Example 62-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 62-16 Composite Direct Collection XML Mapping to a Subelement Sequence
Given the XML schema in Example 62-28, Figure 62-17 illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. Example 62-29 shows how to configure this mapping in Java.
Example 62-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 62-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 62-30, Figure 62-18 illustrates a composite direct collection XML mapping to a single text node in a corresponding XML document. Example 62-31 shows how to configure this mapping in Java.
Example 62-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 62-18 XML Composite Direct Collection Mapping to a Single Text Node
Given the XML schema in Example 62-32, Figure 62-19 illustrates a composite direct collection XML mapping to a single attribute in a corresponding XML document. Example 62-33 shows how to configure this mapping in Java.
Example 62-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 62-19 XML Composite Direct Collection Mapping to a Single Attribute
Given the XML schema in Example 62-34, Figure 62-20 illustrates a composite direct collection XML mapping to a list of unions in a corresponding XML document. Example 62-35 shows how to configure this mapping in Java.
Example 62-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 62-20 Composite XML Direct Collection Mapping to List of Unions
Example 62-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 62-34, Figure 62-20 illustrates an XML composite direct collection mapping to a list of unions in a corresponding XML document. Example 62-35 shows how to configure this mapping in Java.
Example 62-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 62-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 62-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 62-38, Figure 62-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 62-39 shows how to configure this mapping in Java.
Example 62-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 62-22 XML Composite Direct Collection Mapping with Specified Content Type
Example 62-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 66, "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 62-40, Figure 62-23 illustrates an XML composite object mapping into the parent record in a corresponding XML document. Example 62-41 shows how to configure this mapping in Java.
Example 62-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 62-23 XML Composite Object Mapping into the Parent Record
Given the XML schema in Example 62-42, Figure 62-24 illustrates an XML composite object mapping to an element in a corresponding XML document. Example 62-43 shows how to configure this mapping in Java.
Example 62-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 62-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 62-44, Figure 62-25 illustrates an XML composite object mapping to different elements by name in a corresponding XML document. Example 62-45 shows how to configure this mapping in Java.
Example 62-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 62-25 XML Composite Object Mapping to Elements by Name
Example 62-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 62-44, Figure 62-25 illustrates an XML composite object mapping to different elements by position in a corresponding XML document. Example 62-45 shows how to configure this mapping in Java.
Example 62-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 62-26 XML Composite Object Mapping to Elements by Position
Example 62-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 CompositeCollectionMapping class allows a reference to the mapped class and the indexing type for that class.
Given the XML schema in Example 62-48, Figure 62-27 illustrates an XML composite collection mapping to different elements by position in a corresponding XML document. Example 62-49 shows how to configure this mapping in Java for a Collection attribute and Example 62-50 shows how to configure this mapping in Java for a Map attribute.
Example 62-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 62-27 XML Composite Collection Mapping
Example 62-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 62-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 67, "Configuring an XML Composite Collection Mapping" for more information.
The XML any object mapping is similar to the composite object XML mapping (see "XML Composite Object Mapping") except that the reference object may be of any type (including String). This type does not need to be related to any other particular type through inheritance or a common interface.
The corresponding object attribute value can be an instance of any object with a Descriptor, a java.lang.Object, a java.lang.String, a primitive object (such as java.lang.Integer), or a user defined type generic enough for all possible application values.
This mapping is useful with the following XML schema constructs:
any
choice
substitution groups
Referenced objects can specify a default root element on their descriptor (see "Default Root Element").
|
Note: The undefined document root element of a referenced object is ignored during marshalling with an any collection mapping and object mapping. |
Given the XML schema in Example 62-51, Figure 62-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 62-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 62-28 Java Classes for XML Any Object Mapping
Figure 62-29, Figure 62-30, and Figure 62-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 62-51.
Figure 62-29 XML Any Object Mapping to Address Type
Figure 62-30 XML Any Object Mapping to PhoneNumber Type
Figure 62-31 XML Any Object Mapping to String Type
Example 62-49 shows how to configure this mapping in Java.
Example 62-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 "xs:any and xs:anyType Support".
See Chapter 68, "Configuring an XML Any Object Mapping" for more information.
The XML any collection mapping is similar to the composite collection XML mapping (see "XML Composite Collection Mapping"), except that the referenced objects may be of different types (including String). These types need not be related to each other through inheritance or a common interface.
The corresponding object attribute value can be an instance of any object with a Descriptor, a java.lang.Object, a java.lang.String, a primitive object (such as java.lang.Integer), or a user defined type generic enough for all possible application values.
This mapping is useful with the following XML schema constructs:
any
choice
substitution groups
Each of the referenced objects (except String) must specify a default root element on their descriptor (see "Default Root Element").
Given the XML schema in Example 62-53, Figure 62-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 62-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 62-32 Java Classes for XML Any Collection Mapping
Figure 62-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 62-53.
Example 62-54 shows how to configure this mapping in Java.
Example 62-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 "xs:any and xs:anyType Support".
See Chapter 69, "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 62-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 70, "Configuring an XML Transformation Mapping" for more information.
