Transformation XML mappings are used 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 marshal (write) and unmarshall (read) time, a transformation mapping takes instances of org.eclipse.persistence.mappings.transformers (such as AttributeTransformer and FieldTransformer), providing a non-intrusive solution that avoids the need for domain objects to implement any 'special' interfaces.
Setting the XPath: TopLink XML mappings make use of XPath statements to find the relevant
data in an XML document. The XPath statement is relative to the context node specified in the descriptor.
The XPath may contain node type, path, and positional information. The XPath is specified on the
field transformer that is set on the mapping. The XPath is set as the first parameter of the
addFieldTransformer method.
The following XPath statements may be used to specify the location of XML data relating to an object's name attribute:
| XPath | Description |
|---|---|
| @name | The "@" character indicates that the node is an attribute. |
| text() | "text()" indicates that the node is a text node. In this case the name value in the text node belongs to the context node. |
| full-name/text() | The name information is stored in the text node of the full-name element. |
| personal-info/name/text() | The XPath statement may be used to specify any valid path. |
| name[2]/text() | The XPath statement may contain positional information. In this case the name information is stored in the text node of the second occurrence of the name element. |
Mapping a transformation: A transformer can be configured to perform both the XML instance-to-Java attribute transformation at unmarshall time (via attribute transformer) and the Java attribute-to-XML instance transformation at marshal time (via field transformer).
XML Schema
<?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="name" type="xsd:string"/>
<xsd:element name="normal-hours" type="normal-hours-type"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="normal-hours-type">
<xsd:sequence>
<xsd:element name="start-time" type="xsd:string"/>
<xsd:element name="end-time" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
Code Sample
XMLTransformationMapping mapping = new XMLTransformationMapping();
mapping.setAttributeName("normalHours");
mapping.setAttributeTransformerClassName("org.eclipse.persistence.testing.oxm.mappings.transformation.NormalHoursAttributeTransformer");
mapping.addFieldTransformer("normal-hours/start-time/text()", new StartTimeTransformer());
mapping.addFieldTransformer("normal-hours/end-time/text()", new EndTimeTransformer()");
More Information: For more information about using the XML Transformation Mapping, see the "Understanding XML Mappings" chapter of the Oracle TopLink Developer's Guide.
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| public void | addFieldTransformation(String fieldName, String methodName)
Overrides org. Implements org. |
| public void | addFieldTransformer(String fieldName, FieldTransformer transformer)
Overrides org. |
| public void | addFieldTransformerClassName(String fieldName, String className)
Implements org. |
| public boolean | |
| public void | preInitialize(AbstractSession session)
Overrides org. |
| public Object | readFromRowIntoObject(XMLRecord row, Object object, AbstractSession executionSession, boolean isTargetProtected)
Implements org. |
| public void | |
| public void | writeFromAttributeIntoRow(UnmarshalRecord<ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, FIELD extends CoreField, ID_RESOLVER extends IDResolver, OBJECT_BUILDER extends ObjectBuilder<ABSTRACT_RECORD extends CoreAbstractRecord, ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, MARSHALLER extends Marshaller<CHARACTER_ESCAPE_HANDLER extends CharacterEscapeHandler, CONTEXT extends Context<ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, DESCRIPTOR extends Descriptor<?, ?, ?, ?, ?, NAMESPACE_RESOLVER, ?, ?, ?, ?>, FIELD extends Field, NAMESPACE_RESOLVER extends NamespaceResolver, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION extends CoreSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager>, SESSION_EVENT_LISTENER extends CoreSessionEventListener>, MARSHALLER_LISTENER extends Marshaller.
Implements org. |
| public void | writeSingleValue(Object
- The value to be marshalled value, Object parent, XMLRecord - The Record the value is being marshalled too. row, AbstractSession session)Implements org. |
| XMLTransformationMapping | back to summary |
|---|---|
| public XMLTransformationMapping() | |
| addFieldTransformation | back to summary |
|---|---|
| public void addFieldTransformation(String fieldName, String methodName) Overrides org. Implements org. Doc from org. Add the name of field and the name of the method
that returns the value to be placed in said field
when the object is written to the database.
The method may take zero arguments, or it may
take a single argument of type
| |
| addFieldTransformer | back to summary |
|---|---|
| public void addFieldTransformer(String fieldName, FieldTransformer transformer) Overrides org. Doc from org. PUBLIC: Add the name of field and the transformer that returns the value to be placed in the field when the object is written to the database.
| |
| addFieldTransformerClassName | back to summary |
|---|---|
| public void addFieldTransformerClassName(String fieldName, String className) Implements org. Doc from org. INTERNAL: Add the name of a field and the name of a class which implements the FieldTransformer interface. When the object is written, the transform method will be called on the FieldTransformer to acquire the value to put in the field.
| |
| isXMLMapping | back to summary |
|---|---|
| public boolean isXMLMapping() Overrides org. INTERNAL:
| |
| preInitialize | back to summary |
|---|---|
| public void preInitialize(AbstractSession session) throws DescriptorException Overrides org. Doc from org. INTERNAL: Allow for initialization of properties and validation.
| |
| readFromRowIntoObject | back to summary |
|---|---|
| public Object readFromRowIntoObject(XMLRecord row, Object object, AbstractSession executionSession, boolean isTargetProtected) throws DatabaseException Implements org. INTERNAL: Extract value from the row and set the attribute to the value in the object.
| |
| setIsWriteOnly | back to summary |
|---|---|
| public void setIsWriteOnly(boolean b) Implements org.
| |
| writeFromAttributeIntoRow | back to summary |
|---|---|
| public void writeFromAttributeIntoRow(UnmarshalRecord<ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, FIELD extends CoreField, ID_RESOLVER extends IDResolver, OBJECT_BUILDER extends ObjectBuilder<ABSTRACT_RECORD extends CoreAbstractRecord, ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, MARSHALLER extends Marshaller<CHARACTER_ESCAPE_HANDLER extends CharacterEscapeHandler, CONTEXT extends Context<ABSTRACT_SESSION extends CoreAbstractSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform<CONVERSION_MANAGER extends CoreConversionManager>, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager<SESSION_EVENT_LISTENER extends CoreSessionEventListener>>, DESCRIPTOR extends Descriptor<?, ?, ?, ?, ?, NAMESPACE_RESOLVER, ?, ?, ?, ?>, FIELD extends Field, NAMESPACE_RESOLVER extends NamespaceResolver, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION extends CoreSession<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, PLATFORM extends CorePlatform, PROJECT extends CoreProject<DESCRIPTOR extends CoreDescriptor<ATTRIBUTE_GROUP extends CoreAttributeGroup, DESCRIPTOR_EVENT_MANAGER extends CoreDescriptorEventManager, FIELD extends CoreField, INHERITANCE_POLICY extends CoreInheritancePolicy, INSTANTIATION_POLICY extends CoreInstantiationPolicy, LIST extends List<E>, OBJECT_BUILDER extends CoreObjectBuilder>, LOGIN extends CoreLogin<PLATFORM extends CorePlatform>, SESSION extends CoreSession>, SESSION_EVENT_MANAGER extends CoreSessionEventManager>, SESSION_EVENT_LISTENER extends CoreSessionEventListener>, MARSHALLER_LISTENER extends Marshaller. Implements org. INTERNAL: Put value into a record keyed on field.
| |
| writeSingleValue | back to summary |
|---|---|
| public void writeSingleValue(Object value, Object parent, XMLRecord row, AbstractSession session) Implements org. Doc from org. INTERNAL: A method that marshals a single value to the provided Record based on this mapping's XPath. Used for Sequenced marshalling. | |