EclipseLink 2.2.0, build 'v20110202-r8913' API Reference

org.eclipse.persistence.oxm.mappings
Class XMLCollectionReferenceMapping

java.lang.Object
  extended by org.eclipse.persistence.mappings.DatabaseMapping
      extended by org.eclipse.persistence.mappings.AggregateMapping
          extended by org.eclipse.persistence.oxm.mappings.XMLObjectReferenceMapping
              extended by org.eclipse.persistence.oxm.mappings.XMLCollectionReferenceMapping
All Implemented Interfaces:
java.io.Serializable, java.lang.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
 
Field Summary
protected  org.eclipse.persistence.internal.queries.ContainerPolicy containerPolicy
           
 
Fields inherited from class org.eclipse.persistence.oxm.mappings.XMLObjectReferenceMapping
sourceToTargetKeyFieldAssociations, sourceToTargetKeys
 
Fields inherited from class org.eclipse.persistence.mappings.AggregateMapping
referenceClass, referenceClassName, referenceDescriptor
 
Fields inherited from class org.eclipse.persistence.mappings.DatabaseMapping
attributeAccessor, attributeName, derivedIdMapping, derivesId, descriptor, fields, isCacheable, isJPAId, isLazy, isMapKeyMapping, isOptional, isPrimaryKeyMapping, isReadOnly, isRemotelyInitialized, mapsIdValue, NO_FIELDS, NO_WEIGHT, properties, weight, WEIGHT_AGGREGATE, WEIGHT_DIRECT, WEIGHT_TO_ONE, WEIGHT_TRANSFORM
 
Constructor Summary
XMLCollectionReferenceMapping()
          PUBLIC: The default constructor initializes the sourceToTargetKeyFieldAssociations and sourceToTargetKeys data structures.
 
Method Summary
 java.lang.Object buildFieldValue(java.lang.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(java.lang.Object srcObject, XMLField xmlField, java.lang.Object object, org.eclipse.persistence.internal.sessions.AbstractSession session)
           
 void buildReference(UnmarshalRecord record, XMLField xmlField, java.lang.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.
 java.lang.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.
 java.lang.Object readFromRowIntoObject(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, java.lang.Object targetObject, org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.sessions.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.
 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(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)
           
 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.
 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, 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(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.oxm.mappings.XMLObjectReferenceMapping
addSourceToTargetKeyFieldAssociation, addSourceToTargetKeyFieldAssociation, cascadePerformRemoveIfRequired, cascadeRegisterNewIfRequired, getFields, getInverseReferenceMapping, getSchemaType, getSingleValueToWriteForUnion, getSourceToTargetKeyFieldAssociations, getValueToWrite, isObjectReferenceMapping, isWriteOnly, isXMLMapping, preInitialize, setAttributeValueInObject, setIsWriteOnly, setSourceToTargetKeyFieldAssociations
 
Methods inherited from class org.eclipse.persistence.mappings.AggregateMapping
buildAggregateDeleteQuery, buildAggregateModifyQuery, buildAggregateWriteQuery, buildBackupClone, buildBackupClonePart, buildClone, buildCloneFromRow, buildClonePart, buildClonePart, buildCopy, buildCopyOfAttributeValue, buildExpression, buildNewMergeInstanceOf, compareAttributeValues, compareForChange, compareObjects, convertClassNamesToClasses, executeEvent, fixAttributeValue, fixObjectReferences, getAttributeValueFromBackupClone, getObjectBuilder, getObjectBuilderForClass, getQueryManager, getReferenceClass, getReferenceClassName, getReferenceDescriptor, getReferenceDescriptor, getReferenceDescriptor, isAggregateMapping, iterate, iterateOnAttributeValue, mergeAttributeValue, mergeChangesIntoObject, mergeIntoObject, postDelete, postDeleteAttributeValue, postInsert, postInsertAttributeValue, postUpdate, postUpdateAttributeValue, preDelete, preDeleteAttributeValue, preInsert, preInsertAttributeValue, preUpdate, preUpdateAttributeValue, remoteInitialization, setReferenceClass, setReferenceClassName, setReferenceDescriptor, updateChangeRecord, verifyDelete, verifyDeleteOfAttributeValue
 
Methods inherited from class org.eclipse.persistence.mappings.DatabaseMapping
buildBackupCloneForPartObject, buildChangeRecord, buildCloneForPartObject, buildContainerClone, buildObjectJoinExpression, buildObjectJoinExpression, buildShallowOriginalFromRow, calculateDeferredChanges, cascadeDiscoverAndPersistUnregisteredNewObjects, cascadeMerge_, cascadePerformRemovePrivateOwnedObjectFromChangeSetIfRequired, clone, cloneFields, collectFields, collectQueryParameters, createCloneValueHolder, derivesId, earlyPreDelete, extractNestedExpressions, 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, hasRootExpressionThatShouldUseOuterJoin, instantiateAttribute, isAbstractCompositeCollectionMapping, isAbstractCompositeDirectCollectionMapping, isAbstractCompositeObjectMapping, isAbstractDirectMapping, isAggregateCollectionMapping, isAggregateObjectMapping, isCacheable, isCandidateForPrivateOwnedRemoval, isCascadedLockingSupported, isChangeTrackingSupported, isCloningRequired, isDatabaseMapping, isDirectCollectionMapping, isDirectMapMapping, isDirectToFieldMapping, isDirectToXMLTypeMapping, isEISMapping, isForeignReferenceMapping, isJoiningSupported, isJPAId, isLazy, isLockableMapping, isManyToManyMapping, isManyToOneMapping, isMapKeyMapping, isNestedTableMapping, isOneToManyMapping, isOneToOneMapping, isOptional, isOwned, isPrimaryKeyMapping, isPrivateOwned, isReadOnly, isReferenceMapping, isRelationalMapping, isRemotelyInitialized, isStructureMapping, isTransformationMapping, isUnidirectionalOneToManyMapping, isUsingMethodAccess, isVariableOneToOneMapping, iterateOnRealAttributeValue, performDataModificationEvent, postCalculateChanges, postCalculateChangesOnDeleted, postInitialize, prepareCascadeLockingPolicy, readFromResultSetIntoObject, readOnly, readWrite, recordPrivateOwnedRemovals, rehashFieldDependancies, remotelyInitialized, replaceValueHoldersIn, setAttributeAccessor, setAttributeName, setChangeListener, setDerivedIdMapping, setDerivesId, setDescriptor, setFields, setGetMethodName, setIsCacheable, 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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

containerPolicy

protected org.eclipse.persistence.internal.queries.ContainerPolicy containerPolicy
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 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,
                                        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,
                           java.lang.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 -

buildReference

public void buildReference(java.lang.Object srcObject,
                           XMLField xmlField,
                           java.lang.Object object,
                           org.eclipse.persistence.internal.sessions.AbstractSession 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 java.lang.Object readFromRowIntoObject(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
                                              org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                              java.lang.Object targetObject,
                                              org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
                                              ObjectBuildingQuery sourceQuery,
                                              org.eclipse.persistence.internal.sessions.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

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(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)

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

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(java.lang.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(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 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.


EclipseLink 2.2.0, build 'v20110202-r8913' API Reference