org.eclipse.persistence.oxm.mappings

Class XMLCollectionReferenceMapping

java.lang.Object

org.eclipse.persistence.mappings.DatabaseMapping

org.eclipse.persistence.mappings.AggregateMapping

org.eclipse.persistence.oxm.mappings.XMLObjectReferenceMapping

org.eclipse.persistence.oxm.mappings.XMLCollectionReferenceMapping

All Implemented Interfaces:

Serializable, Cloneable, ContainerMapping, XMLMapping

public class XMLCollectionReferenceMapping
extends XMLObjectReferenceMapping
implements ContainerMapping

TopLink OXM version of a 1-M mapping. A list of source-target key field associations is used to link the source xpaths to their related target xpaths, and hence their primary key (unique identifier) values used when (un)marshalling. It is important to note that each target xpath is assumed to be set as a primary key field on the target (reference) class descriptor - this is necessary in order to locate the correct target object instance in the session cache when resolving mapping references. The usesSingleNode flag should be set to true if the keys are to be written out in space-separated lists.

See Also:

XMLObjectReferenceMapping, ContainerMapping, Serialized Form

Nested Class Summary

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

DatabaseMapping.WriteType

Constructor Summary

Constructors

Constructor and Description
XMLCollectionReferenceMapping() PUBLIC: The default constructor initializes the sourceToTargetKeyFieldAssociations and sourceToTargetKeys data structures.

Method Summary

Methods

Modifier and Type	Method and Description
Object	buildFieldValue(Object targetObject, XMLField xmlFld, org.eclipse.persistence.internal.sessions.AbstractSession session) INTERNAL: Retrieve the target object's primary key value that is mapped to a given source xpath (in the source-target key field association list).
void	buildReference(UnmarshalRecord record, XMLField xmlField, Object object, org.eclipse.persistence.internal.sessions.AbstractSession session) INTERNAL: Create (if necessary) and populate a reference object that will be used during the mapping reference resolution phase after unmarshalling is complete.
org.eclipse.persistence.internal.queries.ContainerPolicy	getContainerPolicy() INTERNAL: Return the mapping's containerPolicy.
org.eclipse.persistence.internal.helper.DatabaseField	getField() INTERNAL: Return the field associated with this mapping if there is exactly one.
boolean	getReuseContainer() Return true if the original container on the object should be used if present.
String	getXPath() Get the XPath String
void	initialize(org.eclipse.persistence.internal.sessions.AbstractSession session) INTERNAL: The mapping is initialized with the given session.
boolean	isCollectionMapping() INTERNAL: Related mapping should implement this method to return true.
Object	readFromRowIntoObject(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, Object targetObject, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.sessions.AbstractSession executionSession) INTERNAL: Extract the primary key values from the row, then create an org.eclipse.persistence.internal.oxm.Reference instance and stored it on the session's org.eclipse.persistence.internal.oxm.ReferenceResolver.
void	setContainerPolicy(org.eclipse.persistence.internal.queries.ContainerPolicy containerPolicy) ADVANCED: Set the mapping's containerPolicy.
void	setField(org.eclipse.persistence.internal.helper.DatabaseField field)
void	setReuseContainer(boolean reuseContainer) Specify whether the original container on the object should be used if present.
void	setUsesSingleNode(boolean useSingleNode)
void	setXPath(String xpathString) Set the Mapping field name attribute to the given XPath String
void	useCollectionClass(Class concreteContainerClass) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useCollectionClassName(String concreteContainerClassName)
void	useMapClass(Class concreteContainerClass, String methodName) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
boolean	usesSingleNode() INTERNAL: For the purpose of XMLCollectionReferenceMappings, 'usesSingleNode' refers to the fact that the source key xpath fields should all be written as space-separated lists.
void	writeFromObjectIntoRow(Object object, org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.sessions.AbstractSession session, DatabaseMapping.WriteType writeType) INTERNAL: Write the attribute value from the object to the row.
void	writeSingleValue(Object value, 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.oxm.mappings.XMLObjectReferenceMapping

addSourceToTargetKeyFieldAssociation, cascadePerformRemoveIfRequired, cascadeRegisterNewIfRequired, getFields, getInverseReferenceMapping, getSourceToTargetKeyFieldAssociations, isWriteOnly, isXMLMapping, preInitialize, setAttributeValueInObject, setIsWriteOnly, setSourceToTargetKeyFieldAssociations

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

buildBackupClone, buildClone, buildCloneFromRow, buildCopy, buildExpression, compareForChange, compareObjects, convertClassNamesToClasses, fixObjectReferences, getReferenceClass, getReferenceClassName, getReferenceDescriptor, isAggregateMapping, iterate, mergeChangesIntoObject, mergeIntoObject, postDelete, postDeleteAttributeValue, postInsert, postInsertAttributeValue, postUpdate, postUpdateAttributeValue, preDelete, preDeleteAttributeValue, preInsert, preInsertAttributeValue, preUpdate, preUpdateAttributeValue, remoteInitialization, setReferenceClass, setReferenceClassName, updateChangeRecord, verifyDelete

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

buildBackupCloneForPartObject, buildChangeRecord, buildCloneForPartObject, buildObjectJoinExpression, buildObjectJoinExpression, buildShallowOriginalFromRow, calculateDeferredChanges, cascadeDiscoverAndPersistUnregisteredNewObjects, cascadeMerge, cascadePerformRemovePrivateOwnedObjectFromChangeSetIfRequired, clone, createUnitOfWorkValueHolder, derivesId, earlyPreDelete, fixRealObjectReferences, getAttributeAccessor, getAttributeClassification, getAttributeName, getAttributeValueFromObject, getDerivedIdMapping, getDescriptor, getFieldClassification, getGetMethodName, getMapsIdValue, getObjectCorrespondingTo, getProperties, getProperty, getRealAttributeValueFromAttribute, getRealAttributeValueFromObject, getRealCollectionAttributeValueFromObject, getRelationshipPartner, getSelectFields, getSelectTables, getSetMethodName, getValueFromRemoteValueHolder, getWeight, hasConstraintDependency, hasDependency, hasInverseConstraintDependency, hasMapsIdValue, instantiateAttribute, isAbstractCompositeCollectionMapping, isAbstractCompositeDirectCollectionMapping, isAbstractCompositeObjectMapping, isAbstractDirectMapping, isAggregateCollectionMapping, isAggregateObjectMapping, isCandidateForPrivateOwnedRemoval, isCascadedLockingSupported, isChangeTrackingSupported, isCloningRequired, isDatabaseMapping, isDirectCollectionMapping, isDirectMapMapping, isDirectToFieldMapping, isDirectToXMLTypeMapping, isEISMapping, isForeignReferenceMapping, isJoiningSupported, isJPAId, isLazy, isLockableMapping, isManyToManyMapping, isManyToOneMapping, isMapKeyMapping, isNestedTableMapping, isObjectReferenceMapping, isOneToManyMapping, isOneToOneMapping, isOptional, isOwned, isPrimaryKeyMapping, isPrivateOwned, isReadOnly, isReferenceMapping, isRelationalMapping, isStructureMapping, isTransformationMapping, isUnidirectionalOneToManyMapping, isUsingMethodAccess, isVariableOneToOneMapping, iterateOnRealAttributeValue, performDataModificationEvent, postCalculateChanges, postCalculateChangesOnDeleted, postInitialize, prepareCascadeLockingPolicy, readFromResultSetIntoObject, readOnly, readWrite, recordPrivateOwnedRemovals, rehashFieldDependancies, replaceValueHoldersIn, setAttributeAccessor, setAttributeName, setChangeListener, setDerivedIdMapping, setDerivesId, setDescriptor, setGetMethodName, setIsJPAId, setIsLazy, setIsMapKeyMapping, setIsOptional, setIsPrimaryKeyMapping, setIsReadOnly, setMapsIdValue, setProperties, setProperty, setRealAttributeValueInObject, setSetMethodName, setWeight, simpleAddToCollectionChangeRecord, simpleRemoveFromCollectionChangeRecord, toString, updateCollectionChangeRecord, validateAfterInitialization, validateBeforeInitialization, valueFromObject, valueFromResultSet, valueFromRow, valueFromRow, writeFromAttributeIntoRow, writeFromObjectIntoRowForShallowInsert, writeFromObjectIntoRowForShallowInsertWithChangeRecord, writeFromObjectIntoRowForUpdate, writeFromObjectIntoRowForWhereClause, writeFromObjectIntoRowWithChangeRecord, writeInsertFieldsIntoRow, writeUpdateFieldsIntoRow

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLCollectionReferenceMapping

public XMLCollectionReferenceMapping()

PUBLIC: The default constructor initializes the sourceToTargetKeyFieldAssociations and sourceToTargetKeys data structures.

Method Detail

getField

public org.eclipse.persistence.internal.helper.DatabaseField getField()

Description copied from class: DatabaseMapping

INTERNAL: Return the field associated with this mapping if there is exactly one. This is required for object relational mapping to print them, but because they are defined in in an Enterprise context they cannot be cast to. Mappings that have a field include direct mappings and object relational mappings.

Overrides:

getField in class DatabaseMapping

setField

public void setField(org.eclipse.persistence.internal.helper.DatabaseField field)

Overrides:

setField in class XMLObjectReferenceMapping

getXPath

public String getXPath()

Get the XPath String

Returns:

String the XPath String associated with this Mapping

setXPath

public void setXPath(String xpathString)

Set the Mapping field name attribute to the given XPath String

Parameters:

xpathString - String

buildFieldValue

public Object buildFieldValue(Object targetObject,
                     XMLField xmlFld,
                     org.eclipse.persistence.internal.sessions.AbstractSession session)

INTERNAL: Retrieve the target object's primary key value that is mapped to a given source xpath (in the source-target key field association list).

Overrides:

buildFieldValue in class XMLObjectReferenceMapping

Parameters:

targetObject - - the reference class instance that holds the required pk value

xmlFld -

session -

Returns:

null if the target object is null, the reference class is null, or a primary key field name does not exist on the reference descriptor that matches the target field name - otherwise, return the associated primary key value

buildReference

public void buildReference(UnmarshalRecord record,
                  XMLField xmlField,
                  Object object,
                  org.eclipse.persistence.internal.sessions.AbstractSession session)

INTERNAL: Create (if necessary) and populate a reference object that will be used during the mapping reference resolution phase after unmarshalling is complete.

Overrides:

buildReference in class XMLObjectReferenceMapping

Parameters:

record -

xmlField -

object -

session -

getContainerPolicy

public org.eclipse.persistence.internal.queries.ContainerPolicy getContainerPolicy()

INTERNAL: Return the mapping's containerPolicy.

Specified by:

getContainerPolicy in interface ContainerMapping

Overrides:

getContainerPolicy in class DatabaseMapping

initialize

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

INTERNAL: The mapping is initialized with the given session. This mapping is fully initialized after this.

Overrides:

initialize in class XMLObjectReferenceMapping

Throws:

DescriptorException

See Also:

ReferenceResolver, NamespaceResolver

readFromRowIntoObject

public Object readFromRowIntoObject(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
                           org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                           Object targetObject,
                           ObjectBuildingQuery sourceQuery,
                           org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
                             throws DatabaseException

INTERNAL: Extract the primary key values from the row, then create an org.eclipse.persistence.internal.oxm.Reference instance and stored it on the session's org.eclipse.persistence.internal.oxm.ReferenceResolver.

Overrides:

readFromRowIntoObject in class XMLObjectReferenceMapping

Throws:

DatabaseException

setContainerPolicy

public void setContainerPolicy(org.eclipse.persistence.internal.queries.ContainerPolicy containerPolicy)

ADVANCED: Set the mapping's containerPolicy.

Specified by:

setContainerPolicy in interface ContainerMapping

useCollectionClass

public void useCollectionClass(Class concreteContainerClass)

PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.

jdk1.2.x: The container class must implement (directly or indirectly) the Collection interface.

jdk1.1.x: The container class must be a subclass of Vector.

Specified by:

useCollectionClass in interface ContainerMapping

useCollectionClassName

public void useCollectionClassName(String concreteContainerClassName)

useMapClass

public void useMapClass(Class concreteContainerClass,
               String methodName)

PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects. The key used to index the value in the Map is the value returned by a call to the specified zero-argument method. The method must be implemented by the class (or a superclass) of the value to be inserted into the Map.

jdk1.2.x: The container class must implement (directly or indirectly) the Map interface.

jdk1.1.x: The container class must be a subclass of Hashtable.

The referenceClass must be set before calling this method.

Specified by:

useMapClass in interface ContainerMapping

usesSingleNode

public boolean usesSingleNode()

INTERNAL: For the purpose of XMLCollectionReferenceMappings, 'usesSingleNode' refers to the fact that the source key xpath fields should all be written as space-separated lists. Would be used for mapping to an IDREFS field in a schema

setUsesSingleNode

public void setUsesSingleNode(boolean useSingleNode)

writeFromObjectIntoRow

public void writeFromObjectIntoRow(Object object,
                          org.eclipse.persistence.internal.sessions.AbstractRecord row,
                          org.eclipse.persistence.internal.sessions.AbstractSession session,
                          DatabaseMapping.WriteType writeType)

INTERNAL: Write the attribute value from the object to the row.

Overrides:

writeFromObjectIntoRow in class XMLObjectReferenceMapping

writeSingleValue

public void writeSingleValue(Object value,
                    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 XMLMapping

Overrides:

writeSingleValue in class XMLObjectReferenceMapping

Parameters:

value - - The value to be marshalled

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

isCollectionMapping

public boolean isCollectionMapping()

Description copied from class: DatabaseMapping

INTERNAL: Related mapping should implement this method to return true.

Overrides:

isCollectionMapping in class DatabaseMapping

getReuseContainer

public boolean getReuseContainer()

Return true if the original container on the object should be used if present. If it is not present then the container policy will be used to create the container.

setReuseContainer

public void setReuseContainer(boolean reuseContainer)

Specify whether the original container on the object should be used if present. If it is not present then the container policy will be used to create the container.