org.eclipse.persistence.oxm.mappings

Class XMLCollectionReferenceMapping

java.lang.Object

org.eclipse.persistence.core.mappings.CoreMapping<AttributeAccessor,AbstractSession,ContainerPolicy,ClassDescriptor,DatabaseField>

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:

java.io.Serializable, java.lang.Cloneable, CollectionReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>, Mapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,XMLRecord>, ObjectReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>, XMLContainerMapping, ContainerMapping, XMLMapping

public class XMLCollectionReferenceMapping
extends XMLObjectReferenceMapping
implements CollectionReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>, 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

Field Summary

Fields inherited from interface org.eclipse.persistence.internal.oxm.mappings.XMLContainerMapping

EMPTY_CONTAINER_DEFAULT

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
java.lang.Object	buildFieldValue(java.lang.Object targetObject, XMLField xmlFld, 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(java.lang.Object srcObject, XMLField xmlField, java.lang.Object object, AbstractSession session, java.lang.Object container, ReferenceResolver resolver) INTERNAL: Create (if necessary) and populate a reference object that will be used during the mapping reference resolution phase after unmarshalling is complete.
void	buildReference(UnmarshalRecord record, XMLField xmlField, java.lang.Object object, AbstractSession session, java.lang.Object container) INTERNAL: Create (if necessary) and populate a reference object that will be used during the mapping reference resolution phase after unmarshalling is complete.
ContainerPolicy	getContainerPolicy() INTERNAL: Return the mapping's containerPolicy.
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.
AbstractNullPolicy	getWrapperNullPolicy() Get the Wrapper NullPolicy from the Mapping.
java.lang.String	getXPath() Get the XPath String
void	initialize(AbstractSession session) INTERNAL: The mapping is initialized with the given session.
boolean	isCollectionMapping() INTERNAL: Related mapping should implement this method to return true.
boolean	isDefaultEmptyContainer() INTERNAL Return true if an empty container should be set on the object if there is no presence of the collection in the XML document.
java.lang.Object	readFromRowIntoObject(AbstractRecord databaseRow, JoinedAttributeManager joinManager, java.lang.Object targetObject, CacheKey parentCacheKey, ObjectBuildingQuery sourceQuery, AbstractSession executionSession, boolean isTargetProtected) 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.
java.lang.Object	readFromRowIntoObject(AbstractRecord databaseRow, JoinedAttributeManager joinManager, java.lang.Object targetObject, CacheKey parentCacheKey, ObjectBuildingQuery sourceQuery, AbstractSession executionSession, boolean isTargetProtected, java.lang.Object container) 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(ContainerPolicy containerPolicy) ADVANCED: Set the mapping's containerPolicy.
void	setDefaultEmptyContainer(boolean defaultEmptyContainer) INTERNAL Indicate whether by default an empty container should be set on the field/property if the collection is not present in the XML document.
void	setField(DatabaseField field)
void	setReuseContainer(boolean reuseContainer) Specify whether the original container on the object should be used if present.
void	setUsesSingleNode(boolean useSingleNode)
void	setWrapperNullPolicy(AbstractNullPolicy policy) Set the Wrapper NullPolicy on the Mapping.
void	setXPath(java.lang.String xpathString) Set the Mapping field name attribute to the given XPath String
void	useCollectionClass(java.lang.Class concreteContainerClass) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useCollectionClassName(java.lang.String concreteContainerClassName) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useListClassName(java.lang.String concreteContainerClassName) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useMapClass(java.lang.Class concreteContainerClass, java.lang.String methodName) PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.
void	useMapClassName(java.lang.String concreteContainerClass, java.lang.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(java.lang.Object object, AbstractRecord row, AbstractSession session, DatabaseMapping.WriteType writeType) INTERNAL: Write the attribute value from the object to the row.
void	writeSingleValue(java.lang.Object value, java.lang.Object parent, XMLRecord row, 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, addSourceToTargetKeyFieldAssociation, buildReference, cascadePerformRemoveIfRequired, cascadeRegisterNewIfRequired, getFields, getInverseReferenceMapping, getSourceToTargetKeyFieldAssociations, isObjectReferenceMapping, 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, hasNestedIdentityReference, isAggregateMapping, iterate, load, loadAll, 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

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

Methods inherited from class java.lang.Object

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

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

addSourceToTargetKeyFieldAssociation, buildReference, getFields, getInverseReferenceMapping, getReferenceClass, getReferenceClassName, getSourceToTargetKeyFieldAssociations, isWriteOnly, setIsWriteOnly, setReferenceClassName

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

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

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

convertClassNamesToClasses

Constructor Detail

XMLCollectionReferenceMapping

public XMLCollectionReferenceMapping()

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

Method Detail

getField

public 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.

Specified by:

getField in interface Mapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,XMLRecord>

Overrides:

getField in class DatabaseMapping

setField

public void setField(DatabaseField field)

Overrides:

setField in class XMLObjectReferenceMapping

getXPath

public java.lang.String getXPath()

Get the XPath String

Returns:

String the XPath String associated with this Mapping

setXPath

public void setXPath(java.lang.String xpathString)

Set the Mapping field name attribute to the given XPath String

Parameters:

xpathString - String

buildFieldValue

public java.lang.Object buildFieldValue(java.lang.Object targetObject,
                                        XMLField xmlFld,
                                        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).

Specified by:

buildFieldValue in interface ObjectReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>

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,
                           java.lang.Object object,
                           AbstractSession session,
                           java.lang.Object container)

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

Specified by:

buildReference in interface CollectionReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>

buildReference

public void buildReference(java.lang.Object srcObject,
                           XMLField xmlField,
                           java.lang.Object object,
                           AbstractSession session,
                           java.lang.Object container,
                           ReferenceResolver resolver)

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

getContainerPolicy

public ContainerPolicy getContainerPolicy()

INTERNAL: Return the mapping's containerPolicy.

Specified by:

getContainerPolicy in interface Mapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,XMLRecord>

Specified by:

getContainerPolicy in interface ContainerMapping

Overrides:

getContainerPolicy in class DatabaseMapping

initialize

public void initialize(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 java.lang.Object readFromRowIntoObject(AbstractRecord databaseRow,
                                              JoinedAttributeManager joinManager,
                                              java.lang.Object targetObject,
                                              CacheKey parentCacheKey,
                                              ObjectBuildingQuery sourceQuery,
                                              AbstractSession executionSession,
                                              boolean isTargetProtected)
                                       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

readFromRowIntoObject

public java.lang.Object readFromRowIntoObject(AbstractRecord databaseRow,
                                              JoinedAttributeManager joinManager,
                                              java.lang.Object targetObject,
                                              CacheKey parentCacheKey,
                                              ObjectBuildingQuery sourceQuery,
                                              AbstractSession executionSession,
                                              boolean isTargetProtected,
                                              java.lang.Object container)
                                       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.

Throws:

DatabaseException

setContainerPolicy

public void setContainerPolicy(ContainerPolicy containerPolicy)

ADVANCED: Set the mapping's containerPolicy.

Specified by:

setContainerPolicy in interface ContainerMapping

useCollectionClass

public void useCollectionClass(java.lang.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(java.lang.String concreteContainerClassName)

Description copied from interface: ContainerMapping

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

The container class must implement (directly or indirectly) the java.util.Collection interface.

Specified by:

useCollectionClassName in interface CollectionReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>

Specified by:

useCollectionClassName in interface ContainerMapping

useListClassName

public void useListClassName(java.lang.String concreteContainerClassName)

Description copied from interface: ContainerMapping

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

The container class must implement (directly or indirectly) the java.util.List interface.

Specified by:

useListClassName in interface ContainerMapping

useMapClass

public void useMapClass(java.lang.Class concreteContainerClass,
                        java.lang.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

useMapClassName

public void useMapClassName(java.lang.String concreteContainerClass,
                            java.lang.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:

useMapClassName 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

Specified by:

usesSingleNode in interface CollectionReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>

setUsesSingleNode

public void setUsesSingleNode(boolean useSingleNode)

Specified by:

setUsesSingleNode in interface CollectionReferenceMapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,UnmarshalRecord,XMLField,XMLRecord>

writeFromObjectIntoRow

public void writeFromObjectIntoRow(java.lang.Object object,
                                   AbstractRecord row,
                                   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(java.lang.Object value,
                             java.lang.Object parent,
                             XMLRecord row,
                             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 Mapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,XMLRecord>

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.

Specified by:

isCollectionMapping in interface Mapping<AbstractSession,AttributeAccessor,ContainerPolicy,ClassDescriptor,DatabaseField,XMLRecord>

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.

Specified by:

getReuseContainer in interface XMLContainerMapping

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.

Specified by:

setReuseContainer in interface XMLContainerMapping

isDefaultEmptyContainer

public boolean isDefaultEmptyContainer()

INTERNAL Return true if an empty container should be set on the object if there is no presence of the collection in the XML document.

Specified by:

isDefaultEmptyContainer in interface XMLContainerMapping

Since:

EclipseLink 2.3.3

setDefaultEmptyContainer

public void setDefaultEmptyContainer(boolean defaultEmptyContainer)

INTERNAL Indicate whether by default an empty container should be set on the field/property if the collection is not present in the XML document.

Specified by:

setDefaultEmptyContainer in interface XMLContainerMapping

Since:

EclipseLink 2.3.3

getWrapperNullPolicy

public AbstractNullPolicy getWrapperNullPolicy()

Description copied from interface: XMLContainerMapping

Get the Wrapper NullPolicy from the Mapping.

Specified by:

getWrapperNullPolicy in interface XMLContainerMapping

setWrapperNullPolicy

public void setWrapperNullPolicy(AbstractNullPolicy policy)

Description copied from interface: XMLContainerMapping

Set the Wrapper NullPolicy on the Mapping.

Specified by:

setWrapperNullPolicy in interface XMLContainerMapping