org.eclipse.persistence.oxm.mappings

Class XMLTransformationMapping

java.lang.Object

org.eclipse.persistence.core.mappings.CoreMapping<AttributeAccessor,org.eclipse.persistence.internal.sessions.AbstractSession,org.eclipse.persistence.internal.queries.ContainerPolicy,ClassDescriptor,org.eclipse.persistence.internal.helper.DatabaseField>

org.eclipse.persistence.mappings.DatabaseMapping

org.eclipse.persistence.mappings.foundation.AbstractTransformationMapping

org.eclipse.persistence.oxm.mappings.XMLTransformationMapping

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, org.eclipse.persistence.internal.oxm.mappings.Mapping<org.eclipse.persistence.internal.sessions.AbstractSession,AttributeAccessor,org.eclipse.persistence.internal.queries.ContainerPolicy,ClassDescriptor,org.eclipse.persistence.internal.helper.DatabaseField,XMLRecord>, org.eclipse.persistence.internal.oxm.mappings.TransformationMapping<org.eclipse.persistence.internal.sessions.AbstractSession,AttributeAccessor,org.eclipse.persistence.internal.queries.ContainerPolicy,ClassDescriptor,org.eclipse.persistence.internal.helper.DatabaseField,XMLRecord>, XMLMapping

public class XMLTransformationMapping
extends AbstractTransformationMapping
implements org.eclipse.persistence.internal.oxm.mappings.TransformationMapping<org.eclipse.persistence.internal.sessions.AbstractSession,AttributeAccessor,org.eclipse.persistence.internal.queries.ContainerPolicy,ClassDescriptor,org.eclipse.persistence.internal.helper.DatabaseField,XMLRecord>, XMLMapping

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.

See Also:

Serialized Form

Since:

Oracle TopLink 10g Release 2 (10.1.3)

Nested Class Summary

Nested classes/interfaces inherited from class org.eclipse.persistence.mappings.DatabaseMapping

DatabaseMapping.WriteType

Field Summary

Fields inherited from class org.eclipse.persistence.mappings.foundation.AbstractTransformationMapping

attributeTransformer, attributeTransformerClassName, fieldToTransformers, fieldTransformations, indirectionPolicy, isMutable

Fields inherited from class org.eclipse.persistence.mappings.DatabaseMapping

attributeAccessor, attributeName, derivedIdMapping, derivesId, descriptor, fields, isCacheable, isInSopObject, isJPAId, isLazy, isMapKeyMapping, isOptional, isPrimaryKeyMapping, isReadOnly, isRemotelyInitialized, mapsIdValue, NO_FIELDS, NO_WEIGHT, properties, unconvertedProperties, weight, WEIGHT_AGGREGATE, WEIGHT_DIRECT, WEIGHT_TO_ONE, WEIGHT_TRANSFORM

Constructor Summary

Constructors

Constructor and Description
XMLTransformationMapping()

Method Summary

Methods

Modifier and Type	Method and Description
void	addFieldTransformation(java.lang.String fieldName, java.lang.String methodName) PUBLIC: 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.
void	addFieldTransformer(java.lang.String fieldName, FieldTransformer transformer) 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.
void	addFieldTransformerClassName(java.lang.String fieldName, java.lang.String className) INTERNAL: Add the name of a field and the name of a class which implements the FieldTransformer interface.
boolean	isXMLMapping() INTERNAL:
void	preInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session) INTERNAL: Allow for initialization of properties and validation.
void	setIsWriteOnly(boolean b)
void	writeSingleValue(java.lang.Object value, java.lang.Object parent, XMLRecord row, org.eclipse.persistence.internal.sessions.AbstractSession session) INTERNAL: A method that marshals a single value to the provided Record based on this mapping's XPath.

Methods inherited from class org.eclipse.persistence.mappings.foundation.AbstractTransformationMapping

addFieldTransformation, addFieldTransformer, addFieldTransformerClassName, areObjectsToBeProcessedInstantiated, buildBackupClone, buildBackupCloneForPartObject, buildChangeRecord, buildClone, buildCloneForPartObject, buildCloneFromRow, buildCopy, buildPhantomRowFrom, buildShallowOriginalFromRow, cascadePerformRemoveIfRequired, cascadeRegisterNewIfRequired, clone, collectFields, compareForChange, compareObjects, convertClassNamesToClasses, createCloneValueHolder, dontUseIndirection, fixObjectReferences, getAttributeMethodName, getAttributeTransformer, getAttributeTransformerClass, getAttributeTransformerClassName, getAttributeValueFromObject, getFieldNameToMethodNameAssociations, getFieldNameToMethodNames, getFieldToTransformers, getFieldTransformations, getIndirectionPolicy, getRealAttributeValueFromAttribute, getValueFromRemoteValueHolder, initialize, initializeAttributeTransformer, initializeFieldToTransformers, instantiateAttribute, internalBuildChangeRecord, invokeAttributeTransformer, invokeFieldTransformer, invokeFieldTransformer, isAttributeValueFromObjectInstantiated, isChangeTrackingSupported, isMutable, isReadOnly, isTransformationMapping, isWriteOnly, iterate, iterateOnRealAttributeValue, mergeChangesIntoObject, mergeIntoObject, readFromReturnRowIntoObject, readFromRowIntoObject, remoteInitialization, setAttributeTransformation, setAttributeTransformer, setAttributeTransformerClass, setAttributeTransformerClassName, setAttributeValueInObject, setFieldNameToMethodNameAssociations, setFieldToTransformers, setFieldTransformations, setIndirectionPolicy, setIsMutable, setRealAttributeValueInObject, setUsesIndirection, updateChangeRecord, useBasicIndirection, useContainerIndirection, useIndirection, usesIndirection, validateBeforeInitialization, valueFromObject, writeFromObjectIntoRow, writeFromObjectIntoRowForUpdate, writeFromObjectIntoRowWithChangeRecord, writeInsertFieldsIntoRow

Methods inherited from class org.eclipse.persistence.mappings.DatabaseMapping

addUnconvertedProperty, buildContainerClone, buildExpression, buildObjectJoinExpression, buildObjectJoinExpression, calculateDeferredChanges, cascadeDiscoverAndPersistUnregisteredNewObjects, cascadePerformRemovePrivateOwnedObjectFromChangeSetIfRequired, cloneFields, collectQueryParameters, convertConverterClassNamesToClasses, derivesId, earlyPreDelete, extractNestedExpressions, fixRealObjectReferences, getAttributeAccessor, getAttributeClassification, getAttributeName, getContainerPolicy, getDerivedIdMapping, getDescriptor, getField, getFieldClassification, getFields, getGetMethodName, getMapsIdValue, getObjectCorrespondingTo, getOrderByNormalizedExpressions, getProperties, getProperty, getRealAttributeValueFromObject, getRealCollectionAttributeValueFromObject, getReferenceDescriptor, getRelationshipPartner, getSelectFields, getSelectTables, getSetMethodName, getUnconvertedProperties, getWeight, hasConstraintDependency, hasDependency, hasInverseConstraintDependency, hasMapsIdValue, hasNestedIdentityReference, hasRootExpressionThatShouldUseOuterJoin, hasUnconvertedProperties, isAbstractColumnMapping, isAbstractCompositeCollectionMapping, isAbstractCompositeDirectCollectionMapping, isAbstractCompositeObjectMapping, isAbstractDirectMapping, isAggregateCollectionMapping, isAggregateMapping, isAggregateObjectMapping, isCacheable, isCandidateForPrivateOwnedRemoval, isCascadedLockingSupported, isCloningRequired, isCollectionMapping, isDatabaseMapping, isDirectCollectionMapping, isDirectMapMapping, isDirectToFieldMapping, isDirectToXMLTypeMapping, isEISMapping, isElementCollectionMapping, isForeignReferenceMapping, isInAndOutSopObject, isInOnlySopObject, isInSopObject, isJoiningSupported, isJPAId, isLazy, isLockableMapping, isManyToManyMapping, isManyToOneMapping, isMapKeyMapping, isMultitenantPrimaryKeyMapping, isNestedTableMapping, isObjectReferenceMapping, isOneToManyMapping, isOneToOneMapping, isOptional, isOutOnlySopObject, isOutSopObject, isOwned, isPrimaryKeyMapping, isPrivateOwned, isReferenceMapping, isRelationalMapping, isRemotelyInitialized, isStructureMapping, isUnidirectionalOneToManyMapping, isUsingMethodAccess, isVariableOneToOneMapping, load, loadAll, performDataModificationEvent, postCalculateChanges, postCalculateChangesOnDeleted, postDelete, postInitialize, postInsert, postUpdate, preDelete, preInsert, prepareCascadeLockingPolicy, preUpdate, readFromResultSetIntoObject, readOnly, readWrite, recordPrivateOwnedRemovals, rehashFieldDependancies, remotelyInitialized, replaceValueHoldersIn, setAttributeAccessor, setAttributeName, setChangeListener, setDerivedIdMapping, setDerivesId, setDescriptor, setFields, setGetMethodName, setIsCacheable, setIsInAndOutSopObject, setIsInSopObject, setIsJPAId, setIsLazy, setIsMapKeyMapping, setIsOptional, setIsOutSopObject, setIsPrimaryKeyMapping, setIsReadOnly, setMapsIdValue, setProperties, setProperty, setSetMethodName, setWeight, simpleAddToCollectionChangeRecord, simpleRemoveFromCollectionChangeRecord, toString, updateCollectionChangeRecord, validateAfterInitialization, valueFromResultSet, valueFromRow, valueFromRow, verifyDelete, writeFromAttributeIntoRow, writeFromObjectIntoRowForShallowInsert, writeFromObjectIntoRowForShallowInsertWithChangeRecord, writeFromObjectIntoRowForUpdateAfterShallowInsert, writeFromObjectIntoRowForUpdateBeforeShallowDelete, writeFromObjectIntoRowForWhereClause, writeUpdateFieldsIntoRow

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.eclipse.persistence.internal.oxm.mappings.TransformationMapping

getFieldToTransformers, setAttributeTransformation, setAttributeTransformerClassName, setIsOptional

Methods inherited from interface org.eclipse.persistence.oxm.mappings.XMLMapping

convertClassNamesToClasses, isWriteOnly

Methods inherited from interface org.eclipse.persistence.internal.oxm.mappings.Mapping

getAttributeAccessor, getAttributeClassification, getAttributeName, getAttributeValueFromObject, getContainerPolicy, getDescriptor, getField, getReferenceDescriptor, isAbstractCompositeCollectionMapping, isAbstractCompositeDirectCollectionMapping, isAbstractCompositeObjectMapping, isAbstractDirectMapping, isCollectionMapping, isReadOnly, isReferenceMapping, isTransformationMapping, setAttributeAccessor, setAttributeName, setAttributeValueInObject, setGetMethodName, setIsReadOnly, setProperties, setSetMethodName

Constructor Detail

XMLTransformationMapping

public XMLTransformationMapping()

Method Detail

isXMLMapping

public boolean isXMLMapping()

INTERNAL:

Overrides:

isXMLMapping in class DatabaseMapping

addFieldTransformer

public void addFieldTransformer(java.lang.String fieldName,
                       FieldTransformer transformer)

Description copied from class: AbstractTransformationMapping

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.

Overrides:

addFieldTransformer in class AbstractTransformationMapping

addFieldTransformerClassName

public void addFieldTransformerClassName(java.lang.String fieldName,
                                java.lang.String className)

Description copied from class: AbstractTransformationMapping

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.

Specified by:

addFieldTransformerClassName in interface org.eclipse.persistence.internal.oxm.mappings.TransformationMapping<org.eclipse.persistence.internal.sessions.AbstractSession,AttributeAccessor,org.eclipse.persistence.internal.queries.ContainerPolicy,ClassDescriptor,org.eclipse.persistence.internal.helper.DatabaseField,XMLRecord>

Overrides:

addFieldTransformerClassName in class AbstractTransformationMapping

addFieldTransformation

public void addFieldTransformation(java.lang.String fieldName,
                          java.lang.String methodName)

Description copied from class: AbstractTransformationMapping

PUBLIC: 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 org.eclipse.persistence.sessions.Session.

Specified by:

addFieldTransformation in interface org.eclipse.persistence.internal.oxm.mappings.TransformationMapping<org.eclipse.persistence.internal.sessions.AbstractSession,AttributeAccessor,org.eclipse.persistence.internal.queries.ContainerPolicy,ClassDescriptor,org.eclipse.persistence.internal.helper.DatabaseField,XMLRecord>

Overrides:

addFieldTransformation in class AbstractTransformationMapping

writeSingleValue

public void writeSingleValue(java.lang.Object value,
                    java.lang.Object parent,
                    XMLRecord row,
                    org.eclipse.persistence.internal.sessions.AbstractSession session)

Description copied from interface: XMLMapping

INTERNAL: A method that marshals a single value to the provided Record based on this mapping's XPath. Used for Sequenced marshalling.

Specified by:

writeSingleValue in interface org.eclipse.persistence.internal.oxm.mappings.Mapping<org.eclipse.persistence.internal.sessions.AbstractSession,AttributeAccessor,org.eclipse.persistence.internal.queries.ContainerPolicy,ClassDescriptor,org.eclipse.persistence.internal.helper.DatabaseField,XMLRecord>

Specified by:

writeSingleValue in interface XMLMapping

Parameters:

value - - The value to be marshalled

row - - The Record the value is being marshalled too.

setIsWriteOnly

public void setIsWriteOnly(boolean b)

Specified by:

setIsWriteOnly in interface XMLMapping

preInitialize

public void preInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
                   throws DescriptorException

Description copied from class: AbstractTransformationMapping

INTERNAL: Allow for initialization of properties and validation.

Overrides:

preInitialize in class AbstractTransformationMapping

Throws:

DescriptorException