Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Introduction to XML Mappings (ELUG)
Contents
- 1 XML Mapping Types
- 2 XML Mapping Concepts
- 3 XML Direct Mapping
- 3.1 Mapping to a Text Node
- 3.2 Mapping to an Attribute
- 3.3 Mapping to a Specified Schema Type
- 3.4 Mapping to a List Field with an XML Direct Mapping
- 3.5 Mapping to a Union Field with an XML Direct Mapping
- 3.6 Mapping to a Union of Lists with an XML Direct Mapping
- 3.7 Mapping to a Union of Unions with an XML Direct Mapping
- 3.8 Mapping with a Simple Type Translator
- 4 XML Composite Direct Collection Mapping
- 4.1 Mapping to Multiple Text Nodes
- 4.2 Mapping to Multiple Attributes
- 4.3 Mapping to a Single Text Node with an XML Composite Direct Collection Mapping
- 4.4 Mapping to a Single Attribute with an XML Composite Direct Collection Mapping
- 4.5 Mapping to a List of Unions with an XML Composite Direct Collection Mapping
- 4.6 Mapping to a Union of Lists with an XML Composite Direct Collection Mapping
- 4.7 Specifying the Content Type of a Collection with an XML Composite Direct Collection Mapping
- 5 XML Composite Object Mapping
- 6 XML Composite Collection Mapping
- 7 XML Any Object Mapping
- 8 XML Any Collection Mapping
- 9 XML Transformation Mapping
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).
For information on mapping concepts and features common to more than one type of EclipseLink mappings, see Introduction to Mappings.
XML Mapping Types
EclipseLink supports the XML mappings listed in this table
EclipseLink XML Mapping Types
| Mapping Type | Description | EclipseLink Workbench | Java |
|---|---|---|---|
|
XML direct mapping (see #XML Direct Mapping) |
Map a simple object attribute to an XML attribute or text node. |
|
|
|
XML composite direct collection mapping (see #XML Composite Direct Collection Mapping) |
Map a collection of simple object attributes to XML attributes or text nodes. |
|
|
|
XML composite object mapping (see #XML Composite Object Mapping) |
Map any attribute that contains a single object to an XML element. The EclipseLink runtime uses the descriptor for the referenced object to populate the contents of that element. |
|
|
|
XML composite collection mapping (see #XML Composite Collection Mapping) |
Map an attribute that contains a homogenous collection of objects to multiple XML elements. The EclipseLink runtime uses the descriptor for the referenced object to populate the contents of those elements. |
|
|
|
XML any object mapping (see #XML Any Object Mapping) |
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 String), not necessarily related to each other through inheritance or a common interface. |
|
|
|
XML any collection mapping (see #XML Any Collection Mapping) |
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 String), not necessarily related to each other through inheritance or a common interface. |
|
|
|
XML transformation mapping (see #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 Mapping Concepts
You can map the attributes of a Java object to a combination of XML simple and complex types using a wide variety of XML mapping types.
EclipseLink stores XML mappings for each class in the class descriptor. EclipseLink 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, we recommend that you use the Workbench to set the descriptor properties and configure the mappings.
This section describes concepts unique to EclipseLink XML mappings, including the following:
- #Mapping to Simple and Complex Types
- #Mapping Order
- [#BABIGBHF1 XPath Support]]
- #xsd:list and xsd:union Support
- #xs:any and xs:anyType Support
- #jaxb:class Support
- #Typesafe Enumeration Support
- #Mapping Extensions
Mapping to Simple and Complex Types
Consider the XML document shown in this example
XML Document
<EMPLOYEE ID="123">
<NAME>Jane Doe</NAME>
<ADDRESS>
<STREET>123 Any St.</STREET>
<CITY>MyCity</CITY>
</ADDRESS>
</EMPLOYEE>
In general, using EclipseLink 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).
This table summarizes the XML simple and complex types supported by each EclipseLink XML mapping.
XML Mapping Support for XML Simple and Complex Types
| Mapping | XML Attribute | XML Text Node | XML Element |
|---|---|---|---|
|
XML direct (see [[#XML Direct Mapping]) |
|
|
|
|
XML composite direct collection (see #XML Composite Direct Collection Mapping) |
|
|
|
|
XML composite object (see #XML Composite Object Mapping) |
|
|
|
|
XML composite collection (see #XML Composite Collection Mapping) |
|
|
|
|
XML any object (see [[#XML Any Object Mapping]) |
|
|
|
|
XML any collection (see #XML Any Collection Mapping) |
|
|
|
|
XML transformation (see #XML Transformation Mapping) |
|
|
|
Mapping Order
Unlike relational database mappings, the order in which mappings are persisted in XML is significant.
The order in which you define XML mappings in EclipseLink (whether in the 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 EclipseLink persists data in an XML document.
XPath Support
EclipseLink uses XPath statements to efficiently map the attributes of a Java object to locations in an XML document. For more information about using XPath with XML mappings, see Mappings and XPath.
xsd:list and xsd:union Support
You can use XML direct (see [[#XML Direct Mapping]) and composite direct collection (see [[#XML Composite Direct Collection Mapping]) mappings to map to xsd:list and xsd:union types in an XML document.
For more information, see Mappings and xsd:list and xsd:union Types.
xs:any and xs:anyType Support
In an XML schema, you can define elements and complex types that correspond to any data type using xs:any and xs:anyType. You can map objects to such elements and complex types using XML mappings XMLAnyObjectMapping and XMLAnyCollectionMapping.
This table lists the XML mappings to use with common applications of xs:any and xs:anyType. For more details, see the specified XML mapping type.
XML Mappings and XML Schema xs:any and xs:anyType
| Use XML Mapping... | To Map XML Schema Definition... |
|---|---|
|
See [[#XML Any Object Mapping] |
Element with a single Foot 1 unnamed complex type specified as xs:any. |
|
See [[#XML Any Collection Mapping] |
Element with an unnamed sequence Footref 2 ] of complex types specified as xs:any.Element with a named sequence Foot 2 of complex types of type xs:anyType.Root element of type xs:anyType. |
Footnote 1 minOccurs and maxOccurs are both equal to 1.
Footnote 2 maxOccurs is greater than 1.
jaxb:class Support
You can configure an XML composite object mapping (see [[#XML Composite Object Mapping]) to accommodate jaxb:class customizations with the following XSD structures:
- all
- sequence
- choice
- group
For more information, see Mappings and the jaxb:class Customization.
Typesafe Enumeration Support
You can map a Java attribute to such a typesafe enumeration using the JAXBTypesafeEnumConverter with an XMLDirectMapping or XMLCompositeDirectCollectionMapping with XML documents.
For more information, see Mappings and JAXB Typesafe Enumerations
Mapping Extensions
If existing EclipseLink 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 Mapping
XML direct mappings map a Java attribute directly to XML text nodes. You can use an XML direct mapping in the following scenarios:
- #Mapping to a Text Node
- #Mapping to an Attribute
- #Mapping to a Specified Schema Type
- #Mapping to a List Field with an XML Direct Mapping
- #Mapping to a Union Field with an XML Direct Mapping
- #Mapping to a Union of Lists with an XML Direct Mapping
- #Mapping to a Union of Unions with an XML Direct Mapping
- #Mapping with a Simple Type Translator
See Chapter 60, "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). |
Mapping to a Text Node
This section describes using an XML direct mapping when:
- #Mapping to a Simple Text Node
- #Mapping to a Text Node in a Simple Sequence
- #Mapping to a Text Node in a Subelement
- #Mapping to a Text Node by Position
Mapping to a Simple Text Node
Given the XML schema in Schema for XML Direct Mapping to Simple Text Node, XML Direct Mapping to Simple Text Node illustrates an XML direct mapping to a simple text node in a corresponding XML document. Java for XML Direct Mapping to Simple Text Node shows how to configure this mapping in Java.
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>
<spanid="Figure 58-1"></span>
XML Direct Mapping to Simple Text Node
Java for XML Direct Mapping to Simple Text Node
XMLDirectMapping numberMapping = new XMLDirectMapping();
numberMapping.setAttributeName("number");
numberMapping.setXPath("text()");
Mapping to a Text Node in a Simple Sequence
Given the XML schema in Schema for XML Direct Mapping to a Text Node in a Simple Sequence, XML Direct Mapping to a Text Node in a Simple Sequence illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document. Java for XML Direct Mapping to a Text Node in a Simple Sequence shows how to configure this mapping in Java.
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>
XML Direct Mapping to a Text Node in a Simple Sequence
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()");
Mapping to a Text Node in a Subelement
Given the XML schema in Schema for XML Direct Mapping to a Text Node in a Subelement', XML Direct Mapping to a Text Node in a Subelement' illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document. Java for XML Direct Mapping to a Text Node in a Subelemen shows how to configure this mapping in Java.
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>
XML Direct Mapping to a Text Node in a Subelement
[img_text/dxmse.htm Description of "Figure 58-3 XML Direct Mapping to a Text Node in a Subelement"]
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()");
Mapping to a Text Node by Position
Given the XML schema in Schema for XML Direct Mapping to Text Node by Position, XML Direct Mapping to Text Node by Position illustrates an XML direct mapping to a text node by position in a corresponding XML document. Java for XML Direct Mapping to Text Node by Position shows how to configure this mapping in Java.
' 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>
XML Direct Mapping to Text Node by Position
[[Image:dxmpos.gif|XML Direct Mapping to Text Node by Position"]
' 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()");
Mapping to an Attribute
Given the XML schema in [[#Example 58-10], [[#Figure 58-5] illustrates an XML direct mapping to a text node by position in a corresponding XML document. [[#Example 58-11] shows how to configure this mapping in Java.
Example 58-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 58-5 XML Direct Mapping to an Attribute
[img_text/dxmatt.htm Description of "Figure 58-5 XML Direct Mapping to an Attribute"]
Example 58-11 Java for XML Direct Mapping to an Attribute
XMLDirectMapping idMapping = new XMLDirectMapping();
idMapping.setAttributeName("id");
idMapping.setXPath("@id");
Mapping to a Specified Schema Type
In most cases, EclipseLink 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 EclipseLink 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 58-12], [[#Figure 58-6] illustrates an XML direct mapping to a text node by position in a corresponding XML document. [[#Example 58-13] shows how to configure this mapping in Java.
Example 58-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 58-6 XML Direct Mapping to a Specified Schema Type
[img_text/dxmscht.htm Description of "Figure 58-6 XML Direct Mapping to a Specified Schema Type"]
Example 58-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);
Mapping to a List Field with an XML Direct Mapping
Given the XML schema in [[#Example 58-14], [[#Figure 58-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 58-15] shows how to configure this mapping in Java.
Example 58-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 58-7 XMLDirect Mapping to a List Field
[img_text/dcxmstn.htm Description of "Figure 58-7 XMLDirect Mapping to a List Field"]
Example 58-15 Java for XML Direct Mapping to a List Field Node
XMLDirectMapping tasksMapping = new XMLDirectMapping();
tasksMapping.setAttributeName("tasks");
XMLField myField = new XMLField("tasks/text()"); // pass in the XPath
myField.setUsesSingleNode(true);
tasksMapping.setField(myField);
Mapping to a Union Field with an XML Direct Mapping
Given the XML schema in [[#Example 58-16], [[#Figure 58-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 58-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 58-8 Java Class for XML Direct Mapping to a Union Field
[img_text/dxmuc.htm Description of "Figure 58-8 Java Class for XML Direct Mapping to a Union Field"]
[[#Figure 58-9] illustrates an XML direct mapping to a union field in an XML document that conforms to the schema in [[#Example 58-16]. When EclipseLink 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, EclipseLink converts the value to the appropriate type. If the Object attribute is specific enough to trigger an appropriate value, EclipseLink will use that type instead. Otherwise, EclipseLink uses a default (in this case BigDecimal). You can override this behavior in Java code.
Figure 58-9 XML Direct Mapping to the First Valid Union Type
[img_text/dxmuv.htm Description of "Figure 58-9 XML Direct Mapping to the First Valid Union Type"]
[[#Figure 58-10] illustrates an XML direct mapping to union field in another XML document that conforms to the schema in [[#Example 58-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 58-10 XML Direct Mapping to Another Valid Union Type
[img_text/dxmuvs.htm Description of "Figure 58-10 XML Direct Mapping to Another Valid Union Type"]
[[#Example 58-17] shows how to configure this mapping in Java.
Example 58-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);
Mapping to a Union of Lists with an XML Direct Mapping
Given the XML schema in [[#Example 58-18], [[#Figure 58-11] illustrates an XML direct mapping to a union of lists in a corresponding XML document. [[#Example 58-19] shows how to configure this mapping in Java.
Example 58-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 58-11 XML Direct Mapping to Union of Lists
[img_text/dxuofl.htm Description of "Figure 58-11 XML Direct Mapping to Union of Lists"]
Note that in this example, valid XML documents contain either all xsd:double, all xsd:date, or all xsd:integer values.
Example 58-19 Java for XML Direct Mapping to Union of Lists
XMLDirectMapping mapping = new XMLDirectMapping();
mapping.setAttributeName("vacation");
mapping.setXPath("UnionOfLists/text()");
Mapping to a Union of Unions with an XML Direct Mapping
Given the XML schema in [[#Example 58-20], [[#Figure 58-12] illustrates a Java class that can be mapped to a corresponding XML document. [[#Example 58-21] shows how to configure this mapping in Java.
Example 58-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 58-12 Java Class for XML Direct Mapping to a Union of Unions
[img_text/dxuofu.htm Description of "Figure 58-12 Java Class for XML Direct Mapping to a Union of Unions"]
Example 58-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);
Mapping with a Simple Type Translator
If the type of a node is not defined in your XML schema, you can configure an XML direct mapping to use the xsi:type attribute to provide type information.
Given the XML schema fragment in [[#Example 58-22], [[#Figure 58-13] illustrates a Java class that can be mapped to a corresponding XML document.
Example 58-22 Schema for XML Direct Mapping with Simple Type Translator
...
<xs:element name="area-code" type="anySimpleType"/>
<xs:element name="number" type="anySimpleType"/>
...
Figure 58-13 Java Class for XML Direct Mapping with Simple Type Translator
[img_text/dxmsttc.htm Description of "Figure 58-13 Java Class for XML Direct Mapping with Simple Type Translator"]
[[#Figure 58-14] illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema in [[#Example 58-22].
Figure 58-14 XML Direct Mapping with a Simple Type Translator
[img_text/dxmsttm.htm Description of "Figure 58-14 XML Direct Mapping with a Simple Type Translator"]
[[#Example 58-23] shows how to configure this mapping in Java.
Example 58-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 Mapping
XML composite direct collection mappings map a Java collection of simple object attributes to XML attributes and text nodes. Use multiplicity settings to specify an element as a collection. The XML schema allows you to define minimum and maximum occurrences. You can use a composite direct collection XML mapping in the following scenarios:
- [[#Mapping to Multiple Text Nodes]
- [[#Mapping to Multiple Attributes]
- [[#Mapping to a Single Text Node with an XML Composite Direct Collection Mapping]
- [[#Mapping to a Single Attribute with an XML Composite Direct Collection Mapping]
- [[#Mapping to a List of Unions with an XML Composite Direct Collection Mapping]
- [[#Mapping to a Union of Lists with an XML Composite Direct Collection Mapping]
- [[#Specifying the Content Type of a Collection with an XML Composite Direct Collection Mapping]
See [Configuring%20an%20XML%20Composite%20Direct%20Collection%20Mapping%20(ELUG)|Chapter 61, "Configuring an XML Composite Direct Collection Mapping"] for more information.
Mapping to Multiple Text Nodes
This section describes using a composite direct collection XML mapping when:
- [[#Mapping to a Simple Sequence]
- [[#Mapping to a Sequence in a Subelement]
Mapping to a Simple Sequence
Given the XML schema in [[#Example 58-24], [[#Figure 58-15] illustrates a composite direct collection XML mapping to a simple sequence of text nodes in a corresponding XML document. [[#Example 58-25] shows how to configure this mapping in Java.
Example 58-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 58-15 Composite Direct Collection XML Mapping to a Simple Sequence
[img_text/dcxmss.htm Description of "Figure 58-15 Composite Direct Collection XML Mapping to a Simple Sequence"]
Example 58-25 Java for Composite Direct Collection XML Mapping to a Simple Sequence
XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("task/text()");
Mapping to a Sequence in a Subelement
Given the XML schema in [[#Example 58-26], [[#Figure 58-16] illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. [[#Example 58-27] shows how to configure this mapping in Java.
Example 58-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 58-16 Composite Direct Collection XML Mapping to a Subelement Sequence
[img_text/dcxmsub.htm Description of "Figure 58-16 Composite Direct Collection XML Mapping to a Subelement Sequence"]
Example 58-27 Java for Composite Direct Collection XML Mapping to a Subelement Sequence
XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("tasks/task/text()");
Mapping to Multiple Attributes
Given the XML schema in [[#Example 58-28], [[#Figure 58-17] illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. [[#Example 58-29] shows how to configure this mapping in Java.
Example 58-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 58-17 Composite Direct Collection XML Mapping to Multiple Attributes
[img_text/dcxmma.htm Description of "Figure 58-17 Composite Direct Collection XML Mapping to Multiple Attributes"]
Example 58-29 Java for Composite Direct Collection XML Mapping to Multiple Attributes
XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks/@task");
tasksMapping.setXPath("task/text()");
Mapping to a Single Text Node with an XML Composite Direct Collection Mapping
When you map a collection to a single node, the contents of the node is treated as a space-separated list.
Given the XML schema in [[#Example 58-30], [[#Figure 58-18] illustrates a composite direct collection XML mapping to a single text node in a corresponding XML document. [[#Example 58-31] shows how to configure this mapping in Java.
Example 58-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 58-18 XML Composite Direct Collection Mapping to a Single Text Node
[img_text/dcxmstn.htm Description of "Figure 58-18 XML Composite Direct Collection Mapping to a Single Text Node"]
Example 58-31 Java for XML Composite Direct Collection Mapping to a Single Text Node
XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("tasks/text()");
tasksMapping.setUsesSingleNode(true);
Mapping to a Single Attribute with an XML Composite Direct Collection Mapping
Given the XML schema in [[#Example 58-32], [[#Figure 58-19] illustrates a composite direct collection XML mapping to a single attribute in a corresponding XML document. [[#Example 58-33] shows how to configure this mapping in Java.
Example 58-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 58-19 XML Composite Direct Collection Mapping to a Single Attribute
[img_text/dcxmsat.htm Description of "Figure 58-19 XML Composite Direct Collection Mapping to a Single Attribute"]
Example 58-33 Java for XML Composite Direct Collection Mapping to a Single Attribute
XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();
tasksMapping.setAttributeName("tasks");
tasksMapping.setXPath("@tasks");
tasksMapping.setUsesSingleNode(true);
Mapping to a List of Unions with an XML Composite Direct Collection Mapping
Given the XML schema in [[#Example 58-34], [[#Figure 58-20] illustrates a composite direct collection XML mapping to a list of unions in a corresponding XML document. [[#Example 58-35] shows how to configure this mapping in Java.
Example 58-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 58-20 Composite XML Direct Collection Mapping to List of Unions
[img_text/cdxlofu.htm Description of "Figure 58-20 Composite XML Direct Collection Mapping to List of Unions"]
Example 58-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);
Mapping to a Union of Lists with an XML Composite Direct Collection Mapping
Given the XML schema in [[#Example 58-36], [[#Figure 58-21] illustrates an XML composite direct collection mapping to a union of lists in a corresponding XML document. [[#Example 58-37] shows how to configure this mapping in Java.
Example 58-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 58-21 XML Composite Direct Collection Mapping to a Union of Lists
[img_text/cdxuofl.htm Description of "Figure 58-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 58-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);
Specifying the Content Type of a Collection with an XML Composite Direct Collection Mapping
By default, EclipseLink 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 58-38], [[#Figure 58-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 58-39] shows how to configure this mapping in Java.
Example 58-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 58-22 XML Composite Direct Collection Mapping with Specified Content Type
[img_text/dcxmct.htm Description of "Figure 58-22 XML Composite Direct Collection Mapping with Specified Content Type"]
Example 58-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 Mapping
XML composite object mappings represent a relationship between two classes. In XML, the "owned" class may be nested with the element tag representing the "owning" class. You can use a composite object XML mapping in the following scenarios:
- [[#Mapping into the Parent Record]
- [[#Mapping to an Element]
- [[#Mapping to Different Elements by Element Name]
- [[#Mapping to Different Elements by Element Position]
See [Configuring%20an%20XML%20Composite%20Object%20(ELUG)|Chapter 62, "Configuring an XML Composite Object Mapping"] for more information.
Mapping into the Parent Record
The composite object may be mapped to the same record as the parent.
|
Note: The nodes mapped to by the composite object must be sequential. |
Given the XML schema in [[#Example 58-40], [[#Figure 58-23] illustrates an XML composite object mapping into the parent record in a corresponding XML document. [[#Example 58-41] shows how to configure this mapping in Java.
Example 58-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 58-23 XML Composite Object Mapping into the Parent Record
[img_text/coxmpr.htm Description of "Figure 58-23 XML Composite Object Mapping into the Parent Record"]
Example 58-41 Java for XML Composite Object Mapping into the Parent Record
XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();
addressMapping.setAttributeName("address");
addressMapping.setXPath(".");
addressMapping.setReferenceClass(Address.class);
Mapping to an Element
Given the XML schema in [[#Example 58-42], [[#Figure 58-24] illustrates an XML composite object mapping to an element in a corresponding XML document. [[#Example 58-43] shows how to configure this mapping in Java.
Example 58-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 58-24 XML Composite Object Mapping to an Element
Description of Figure 58-24 follows
[img_text/coxme.htm Description of "Figure 58-24 XML Composite Object Mapping to an Element"]
Example 58-43 Java for XML Composite Object Mapping to an Element
XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();
addressMapping.setAttributeName("address");
addressMapping.setXPath("address");
addressMapping.setReferenceClass(Address.class);
Mapping to Different Elements by Element Name
An object may have multiple composite object mappings to the same reference class. Each composite object mapping must have a unique XPath. This example uses unique XPaths by name.
Given the XML schema in [[#Example 58-44], [[#Figure 58-25] illustrates an XML composite object mapping to different elements by name in a corresponding XML document. [[#Example 58-45] shows how to configure this mapping in Java.
Example 58-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 58-25 XML Composite Object Mapping to Elements by Name
[img_text/coxmden.htm Description of "Figure 58-25 XML Composite Object Mapping to Elements by Name"]
Example 58-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);
Mapping to Different Elements by Element Position
An object may have multiple composite object mappings to the same reference class. Each composite object mapping must have a unique XPath. This example uses unique XPaths by position.
Given the XML schema in [[#Example 58-46], [[#Figure 58-26] illustrates an XML composite object mapping to different elements by position in a corresponding XML document. [[#Example 58-47] shows how to configure this mapping in Java.
Example 58-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 58-26 XML Composite Object Mapping to Elements by Position
[img_text/coxmdep.htm Description of "Figure 58-26 XML Composite Object Mapping to Elements by Position"]
Example 58-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);
XML Composite Collection Mapping
Use XML composite collection mappings to represent one-to-many relationships. Composite collection XML mappings can reference any class that has a EclipseLink 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 58-48], [[#Figure 58-27] illustrates an XML composite collection mapping to different elements by position in a corresponding XML document. [[#Example 58-49] shows how to configure this mapping in Java for a Collection attribute and [[#Example 58-50] shows how to configure this mapping in Java for a Map attribute.
Example 58-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 58-27 XML Composite Collection Mapping
Example 58-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 58-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 63, "Configuring an XML Composite Collection Mappin for more information.
XML Any Object Mapping
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 58-51, #Figure 58-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.
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 58-28 Java Classes for XML Any Object Mapping
[img_text/aoxmc.htm Description of "Figure 58-28 Java Classes for XML Any Object Mapping"]
[[#Figure 58-29], [[#Figure 58-30], and [[#Figure 58-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 58-51].
Figure 58-29 XML Any Object Mapping to Address Type
[img_text/aoxmadd.htm Description of "Figure 58-29 XML Any Object Mapping to Address Type"]
Figure 58-30 XML Any Object Mapping to PhoneNumber Type
[img_text/aoxmpho.htm Description of "Figure 58-30 XML Any Object Mapping to PhoneNumber Type"]
Figure 58-31 XML Any Object Mapping to String Type
#Example 58-52 shows how to configure this mapping in Java.
Example 58-52 Java for XML Any Object Mapping
XMLAnyObjectMapping contactMethodMapping = new XMLAnyObjectMapping();
contactMethodMapping.setAttributeName("contactMethod");
contactMethodMapping.setXPath("contact-method");
For more information about EclipseLink XML mapping support for xs:any and xs:anyType, see [[#xs:any and xs:anyType Support].
See Chapter 64, "Configuring an XML Any Object Mapping" for more information.
XML Any Collection Mapping
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 58-53, #Figure 58-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.
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 58-32 Java Classes for XML Any Collection Mapping
[img_text/aoxmc.htm Description of "Figure 58-32 Java Classes for XML Any Collection Mapping"]
[[#Figure 58-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 58-53.
Figure 58-33 XML Any Collection Mapping
[img_text/acxm.htm Description of "Figure 58-33 XML Any Collection Mapping"]
#Example 58-54 shows how to configure this mapping in Java.
Example 58-54 Java for XML Any Collection Mapping
XMLAnyCollectionMapping contactMethodsMapping = new XMLAnyCollectionMapping();
contactMethodsMapping.setAttributeName("contactMethods");
contactMethodsMapping.setXPath("contact-methods");
For more information about EclipseLink XML mapping support for xs:any and xs:anyType, see #xs:any and xs:anyType Support.
See Chapter 65, "Configuring an XML Any Collection Mapping" for more information.
XML Transformation Mapping
You can use an XML transformation mapping to create a custom mapping where one or more XML nodes can be used to create the object to be stored in a Java class's attribute. To handle the custom requirements at marshall (write) and unmarshall (read) time, a transformation mapping takes instances of org.eclipse.persistence.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 XML Transformation Mappings illustrates, you configure the transformation mapping with an org.eclipse.persistence.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 org.eclipse.persistence.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.
XML Transformation Mappings
See Configuring an XML Transformation Mapping for more information.