EclipseLink 2.2.0, build 'v20110202-r8913' API Reference

org.eclipse.persistence.mappings
Class ForeignReferenceMapping

java.lang.Object
  extended by org.eclipse.persistence.mappings.DatabaseMapping
      extended by org.eclipse.persistence.mappings.ForeignReferenceMapping
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
CollectionMapping, ObjectReferenceMapping

public abstract class ForeignReferenceMapping
extends DatabaseMapping

Purpose: Abstract class for relationship mappings

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.eclipse.persistence.mappings.DatabaseMapping
DatabaseMapping.WriteType
 
Field Summary
protected  BatchFetchType batchFetchType
          Indicates whether the referenced object should always be batch read on read all queries, and defines the type of batch fetch to use.
protected  boolean cascadeDetach
           
protected  boolean cascadeMerge
           
protected  boolean cascadePersist
          Cascading flags used by the EntityManager
protected  boolean cascadeRefresh
           
protected  boolean cascadeRemove
           
protected  boolean forceInitializationOfSelectionCriteria
          This is a way (after cloning) to force the initialization of the selection criteria
protected  boolean hasCustomSelectionQuery
          Indicates whether the selection query is TopLink generated or defined by the user.
protected  org.eclipse.persistence.internal.indirection.IndirectionPolicy indirectionPolicy
          Implements indirection behavior
static int INNER_JOIN
          Specify any INNER join on a join fetch.
protected  boolean isCascadeOnDeleteSetOnDatabase
          Support delete cascading on the database relationship constraint.
protected  boolean isPrivateOwned
          Indicates whether the referenced object is privately owned or not.
protected  int joinFetch
          Define if the relationship should always be join fetched.
static int NONE
          Specify no join fetch, this is the default.
static int OUTER_JOIN
          Specify any OUTER join on a join fetch.
protected  PartitioningPolicy partitioningPolicy
          Allow the mapping's queries to be targeted at specific connection pools.
protected  java.lang.String partitioningPolicyName
          Allow the mapping's queries to be targeted at specific connection pools.
static java.lang.String QUERY_BATCH_PARAMETER
          Query parameter name used for IN batch ids.
protected  java.lang.Class referenceClass
          This is used only in descriptor proxy in remote session
protected  java.lang.String referenceClassName
           
protected  ClassDescriptor referenceDescriptor
          The descriptor of the reference class.
protected  DatabaseMapping relationshipPartner
          Used to reference the other half of a bi-directional relationship.
protected  java.lang.String relationshipPartnerAttributeName
          Set by users, used to retrieve the backpointer for this mapping
protected  boolean requiresTransientWeavedFields
          Flag used to determine if we need to weave the transient annotation on weaved fields.
protected  ReadQuery selectionQuery
          This query is used to read referenced objects for this mapping.
protected  org.eclipse.persistence.internal.sessions.AbstractSession tempInitSession
          The session is temporarily used for initialization.
 
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
protected ForeignReferenceMapping()
           
 
Method Summary
protected  java.lang.Object batchedValueFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord row, ObjectLevelReadQuery query, org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey)
          INTERNAL: Retrieve the value through using batch reading.
 void buildBackupClone(java.lang.Object clone, java.lang.Object backup, org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork)
          INTERNAL: Clone the attribute from the clone and assign it to the backup.
abstract  java.lang.Object buildBackupCloneForPartObject(java.lang.Object attributeValue, java.lang.Object clone, java.lang.Object backup, org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork)
          INTERNAL: Used during building the backup shallow copy to copy the target object without re-registering it.
protected  Expression buildBatchCriteria(ExpressionBuilder builder, ObjectLevelReadQuery query)
          INTERNAL: Return the selection criteria used to IN batch fetching.
 void buildClone(java.lang.Object original, org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey, java.lang.Object clone, org.eclipse.persistence.internal.sessions.AbstractSession cloningSession)
          INTERNAL: Clone the attribute from the original and assign it to the clone.
abstract  java.lang.Object buildCloneForPartObject(java.lang.Object attributeValue, java.lang.Object original, org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey, java.lang.Object clone, org.eclipse.persistence.internal.sessions.AbstractSession cloningSession, boolean isExisting)
          INTERNAL: Require for cloning, the part must be cloned.
 void buildCloneFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, java.lang.Object clone, org.eclipse.persistence.internal.identitymaps.CacheKey sharedCacheKey, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork, org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
          INTERNAL: A combination of readFromRowIntoObject and buildClone.
abstract  java.lang.Object[] buildReferencesPKList(java.lang.Object entity, java.lang.Object attribute, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: This method will access the target relationship and create a list of information to rebuild the relationship.
protected  java.lang.Object checkCacheForBatchKey(org.eclipse.persistence.internal.sessions.AbstractRecord sourceRow, java.lang.Object foreignKey, java.util.Map batchObjects, ReadQuery batchQuery, ObjectLevelReadQuery originalQuery, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Check if the target object is in the cache if possible based on the source row.
 java.lang.Object clone()
          INTERNAL: The mapping clones itself to create deep copy.
abstract  void collectQueryParameters(java.util.Set<org.eclipse.persistence.internal.helper.DatabaseField> cacheFields)
          INTERNAL: This method is used to store the FK fields that can be cached that correspond to noncacheable mappings the FK field values will be used to re-issue the query when cloning the shared cache entity
 boolean compareObjects(java.lang.Object firstObject, java.lang.Object secondObject, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Compare the attributes belonging to this mapping for the objects.
protected abstract  boolean compareObjectsWithoutPrivateOwned(java.lang.Object first, java.lang.Object second, org.eclipse.persistence.internal.sessions.AbstractSession session)
          Compare two objects if their parts are not private owned
protected abstract  boolean compareObjectsWithPrivateOwned(java.lang.Object first, java.lang.Object second, org.eclipse.persistence.internal.sessions.AbstractSession session)
          Compare two objects if their parts are private owned
 void convertClassNamesToClasses(java.lang.ClassLoader classLoader)
          INTERNAL: Convert all the class-name-based settings in this mapping to actual class-based settings.
 org.eclipse.persistence.internal.indirection.DatabaseValueHolder createCloneValueHolder(ValueHolderInterface attributeValue, java.lang.Object original, java.lang.Object clone, org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.sessions.AbstractSession cloningSession, boolean buildDirectlyFromRow)
          INTERNAL: Builder the unit of work value holder.
protected  boolean dontDoMerge(java.lang.Object target, java.lang.Object source, org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
          INTERNAL: Return true if the merge should be bypassed.
 void dontUseBatchReading()
          PUBLIC: Indicates whether the referenced object should always be batch read on read all queries.
 void dontUseIndirection()
          PUBLIC: Indirection means that a ValueHolder will be put in-between the attribute and the real object.
protected  void executeBatchQuery(DatabaseQuery query, org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey, java.util.Map referenceObjectsByKey, org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.sessions.AbstractRecord row)
          INTERNAL: Prepare and execute the batch query and store the results for each source object in a map keyed by the mappings source keys of the source objects.
 void extendPessimisticLockScopeInSourceQuery(ObjectLevelReadQuery sourceQuery)
          INTERNAL: Called if shouldExtendPessimisticLockScopeInSourceQuery is true.
protected  void extendPessimisticLockScopeInTargetQuery(ObjectLevelReadQuery targetQuery, ObjectBuildingQuery sourceQuery)
          INTERNAL: Called if shouldExtendPessimisticLockScopeInTargetQuery() is true.
protected  java.lang.Object extractBatchKeyFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord targetRow, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Extract the batch key value from the source row.
 java.lang.Object extractResultFromBatchQuery(ReadQuery batchQuery, org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey, org.eclipse.persistence.internal.sessions.AbstractRecord sourceRow, org.eclipse.persistence.internal.sessions.AbstractSession session, ObjectLevelReadQuery originalQuery)
          INTERNAL: Extract the value from the batch optimized query, this should be supported by most query types.
 void fixObjectReferences(java.lang.Object object, java.util.Map objectDescriptors, java.util.Map processedObjects, ObjectLevelReadQuery query, RemoteSession session)
          INTERNAL: An object has been serialized from the server to the client.
 java.lang.Object getAttributeValueFromObject(java.lang.Object object)
          INTERNAL: Return the value of an attribute which this mapping represents for an object.
 java.lang.Object getAttributeValueWithClonedValueHolders(java.lang.Object object)
          INTERNAL: Returns the attribute value from the reference object.
 BatchFetchType getBatchFetchType()
          PUBLIC: Return the type of batch fetching to use for all queries for this class if configured.
protected  ReadQuery getExtendPessimisticLockScopeDedicatedQuery(org.eclipse.persistence.internal.sessions.AbstractSession session, short lockMode)
          INTERNAL: Should be overridden by subclass that allows setting extendPessimisticLockScope to DEDICATED_QUERY.
 java.util.Collection getFieldsForTranslationInAggregate()
          INTERNAL: Return source key fields for translation by an AggregateObjectMapping By default, return an empty NonSynchronizedVector
 org.eclipse.persistence.internal.indirection.IndirectionPolicy getIndirectionPolicy()
          INTERNAL: Return the mapping's indirection policy.
 Expression getJoinCriteria(org.eclipse.persistence.internal.expressions.QueryKeyExpression exp)
          INTERNAL: Returns the join criteria stored in the mapping selection query.
 int getJoinFetch()
          PUBLIC: Return if this relationship should always be join fetched.
 java.lang.Object getObjectCorrespondingTo(java.lang.Object object, RemoteSession session, java.util.Map objectDescriptors, java.util.Map processedObjects, ObjectLevelReadQuery query)
          INTERNAL: return the object on the client corresponding to the specified object.
 PartitioningPolicy getPartitioningPolicy()
          PUBLIC: Return the mapping's partitioning policy.
 java.lang.String getPartitioningPolicyName()
          PUBLIC: Return the name of the mapping's partitioning policy.
 java.lang.Object getRealAttributeValueFromAttribute(java.lang.Object attributeValue, java.lang.Object object, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Returns the attribute value from the reference object.
 java.lang.Class getReferenceClass()
          PUBLIC: Returns the reference class.
 java.lang.String getReferenceClassName()
          INTERNAL: Returns the reference class name.
 ClassDescriptor getReferenceDescriptor()
          INTERNAL: Return the referenceDescriptor.
 DatabaseMapping getRelationshipPartner()
          INTERNAL: Return the relationshipPartner mapping for this bi-directional mapping.
 java.lang.String getRelationshipPartnerAttributeName()
          PUBLIC: Use this method retrieve the relationship partner attribute name of this bidirectional Mapping.
 Expression getSelectionCriteria()
          INTERNAL: Returns the selection criteria stored in the mapping selection query.
 ReadQuery getSelectionQuery()
          INTERNAL: Returns the read query associated with the mapping.
protected  org.eclipse.persistence.internal.sessions.AbstractSession getTempSession()
           
 java.lang.Object getValueFromRemoteValueHolder(org.eclipse.persistence.internal.sessions.remote.RemoteValueHolder remoteValueHolder)
          INTERNAL: Extract and return the appropriate value from the specified remote value holder.
 boolean hasCustomSelectionQuery()
          INTERNAL: Indicates whether the selection query is TopLink generated or defined by the user.
 boolean hasDependency()
          INTERNAL: Return if the mapping has any ownership or other dependency over its target object(s).
 void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Initialize the state of mapping.
protected  void initializeReferenceDescriptor(org.eclipse.persistence.internal.sessions.AbstractSession session)
          Initialize and set the descriptor for the referenced class in this mapping.
protected  void initializeSelectionQuery(org.eclipse.persistence.internal.sessions.AbstractSession session)
          A subclass should implement this method if it wants non default behavior.
 void instantiateAttribute(java.lang.Object object, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Trigger the instantiation of the attribute if lazy.
 boolean isAttributeValueInstantiated(java.lang.Object object)
          INTERNAL: The referenced object is checked if it is instantiated or not
 boolean isCascadeDetach()
          PUBLIC: Check cascading value for the detach operation.
 boolean isCascadeMerge()
          PUBLIC: Check cascading value for the MERGE operation.
 boolean isCascadeOnDeleteSetOnDatabase()
          ADVANCED: Return if delete cascading has been set on the database for the mapping's foreign key constraint.
 boolean isCascadePersist()
          PUBLIC: Check cascading value for the CREATE operation.
 boolean isCascadeRefresh()
          PUBLIC: Check cascading value for the REFRESH operation.
 boolean isCascadeRemove()
          PUBLIC: Check cascading value for the REMOVE operation.
protected  boolean isExtendingPessimisticLockScope(ObjectBuildingQuery sourceQuery)
          INTERNAL: Indicates whether the source query's pessimistic lock scope scope should be extended in the target query.
 boolean isForeignReferenceMapping()
          INTERNAL:
 boolean isInnerJoinFetched()
          PUBLIC: Return if this relationship should always be INNER join fetched.
 boolean isJoinFetched()
          PUBLIC: Return if this relationship should always be join fetched.
 boolean isJoiningSupported()
          INTERNAL: Return if this mapping supports joining.
 boolean isLazy()
          Return if this mapping is lazy.
 boolean isLockableMapping()
          INTERNAL: Return whether this mapping should be traversed when we are locking.
 boolean isOuterJoinFetched()
          PUBLIC: Return if this relationship should always be OUTER join fetched.
 boolean isPrivateOwned()
          PUBLIC: Return true if referenced objects are privately owned else false.
 void iterate(org.eclipse.persistence.internal.descriptors.DescriptorIterator iterator)
          INTERNAL: Iterate on the iterator's current object's attribute defined by this mapping.
abstract  void iterateOnRealAttributeValue(org.eclipse.persistence.internal.descriptors.DescriptorIterator iterator, java.lang.Object realAttributeValue)
          INTERNAL: Iterate on the attribute value.
 void mergeRemoteValueHolder(java.lang.Object clientSideDomainObject, java.lang.Object serverSideDomainObject, org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
          INTERNAL: Replace the client value holder with the server value holder, after copying some of the settings from the client value holder.
 void postInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Ensure the container policy is post initialized
protected  void postPrepareNestedBatchQuery(ReadQuery batchQuery, ObjectLevelReadQuery query)
          INTERNAL: Allow the mapping the do any further batch preparation.
 void preInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Initialize the state of mapping.
protected  ReadQuery prepareHistoricalQuery(ReadQuery targetQuery, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
          INTERNAL: Allow for the mapping to perform any historical query additions.
 ReadQuery prepareNestedBatchQuery(ObjectLevelReadQuery query)
          INTERNAL: Clone and prepare the selection query as a nested batch read query.
protected  ObjectLevelReadQuery prepareNestedJoinQueryClone(org.eclipse.persistence.internal.sessions.AbstractRecord row, java.util.List dataResults, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
          INTERNAL: Prepare the clone of the nested query for joining.
 ObjectLevelReadQuery prepareNestedJoins(org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, ObjectBuildingQuery baseQuery, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Clone and prepare the JoinedAttributeManager nested JoinedAttributeManager.
 void privateOwnedRelationship()
          PUBLIC: Sets the reference object to be a private owned.
 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 value from the row and set the attribute to this value in the object.
 void remoteInitialization(DistributedSession session)
          INTERNAL: Once descriptors are serialized to the remote session.
 java.util.Map replaceValueHoldersIn(java.lang.Object object, org.eclipse.persistence.internal.sessions.remote.RemoteSessionController controller)
          INTERNAL: replace the value holders in the specified reference object(s)
 boolean requiresTransientWeavedFields()
          Returns true if this mappings associated weaved field requires a transient setting to avoid metadata processing.
 void setBatchFetchType(BatchFetchType batchFetchType)
          PUBLIC: Set the type of batch fetching to use for all queries for this class.
 void setCascadeAll(boolean value)
          PUBLIC: Sets the cascading for all JPA operations.
 void setCascadeDetach(boolean value)
          PUBLIC: Sets the cascading for the JPA detach operation.
 void setCascadeMerge(boolean value)
          PUBLIC: Sets the cascading for the JPA MERGE operation.
 void setCascadePersist(boolean value)
          PUBLIC: Sets the cascading for the JPA CREATE operation.
 void setCascadeRefresh(boolean value)
          PUBLIC: Sets the cascading for the JPA REFRESH operation.
 void setCascadeRemove(boolean value)
          PUBLIC: Sets the cascading for the JPA REMOVE operation.
 void setCustomSelectionQuery(ReadQuery query)
          PUBLIC: Relationship mappings creates a read query to read reference objects.
 void setForceInitializationOfSelectionCriteria(boolean bool)
          INTERNAL: A way of forcing the selection criteria to be rebuilt.
protected  void setHasCustomSelectionQuery(boolean bool)
           
 void setIndirectionPolicy(org.eclipse.persistence.internal.indirection.IndirectionPolicy indirectionPolicy)
          ADVANCED: Set the indirection policy.
 void setIsCacheable(boolean cacheable)
          Used to signal that this mapping references a protected/isolated entity and requires special merge/object building behaviour.
 void setIsCascadeOnDeleteSetOnDatabase(boolean isCascadeOnDeleteSetOnDatabase)
          ADVANCED: Set if delete cascading has been set on the database for the mapping's foreign key constraint.
 void setIsPrivateOwned(boolean isPrivateOwned)
          PUBLIC: Set if the relationship is privately owned.
 void setJoinFetch(int joinFetch)
          PUBLIC: Indicates whether the referenced object(s) should always be joined on read queries.
 void setPartitioningPolicy(PartitioningPolicy partitioningPolicy)
          PUBLIC: Set the mapping's partitioning policy.
 void setPartitioningPolicyName(java.lang.String partitioningPolicyName)
          PUBLIC: Set the name of the mapping's partitioning policy.
 void setRealAttributeValueInObject(java.lang.Object object, java.lang.Object value)
          INTERNAL: Set the value of the attribute mapped by this mapping, placing it inside a value holder if necessary.
 void setReferenceClass(java.lang.Class referenceClass)
          PUBLIC: Set the referenced class.
 void setReferenceClassName(java.lang.String referenceClassName)
          INTERNAL: Used by MW.
protected  void setReferenceDescriptor(ClassDescriptor aDescriptor)
          Set the referenceDescriptor.
 void setRelationshipPartner(DatabaseMapping mapping)
          INTERNAL: Sets the relationshipPartner mapping for this bi-directional mapping.
 void setRelationshipPartnerAttributeName(java.lang.String attributeName)
          PUBLIC: Use this method to specify the relationship partner attribute name of a bidirectional Mapping.
 void setRequiresTransientWeavedFields(boolean requiresTransientWeavedFields)
          Set this flag if this mappings associated weaved field requires a transient setting to avoid metadata processing.
 void setSelectionCall(Call call)
          PUBLIC: This is a property on the mapping which will allow custom call to be substituted for reading a reference object.
 void setSelectionCriteria(Expression anExpression)
          PUBLIC: Sets the selection criteria to be used as a where clause to read reference objects.
protected  void setSelectionQuery(ReadQuery aQuery)
          Sets the query
 void setSelectionSQLString(java.lang.String sqlString)
          PUBLIC: This is a property on the mapping which will allow custom SQL to be substituted for reading a reference object.
 void setShouldExtendPessimisticLockScope(boolean shouldExtend)
          ADVANCED: Indicates whether pessimistic lock of ObjectLevelReadQuery with isPessimisticLockScopeExtended set to true should be applied through this mapping beyond the tables mapped to the source object.
protected  void setTempSession(org.eclipse.persistence.internal.sessions.AbstractSession session)
           
 void setUsesBatchReading(boolean usesBatchReading)
          PUBLIC: Indicates whether the referenced object should always be batch read on read all queries.
 void setUsesIndirection(boolean usesIndirection)
          PUBLIC: Indirection means that a ValueHolder will be put in-between the attribute and the real object.
 boolean shouldExtendPessimisticLockScope()
          INTERNAL: Indicates whether pessimistic lock of ObjectLevelReadQuery with isPessimisticLockScopeExtended set to true should be applied through this mapping beyond the tables mapped to the source object.
 boolean shouldExtendPessimisticLockScopeInDedicatedQuery()
           
 boolean shouldExtendPessimisticLockScopeInSourceQuery()
           
 boolean shouldExtendPessimisticLockScopeInTargetQuery()
           
protected  boolean shouldForceInitializationOfSelectionCriteria()
          INTERNAL:
protected  boolean shouldInitializeSelectionCriteria()
           
 boolean shouldMergeCascadeParts(org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
          INTERNAL: Returns true if the merge should cascade to the mappings reference's parts.
protected  boolean shouldMergeCascadeReference(org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
          Returns true if the merge should cascade to the mappings reference.
protected  boolean shouldObjectModifyCascadeToParts(ObjectLevelModifyQuery query)
          Returns true if any process leading to object modification should also affect its parts Usually used by write, insert, update and delete.
 boolean shouldUseBatchReading()
          PUBLIC: Indicates whether the referenced object should always be batch read on read all queries.
protected  boolean shouldUseValueFromRowWithJoin(org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, ObjectBuildingQuery sourceQuery)
          INTERNAL: Indicates whether valueFromRow should call valueFromRowInternalWithJoin (true) or valueFromRowInternal (false)
 org.eclipse.persistence.internal.sessions.AbstractRecord trimRowForJoin(org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
          INTERNAL: Return a sub-partition of the row starting at the index for the mapping.
 org.eclipse.persistence.internal.sessions.AbstractRecord trimRowForJoin(org.eclipse.persistence.internal.sessions.AbstractRecord row, java.lang.Object value, org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
          INTERNAL: Return a sub-partition of the row starting at the index.
 void useBasicIndirection()
          PUBLIC: Indirection means that a ValueHolder will be put in-between the attribute and the real object.
 void useBatchReading()
          PUBLIC: Indicates whether the referenced object should always be batch read on read all queries.
 void useContainerIndirection(java.lang.Class containerClass)
          PUBLIC: Indirection means that a IndirectContainer (wrapping a ValueHolder) will be put in-between the attribute and the real object.
 void useInnerJoinFetch()
          PUBLIC: Specify this relationship to always be join fetched using an INNER join.
 void useOuterJoinFetch()
          PUBLIC: Specify this relationship to always be join fetched using an OUTER join.
 boolean usesIndirection()
          PUBLIC: Indirection means that some sort of indirection object will be put in-between the attribute and the real object.
 void useWeavedIndirection(java.lang.String getMethodName, java.lang.String setMethodName, boolean hasUsedMethodAccess)
          INTERNAL: Configures the mapping to used weaved indirection.
 void validateBeforeInitialization(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: To validate mappings declaration
abstract  java.lang.Object valueFromPKList(java.lang.Object[] pks, org.eclipse.persistence.internal.sessions.AbstractSession session)
          This method is used to load a relationship from a list of PKs.
 java.lang.Object valueFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey, org.eclipse.persistence.internal.sessions.AbstractSession executionSession, boolean isTargetProtected)
          INTERNAL: Return the value of the reference attribute or a value holder.
protected  java.lang.Object valueFromRowInternal(org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
          INTERNAL: Return the value of the reference attribute or a value holder.
protected  java.lang.Object valueFromRowInternalWithJoin(org.eclipse.persistence.internal.sessions.AbstractRecord row, org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager, ObjectBuildingQuery sourceQuery, org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey, org.eclipse.persistence.internal.sessions.AbstractSession executionSession, boolean isTargetProtected)
          INTERNAL: If the query used joining or partial attributes, build the target object directly.
 
Methods inherited from class org.eclipse.persistence.mappings.DatabaseMapping
buildChangeRecord, buildContainerClone, buildCopy, buildExpression, buildObjectJoinExpression, buildObjectJoinExpression, buildShallowOriginalFromRow, calculateDeferredChanges, cascadeDiscoverAndPersistUnregisteredNewObjects, cascadeMerge_, cascadePerformRemoveIfRequired, cascadePerformRemovePrivateOwnedObjectFromChangeSetIfRequired, cascadeRegisterNewIfRequired, cloneFields, collectFields, compareForChange, derivesId, earlyPreDelete, extractNestedExpressions, fixRealObjectReferences, getAttributeAccessor, getAttributeClassification, getAttributeName, getContainerPolicy, getDerivedIdMapping, getDescriptor, getField, getFieldClassification, getFields, getGetMethodName, getMapsIdValue, getProperties, getProperty, getRealAttributeValueFromObject, getRealCollectionAttributeValueFromObject, getSelectFields, getSelectTables, getSetMethodName, getWeight, hasConstraintDependency, hasInverseConstraintDependency, hasMapsIdValue, hasRootExpressionThatShouldUseOuterJoin, isAbstractCompositeCollectionMapping, isAbstractCompositeDirectCollectionMapping, isAbstractCompositeObjectMapping, isAbstractDirectMapping, isAggregateCollectionMapping, isAggregateMapping, isAggregateObjectMapping, isCacheable, isCandidateForPrivateOwnedRemoval, isCascadedLockingSupported, isChangeTrackingSupported, isCloningRequired, isCollectionMapping, isDatabaseMapping, isDirectCollectionMapping, isDirectMapMapping, isDirectToFieldMapping, isDirectToXMLTypeMapping, isEISMapping, isJPAId, isManyToManyMapping, isManyToOneMapping, isMapKeyMapping, isNestedTableMapping, isObjectReferenceMapping, isOneToManyMapping, isOneToOneMapping, isOptional, isOwned, isPrimaryKeyMapping, isReadOnly, isReferenceMapping, isRelationalMapping, isRemotelyInitialized, isStructureMapping, isTransformationMapping, isUnidirectionalOneToManyMapping, isUsingMethodAccess, isVariableOneToOneMapping, isWriteOnly, isXMLMapping, mergeChangesIntoObject, mergeIntoObject, performDataModificationEvent, postCalculateChanges, postCalculateChangesOnDeleted, postDelete, postInsert, postUpdate, preDelete, preInsert, prepareCascadeLockingPolicy, preUpdate, readFromResultSetIntoObject, readOnly, readWrite, recordPrivateOwnedRemovals, rehashFieldDependancies, remotelyInitialized, setAttributeAccessor, setAttributeName, setAttributeValueInObject, setChangeListener, setDerivedIdMapping, setDerivesId, setDescriptor, setFields, setGetMethodName, setIsJPAId, setIsLazy, setIsMapKeyMapping, setIsOptional, setIsPrimaryKeyMapping, setIsReadOnly, setMapsIdValue, setProperties, setProperty, setSetMethodName, setWeight, simpleAddToCollectionChangeRecord, simpleRemoveFromCollectionChangeRecord, toString, updateChangeRecord, updateCollectionChangeRecord, validateAfterInitialization, valueFromObject, valueFromResultSet, valueFromRow, verifyDelete, writeFromAttributeIntoRow, writeFromObjectIntoRow, 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

QUERY_BATCH_PARAMETER

public static final java.lang.String QUERY_BATCH_PARAMETER
Query parameter name used for IN batch ids.

See Also:
Constant Field Values

referenceClass

protected java.lang.Class referenceClass
This is used only in descriptor proxy in remote session


referenceClassName

protected java.lang.String referenceClassName

tempInitSession

protected transient org.eclipse.persistence.internal.sessions.AbstractSession tempInitSession
The session is temporarily used for initialization. Once used, it is set to null


referenceDescriptor

protected transient ClassDescriptor referenceDescriptor
The descriptor of the reference class.


selectionQuery

protected transient ReadQuery selectionQuery
This query is used to read referenced objects for this mapping.


isPrivateOwned

protected boolean isPrivateOwned
Indicates whether the referenced object is privately owned or not.


batchFetchType

protected BatchFetchType batchFetchType
Indicates whether the referenced object should always be batch read on read all queries, and defines the type of batch fetch to use.


indirectionPolicy

protected org.eclipse.persistence.internal.indirection.IndirectionPolicy indirectionPolicy
Implements indirection behavior


hasCustomSelectionQuery

protected transient boolean hasCustomSelectionQuery
Indicates whether the selection query is TopLink generated or defined by the user.


relationshipPartner

protected DatabaseMapping relationshipPartner
Used to reference the other half of a bi-directional relationship.


relationshipPartnerAttributeName

protected java.lang.String relationshipPartnerAttributeName
Set by users, used to retrieve the backpointer for this mapping


cascadePersist

protected boolean cascadePersist
Cascading flags used by the EntityManager


cascadeMerge

protected boolean cascadeMerge

cascadeRefresh

protected boolean cascadeRefresh

cascadeRemove

protected boolean cascadeRemove

cascadeDetach

protected boolean cascadeDetach

requiresTransientWeavedFields

protected boolean requiresTransientWeavedFields
Flag used to determine if we need to weave the transient annotation on weaved fields.


joinFetch

protected int joinFetch
Define if the relationship should always be join fetched.


INNER_JOIN

public static final int INNER_JOIN
Specify any INNER join on a join fetch.

See Also:
Constant Field Values

OUTER_JOIN

public static final int OUTER_JOIN
Specify any OUTER join on a join fetch.

See Also:
Constant Field Values

NONE

public static final int NONE
Specify no join fetch, this is the default.

See Also:
Constant Field Values

forceInitializationOfSelectionCriteria

protected boolean forceInitializationOfSelectionCriteria
This is a way (after cloning) to force the initialization of the selection criteria


isCascadeOnDeleteSetOnDatabase

protected boolean isCascadeOnDeleteSetOnDatabase
Support delete cascading on the database relationship constraint.


partitioningPolicy

protected PartitioningPolicy partitioningPolicy
Allow the mapping's queries to be targeted at specific connection pools.


partitioningPolicyName

protected java.lang.String partitioningPolicyName
Allow the mapping's queries to be targeted at specific connection pools.

Constructor Detail

ForeignReferenceMapping

protected ForeignReferenceMapping()
Method Detail

getPartitioningPolicy

public PartitioningPolicy getPartitioningPolicy()
PUBLIC: Return the mapping's partitioning policy.


setPartitioningPolicy

public void setPartitioningPolicy(PartitioningPolicy partitioningPolicy)
PUBLIC: Set the mapping's partitioning policy. A PartitioningPolicy is used to partition, load-balance or replicate data across multiple difference databases or across a database cluster such as Oracle RAC. Partitioning can provide improved scalability by allowing multiple database machines to service requests. Setting a policy on a mapping will set the policy on all of its mappings.


getPartitioningPolicyName

public java.lang.String getPartitioningPolicyName()
PUBLIC: Return the name of the mapping's partitioning policy. A PartitioningPolicy with the same name must be defined on the Project. A PartitioningPolicy is used to partition the data for a class across multiple difference databases or across a database cluster such as Oracle RAC. Partitioning can provide improved scalability by allowing multiple database machines to service requests.


setPartitioningPolicyName

public void setPartitioningPolicyName(java.lang.String partitioningPolicyName)
PUBLIC: Set the name of the mapping's partitioning policy. A PartitioningPolicy with the same name must be defined on the Project. A PartitioningPolicy is used to partition the data for a class across multiple difference databases or across a database cluster such as Oracle RAC. Partitioning can provide improved scalability by allowing multiple database machines to service requests.


batchedValueFromRow

protected java.lang.Object batchedValueFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                               ObjectLevelReadQuery query,
                                               org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey)
INTERNAL: Retrieve the value through using batch reading. This executes a single query to read the target for all of the objects and stores the result of the batch query in the original query to allow the other objects to share the results.


buildBackupClone

public void buildBackupClone(java.lang.Object clone,
                             java.lang.Object backup,
                             org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork)
INTERNAL: Clone the attribute from the clone and assign it to the backup.

Specified by:
buildBackupClone in class DatabaseMapping

buildBackupCloneForPartObject

public abstract java.lang.Object buildBackupCloneForPartObject(java.lang.Object attributeValue,
                                                               java.lang.Object clone,
                                                               java.lang.Object backup,
                                                               org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork)
INTERNAL: Used during building the backup shallow copy to copy the target object without re-registering it.

Overrides:
buildBackupCloneForPartObject in class DatabaseMapping

buildClone

public void buildClone(java.lang.Object original,
                       org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey,
                       java.lang.Object clone,
                       org.eclipse.persistence.internal.sessions.AbstractSession cloningSession)
INTERNAL: Clone the attribute from the original and assign it to the clone.

Specified by:
buildClone in class DatabaseMapping

buildCloneFromRow

public void buildCloneFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord databaseRow,
                              org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                              java.lang.Object clone,
                              org.eclipse.persistence.internal.identitymaps.CacheKey sharedCacheKey,
                              ObjectBuildingQuery sourceQuery,
                              org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork,
                              org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
INTERNAL: A combination of readFromRowIntoObject and buildClone.

buildClone assumes the attribute value exists on the original and can simply be copied.

readFromRowIntoObject assumes that one is building an original.

Both of the above assumptions are false in this method, and actually attempts to do both at the same time.

Extract value from the row and set the attribute to this value in the working copy clone. In order to bypass the shared cache when in transaction a UnitOfWork must be able to populate working copies directly from the row.

Specified by:
buildCloneFromRow in class DatabaseMapping

buildCloneForPartObject

public abstract java.lang.Object buildCloneForPartObject(java.lang.Object attributeValue,
                                                         java.lang.Object original,
                                                         org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey,
                                                         java.lang.Object clone,
                                                         org.eclipse.persistence.internal.sessions.AbstractSession cloningSession,
                                                         boolean isExisting)
INTERNAL: Require for cloning, the part must be cloned.

Overrides:
buildCloneForPartObject in class DatabaseMapping

clone

public java.lang.Object clone()
INTERNAL: The mapping clones itself to create deep copy.

Overrides:
clone in class DatabaseMapping

buildReferencesPKList

public abstract java.lang.Object[] buildReferencesPKList(java.lang.Object entity,
                                                         java.lang.Object attribute,
                                                         org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: This method will access the target relationship and create a list of information to rebuild the relationship. This method is used in combination with the CachedValueHolder to store references to PK's to be loaded from a cache instead of a query.


compareObjects

public boolean compareObjects(java.lang.Object firstObject,
                              java.lang.Object secondObject,
                              org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Compare the attributes belonging to this mapping for the objects.

Specified by:
compareObjects in class DatabaseMapping

compareObjectsWithoutPrivateOwned

protected abstract boolean compareObjectsWithoutPrivateOwned(java.lang.Object first,
                                                             java.lang.Object second,
                                                             org.eclipse.persistence.internal.sessions.AbstractSession session)
Compare two objects if their parts are not private owned


compareObjectsWithPrivateOwned

protected abstract boolean compareObjectsWithPrivateOwned(java.lang.Object first,
                                                          java.lang.Object second,
                                                          org.eclipse.persistence.internal.sessions.AbstractSession session)
Compare two objects if their parts are private owned


convertClassNamesToClasses

public void convertClassNamesToClasses(java.lang.ClassLoader classLoader)
INTERNAL: Convert all the class-name-based settings in this mapping to actual class-based settings. This method is used when converting a project that has been built with class names to a project with classes.

Overrides:
convertClassNamesToClasses in class DatabaseMapping

createCloneValueHolder

public org.eclipse.persistence.internal.indirection.DatabaseValueHolder createCloneValueHolder(ValueHolderInterface attributeValue,
                                                                                               java.lang.Object original,
                                                                                               java.lang.Object clone,
                                                                                               org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                                                                               org.eclipse.persistence.internal.sessions.AbstractSession cloningSession,
                                                                                               boolean buildDirectlyFromRow)
INTERNAL: Builder the unit of work value holder. Ignore the original object.

Overrides:
createCloneValueHolder in class DatabaseMapping
Parameters:
buildDirectlyFromRow - indicates that we are building the clone directly from a row as opposed to building the original from the row, putting it in the shared cache, and then cloning the original.

dontDoMerge

protected boolean dontDoMerge(java.lang.Object target,
                              java.lang.Object source,
                              org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
INTERNAL: Return true if the merge should be bypassed. This would be the case for several reasons, depending on the kind of merge taking place.


dontUseBatchReading

public void dontUseBatchReading()
PUBLIC: Indicates whether the referenced object should always be batch read on read all queries. Batch reading will read all of the related objects in a single query when accessed from an originating read all. This should only be used if it is know that the related objects are always required with the source object, or indirection is not used.


dontUseIndirection

public void dontUseIndirection()
PUBLIC: Indirection means that a ValueHolder will be put in-between the attribute and the real object. This allows for the reading of the target from the database to be delayed until accessed. This defaults to true and is strongly suggested as it give a huge performance gain.


extendPessimisticLockScopeInTargetQuery

protected void extendPessimisticLockScopeInTargetQuery(ObjectLevelReadQuery targetQuery,
                                                       ObjectBuildingQuery sourceQuery)
INTERNAL: Called if shouldExtendPessimisticLockScopeInTargetQuery() is true. Adds locking clause to the target query to extend pessimistic lock scope.


extendPessimisticLockScopeInSourceQuery

public void extendPessimisticLockScopeInSourceQuery(ObjectLevelReadQuery sourceQuery)
INTERNAL: Called if shouldExtendPessimisticLockScopeInSourceQuery is true. Adds fields to be locked to the where clause of the source query. Note that the sourceQuery must be ObjectLevelReadQuery so that it has ExpressionBuilder. This method must be implemented in subclasses that allow setting shouldExtendPessimisticLockScopeInSourceQuery to true.


extractResultFromBatchQuery

public java.lang.Object extractResultFromBatchQuery(ReadQuery batchQuery,
                                                    org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
                                                    org.eclipse.persistence.internal.sessions.AbstractRecord sourceRow,
                                                    org.eclipse.persistence.internal.sessions.AbstractSession session,
                                                    ObjectLevelReadQuery originalQuery)
                                             throws QueryException
INTERNAL: Extract the value from the batch optimized query, this should be supported by most query types.

Throws:
QueryException

extractBatchKeyFromRow

protected java.lang.Object extractBatchKeyFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord targetRow,
                                                  org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Extract the batch key value from the source row. Used for batch reading, most following same order and fields as in the mapping. The method should be overridden by classes that support batch reading.


collectQueryParameters

public abstract void collectQueryParameters(java.util.Set<org.eclipse.persistence.internal.helper.DatabaseField> cacheFields)
INTERNAL: This method is used to store the FK fields that can be cached that correspond to noncacheable mappings the FK field values will be used to re-issue the query when cloning the shared cache entity

Overrides:
collectQueryParameters in class DatabaseMapping

checkCacheForBatchKey

protected java.lang.Object checkCacheForBatchKey(org.eclipse.persistence.internal.sessions.AbstractRecord sourceRow,
                                                 java.lang.Object foreignKey,
                                                 java.util.Map batchObjects,
                                                 ReadQuery batchQuery,
                                                 ObjectLevelReadQuery originalQuery,
                                                 org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Check if the target object is in the cache if possible based on the source row. If in the cache, add the object to the batch results. Return null if not possible or not in the cache.


executeBatchQuery

protected void executeBatchQuery(DatabaseQuery query,
                                 org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
                                 java.util.Map referenceObjectsByKey,
                                 org.eclipse.persistence.internal.sessions.AbstractSession session,
                                 org.eclipse.persistence.internal.sessions.AbstractRecord row)
INTERNAL: Prepare and execute the batch query and store the results for each source object in a map keyed by the mappings source keys of the source objects.


prepareNestedJoins

public ObjectLevelReadQuery prepareNestedJoins(org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                               ObjectBuildingQuery baseQuery,
                                               org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Clone and prepare the JoinedAttributeManager nested JoinedAttributeManager. This is used for nested joining as the JoinedAttributeManager passed to the joined build object.


postInitialize

public void postInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Ensure the container policy is post initialized

Overrides:
postInitialize in class DatabaseMapping

postPrepareNestedBatchQuery

protected void postPrepareNestedBatchQuery(ReadQuery batchQuery,
                                           ObjectLevelReadQuery query)
INTERNAL: Allow the mapping the do any further batch preparation.


buildBatchCriteria

protected Expression buildBatchCriteria(ExpressionBuilder builder,
                                        ObjectLevelReadQuery query)
INTERNAL: Return the selection criteria used to IN batch fetching.


prepareNestedBatchQuery

public ReadQuery prepareNestedBatchQuery(ObjectLevelReadQuery query)
INTERNAL: Clone and prepare the selection query as a nested batch read query. This is used for nested batch reading.


fixObjectReferences

public void fixObjectReferences(java.lang.Object object,
                                java.util.Map objectDescriptors,
                                java.util.Map processedObjects,
                                ObjectLevelReadQuery query,
                                RemoteSession session)
INTERNAL: An object has been serialized from the server to the client. Replace the transient attributes of the remote value holders with client-side objects.

Specified by:
fixObjectReferences in class DatabaseMapping

getAttributeValueFromObject

public java.lang.Object getAttributeValueFromObject(java.lang.Object object)
                                             throws DescriptorException
INTERNAL: Return the value of an attribute which this mapping represents for an object.

Overrides:
getAttributeValueFromObject in class DatabaseMapping
Throws:
DescriptorException

getAttributeValueWithClonedValueHolders

public java.lang.Object getAttributeValueWithClonedValueHolders(java.lang.Object object)
INTERNAL: Returns the attribute value from the reference object. If the attribute is using indirection the value of the value-holder is returned. If the value holder is not instantiated then it is instantiated.


getFieldsForTranslationInAggregate

public java.util.Collection getFieldsForTranslationInAggregate()
INTERNAL: Return source key fields for translation by an AggregateObjectMapping By default, return an empty NonSynchronizedVector


getExtendPessimisticLockScopeDedicatedQuery

protected ReadQuery getExtendPessimisticLockScopeDedicatedQuery(org.eclipse.persistence.internal.sessions.AbstractSession session,
                                                                short lockMode)
INTERNAL: Should be overridden by subclass that allows setting extendPessimisticLockScope to DEDICATED_QUERY.


getIndirectionPolicy

public org.eclipse.persistence.internal.indirection.IndirectionPolicy getIndirectionPolicy()
INTERNAL: Return the mapping's indirection policy.


getJoinCriteria

public Expression getJoinCriteria(org.eclipse.persistence.internal.expressions.QueryKeyExpression exp)
INTERNAL: Returns the join criteria stored in the mapping selection query. This criteria is used to read reference objects across the tables from the database.


getObjectCorrespondingTo

public java.lang.Object getObjectCorrespondingTo(java.lang.Object object,
                                                 RemoteSession session,
                                                 java.util.Map objectDescriptors,
                                                 java.util.Map processedObjects,
                                                 ObjectLevelReadQuery query)
INTERNAL: return the object on the client corresponding to the specified object. ForeignReferenceMappings have to worry about maintaining object identity.

Overrides:
getObjectCorrespondingTo in class DatabaseMapping

getRealAttributeValueFromAttribute

public java.lang.Object getRealAttributeValueFromAttribute(java.lang.Object attributeValue,
                                                           java.lang.Object object,
                                                           org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Returns the attribute value from the reference object. If the attribute is using indirection the value of the value-holder is returned. If the value holder is not instantiated then it is instantiated.

Overrides:
getRealAttributeValueFromAttribute in class DatabaseMapping

isLazy

public boolean isLazy()
Return if this mapping is lazy. For relationship mappings this should normally be the same value as indirection, however for eager relationships this can be used with indirection to allow indirection locking and change tracking, but still always force instantiation.

Overrides:
isLazy in class DatabaseMapping

isLockableMapping

public boolean isLockableMapping()
INTERNAL: Return whether this mapping should be traversed when we are locking.

Overrides:
isLockableMapping in class DatabaseMapping
Returns:

instantiateAttribute

public void instantiateAttribute(java.lang.Object object,
                                 org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Trigger the instantiation of the attribute if lazy.

Overrides:
instantiateAttribute in class DatabaseMapping

getReferenceClass

public java.lang.Class getReferenceClass()
PUBLIC: Returns the reference class.


getReferenceClassName

public java.lang.String getReferenceClassName()
INTERNAL: Returns the reference class name.


getReferenceDescriptor

public ClassDescriptor getReferenceDescriptor()
INTERNAL: Return the referenceDescriptor. This is a descriptor which is associated with the reference class.

Overrides:
getReferenceDescriptor in class DatabaseMapping

getRelationshipPartner

public DatabaseMapping getRelationshipPartner()
INTERNAL: Return the relationshipPartner mapping for this bi-directional mapping. If the relationshipPartner is null then this is a uni-directional mapping.

Overrides:
getRelationshipPartner in class DatabaseMapping

getRelationshipPartnerAttributeName

public java.lang.String getRelationshipPartnerAttributeName()
PUBLIC: Use this method retrieve the relationship partner attribute name of this bidirectional Mapping.


getSelectionCriteria

public Expression getSelectionCriteria()
INTERNAL: Returns the selection criteria stored in the mapping selection query. This criteria is used to read reference objects from the database. It will return null before initialization. To obtain the selection criteria before initialization (e.g., in a customizer) you can use the buildSelectionCriteria() method defined by some subclasses.

See Also:
OneToOneMapping.buildSelectionCriteria(), OneToManyMapping.buildSelectionCriteria()

getSelectionQuery

public ReadQuery getSelectionQuery()
INTERNAL: Returns the read query associated with the mapping.


getTempSession

protected org.eclipse.persistence.internal.sessions.AbstractSession getTempSession()

getValueFromRemoteValueHolder

public java.lang.Object getValueFromRemoteValueHolder(org.eclipse.persistence.internal.sessions.remote.RemoteValueHolder remoteValueHolder)
INTERNAL: Extract and return the appropriate value from the specified remote value holder.

Overrides:
getValueFromRemoteValueHolder in class DatabaseMapping

hasCustomSelectionQuery

public boolean hasCustomSelectionQuery()
INTERNAL: Indicates whether the selection query is TopLink generated or defined by the user.


preInitialize

public void preInitialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
                   throws DescriptorException
INTERNAL: Initialize the state of mapping.

Overrides:
preInitialize in class DatabaseMapping
Throws:
DescriptorException

initialize

public void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
                throws DescriptorException
INTERNAL: Initialize the state of mapping.

Overrides:
initialize in class DatabaseMapping
Throws:
DescriptorException

initializeReferenceDescriptor

protected void initializeReferenceDescriptor(org.eclipse.persistence.internal.sessions.AbstractSession session)
                                      throws DescriptorException
Initialize and set the descriptor for the referenced class in this mapping.

Throws:
DescriptorException

initializeSelectionQuery

protected void initializeSelectionQuery(org.eclipse.persistence.internal.sessions.AbstractSession session)
                                 throws DescriptorException
A subclass should implement this method if it wants non default behavior.

Throws:
DescriptorException

isAttributeValueInstantiated

public boolean isAttributeValueInstantiated(java.lang.Object object)
INTERNAL: The referenced object is checked if it is instantiated or not


isCascadeDetach

public boolean isCascadeDetach()
PUBLIC: Check cascading value for the detach operation.


isCascadePersist

public boolean isCascadePersist()
PUBLIC: Check cascading value for the CREATE operation.


isCascadeMerge

public boolean isCascadeMerge()
PUBLIC: Check cascading value for the MERGE operation.


isCascadeRefresh

public boolean isCascadeRefresh()
PUBLIC: Check cascading value for the REFRESH operation.


isCascadeRemove

public boolean isCascadeRemove()
PUBLIC: Check cascading value for the REMOVE operation.


hasDependency

public boolean hasDependency()
INTERNAL: Return if the mapping has any ownership or other dependency over its target object(s).

Overrides:
hasDependency in class DatabaseMapping

isForeignReferenceMapping

public boolean isForeignReferenceMapping()
INTERNAL:

Overrides:
isForeignReferenceMapping in class DatabaseMapping

isJoiningSupported

public boolean isJoiningSupported()
INTERNAL: Return if this mapping supports joining.

Overrides:
isJoiningSupported in class DatabaseMapping

isPrivateOwned

public boolean isPrivateOwned()
PUBLIC: Return true if referenced objects are privately owned else false.

Overrides:
isPrivateOwned in class DatabaseMapping

iterate

public void iterate(org.eclipse.persistence.internal.descriptors.DescriptorIterator iterator)
INTERNAL: Iterate on the iterator's current object's attribute defined by this mapping. The iterator's settings for cascading and value holders determine how the iteration continues from here.

Specified by:
iterate in class DatabaseMapping

iterateOnRealAttributeValue

public abstract void iterateOnRealAttributeValue(org.eclipse.persistence.internal.descriptors.DescriptorIterator iterator,
                                                 java.lang.Object realAttributeValue)
INTERNAL: Iterate on the attribute value. The value holder has already been processed.

Overrides:
iterateOnRealAttributeValue in class DatabaseMapping

mergeRemoteValueHolder

public void mergeRemoteValueHolder(java.lang.Object clientSideDomainObject,
                                   java.lang.Object serverSideDomainObject,
                                   org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
INTERNAL: Replace the client value holder with the server value holder, after copying some of the settings from the client value holder.


privateOwnedRelationship

public void privateOwnedRelationship()
PUBLIC: Sets the reference object to be a private owned. The default behavior is non private owned, or independent.

See Also:
setIsPrivateOwned(boolean)

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 value from the row and set the attribute to this value in the object. return value as this value will have been converted to the appropriate type for the object.

Overrides:
readFromRowIntoObject in class DatabaseMapping
Throws:
DatabaseException

remoteInitialization

public void remoteInitialization(DistributedSession session)
INTERNAL: Once descriptors are serialized to the remote session. All its mappings and reference descriptors are traversed. Usually mappings are initialized and serialized reference descriptors are replaced with local descriptors if they already exist on the remote session.

Overrides:
remoteInitialization in class DatabaseMapping

replaceValueHoldersIn

public java.util.Map replaceValueHoldersIn(java.lang.Object object,
                                           org.eclipse.persistence.internal.sessions.remote.RemoteSessionController controller)
INTERNAL: replace the value holders in the specified reference object(s)

Overrides:
replaceValueHoldersIn in class DatabaseMapping

requiresTransientWeavedFields

public boolean requiresTransientWeavedFields()
Returns true if this mappings associated weaved field requires a transient setting to avoid metadata processing.


setCascadeAll

public void setCascadeAll(boolean value)
PUBLIC: Sets the cascading for all JPA operations.


setCascadeDetach

public void setCascadeDetach(boolean value)
PUBLIC: Sets the cascading for the JPA detach operation.


setCascadePersist

public void setCascadePersist(boolean value)
PUBLIC: Sets the cascading for the JPA CREATE operation.


setCascadeMerge

public void setCascadeMerge(boolean value)
PUBLIC: Sets the cascading for the JPA MERGE operation.


setCascadeRefresh

public void setCascadeRefresh(boolean value)
PUBLIC: Sets the cascading for the JPA REFRESH operation.


setCascadeRemove

public void setCascadeRemove(boolean value)
PUBLIC: Sets the cascading for the JPA REMOVE operation.


setCustomSelectionQuery

public void setCustomSelectionQuery(ReadQuery query)
PUBLIC: Relationship mappings creates a read query to read reference objects. If this default query needs to be customize then user can specify its own read query to do the reading of reference objects. One must instance of ReadQuery or subclasses of the ReadQuery.


setHasCustomSelectionQuery

protected void setHasCustomSelectionQuery(boolean bool)

setForceInitializationOfSelectionCriteria

public void setForceInitializationOfSelectionCriteria(boolean bool)
INTERNAL: A way of forcing the selection criteria to be rebuilt.


setIndirectionPolicy

public void setIndirectionPolicy(org.eclipse.persistence.internal.indirection.IndirectionPolicy indirectionPolicy)
ADVANCED: Set the indirection policy.


setIsPrivateOwned

public void setIsPrivateOwned(boolean isPrivateOwned)
PUBLIC: Set if the relationship is privately owned. A privately owned relationship means the target object is a dependent part of the source object and is not referenced by any other object and cannot exist on its own. Private ownership causes many operations to be cascaded across the relationship, including, deletion, insertion, refreshing, locking (when cascaded). It also ensures that private objects removed from collections are deleted and object added are inserted.


setRealAttributeValueInObject

public void setRealAttributeValueInObject(java.lang.Object object,
                                          java.lang.Object value)
                                   throws DescriptorException
INTERNAL: Set the value of the attribute mapped by this mapping, placing it inside a value holder if necessary. If the value holder is not instantiated then it is instantiated.

Overrides:
setRealAttributeValueInObject in class DatabaseMapping
Throws:
DescriptorException

setReferenceClass

public void setReferenceClass(java.lang.Class referenceClass)
PUBLIC: Set the referenced class.


setReferenceClassName

public void setReferenceClassName(java.lang.String referenceClassName)
INTERNAL: Used by MW.


setReferenceDescriptor

protected void setReferenceDescriptor(ClassDescriptor aDescriptor)
Set the referenceDescriptor. This is a descriptor which is associated with the reference class.


setRelationshipPartner

public void setRelationshipPartner(DatabaseMapping mapping)
INTERNAL: Sets the relationshipPartner mapping for this bi-directional mapping. If the relationshipPartner is null then this is a uni-directional mapping.


setRelationshipPartnerAttributeName

public void setRelationshipPartnerAttributeName(java.lang.String attributeName)
PUBLIC: Use this method to specify the relationship partner attribute name of a bidirectional Mapping. TopLink will use the attribute name to find the back pointer mapping to maintain referential integrity of the bi-directional mappings.


setRequiresTransientWeavedFields

public void setRequiresTransientWeavedFields(boolean requiresTransientWeavedFields)
Set this flag if this mappings associated weaved field requires a transient setting to avoid metadata processing.


setSelectionCriteria

public void setSelectionCriteria(Expression anExpression)
PUBLIC: Sets the selection criteria to be used as a where clause to read reference objects. This criteria is automatically generated by the TopLink if not explicitly specified by the user.


setSelectionQuery

protected void setSelectionQuery(ReadQuery aQuery)
Sets the query


setSelectionSQLString

public void setSelectionSQLString(java.lang.String sqlString)
PUBLIC: This is a property on the mapping which will allow custom SQL to be substituted for reading a reference object.


setSelectionCall

public void setSelectionCall(Call call)
PUBLIC: This is a property on the mapping which will allow custom call to be substituted for reading a reference object.


setShouldExtendPessimisticLockScope

public void setShouldExtendPessimisticLockScope(boolean shouldExtend)
ADVANCED: Indicates whether pessimistic lock of ObjectLevelReadQuery with isPessimisticLockScopeExtended set to true should be applied through this mapping beyond the tables mapped to the source object.


setTempSession

protected void setTempSession(org.eclipse.persistence.internal.sessions.AbstractSession session)

setUsesBatchReading

public void setUsesBatchReading(boolean usesBatchReading)
PUBLIC: Indicates whether the referenced object should always be batch read on read all queries. Batch reading will read all of the related objects in a single query when accessed from an originating read all. This should only be used if it is know that the related objects are always required with the source object, or indirection is not used.

See Also:
setBatchFetchType(BatchFetchType)

setUsesIndirection

public void setUsesIndirection(boolean usesIndirection)
PUBLIC: Indirection means that a ValueHolder will be put in-between the attribute and the real object. This allows for the reading of the target from the database to be delayed until accessed. This defaults to true and is strongly suggested as it give a huge performance gain.

See Also:
useBasicIndirection(), dontUseIndirection()

shouldExtendPessimisticLockScope

public boolean shouldExtendPessimisticLockScope()
INTERNAL: Indicates whether pessimistic lock of ObjectLevelReadQuery with isPessimisticLockScopeExtended set to true should be applied through this mapping beyond the tables mapped to the source object.


shouldExtendPessimisticLockScopeInSourceQuery

public boolean shouldExtendPessimisticLockScopeInSourceQuery()

shouldExtendPessimisticLockScopeInTargetQuery

public boolean shouldExtendPessimisticLockScopeInTargetQuery()

shouldExtendPessimisticLockScopeInDedicatedQuery

public boolean shouldExtendPessimisticLockScopeInDedicatedQuery()

shouldForceInitializationOfSelectionCriteria

protected boolean shouldForceInitializationOfSelectionCriteria()
INTERNAL:


shouldInitializeSelectionCriteria

protected boolean shouldInitializeSelectionCriteria()

shouldMergeCascadeParts

public boolean shouldMergeCascadeParts(org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
INTERNAL: Returns true if the merge should cascade to the mappings reference's parts.


shouldMergeCascadeReference

protected boolean shouldMergeCascadeReference(org.eclipse.persistence.internal.sessions.MergeManager mergeManager)
Returns true if the merge should cascade to the mappings reference.


shouldObjectModifyCascadeToParts

protected boolean shouldObjectModifyCascadeToParts(ObjectLevelModifyQuery query)
Returns true if any process leading to object modification should also affect its parts Usually used by write, insert, update and delete.


shouldUseBatchReading

public boolean shouldUseBatchReading()
PUBLIC: Indicates whether the referenced object should always be batch read on read all queries. Batch reading will read all of the related objects in a single query when accessed from an originating read all. This should only be used if it is know that the related objects are always required with the source object, or indirection is not used.


useBasicIndirection

public void useBasicIndirection()
PUBLIC: Indirection means that a ValueHolder will be put in-between the attribute and the real object. This allows for the reading of the target from the database to be delayed until accessed. This defaults to true and is strongly suggested as it give a huge performance gain.


useBatchReading

public void useBatchReading()
PUBLIC: Indicates whether the referenced object should always be batch read on read all queries. Batch reading will read all of the related objects in a single query when accessed from an originating read all. This should only be used if it is know that the related objects are always required with the source object, or indirection is not used.


useWeavedIndirection

public void useWeavedIndirection(java.lang.String getMethodName,
                                 java.lang.String setMethodName,
                                 boolean hasUsedMethodAccess)
INTERNAL: Configures the mapping to used weaved indirection. This requires that the toplink-agent be used to weave indirection into the class. This policy is only require for method access.

Parameters:
getMethodName - is the name of the original (or weaved in field access case) set method for the mapping.
setMethodName - is the name of the original (or weaved in field access case) set method for the mapping.
hasUsedMethodAccess - indicates whether method or field access was originally used.

useContainerIndirection

public void useContainerIndirection(java.lang.Class containerClass)
PUBLIC: Indirection means that a IndirectContainer (wrapping a ValueHolder) will be put in-between the attribute and the real object. This allows for an application specific class to be used which wraps the value holder. The purpose of this is that the domain objects will not require to import the ValueHolderInterface class. Refer also to transparent indirection for a transparent solution to indirection.


usesIndirection

public boolean usesIndirection()
PUBLIC: Indirection means that some sort of indirection object will be put in-between the attribute and the real object. This allows for the reading of the target from the database to be delayed until accessed. This defaults to true and is strongly suggested as it give a huge performance gain.


setJoinFetch

public void setJoinFetch(int joinFetch)
PUBLIC: Indicates whether the referenced object(s) should always be joined on read queries. Joining will join the two classes tables to read all of the data in a single query. This should only be used if it is know that the related objects are always required with the source object, or indirection is not used. A join-fetch can either use an INNER_JOIN or OUTER_JOIN, if the relationship may reference null or an empty collection an outer join should be used to avoid filtering the source objects from the queries. Join fetch can also be specified on the query, and it is normally more efficient to do so as some queries may not require the related objects. Typically batch reading is more efficient than join fetching and should be considered, especially for collection relationships.

See Also:
ObjectLevelReadQuery.addJoinedAttribute(String), ObjectLevelReadQuery.addBatchReadAttribute(String)

getJoinFetch

public int getJoinFetch()
PUBLIC: Return if this relationship should always be join fetched.


isJoinFetched

public boolean isJoinFetched()
PUBLIC: Return if this relationship should always be join fetched.


isInnerJoinFetched

public boolean isInnerJoinFetched()
PUBLIC: Return if this relationship should always be INNER join fetched.


isOuterJoinFetched

public boolean isOuterJoinFetched()
PUBLIC: Return if this relationship should always be OUTER join fetched.


useInnerJoinFetch

public void useInnerJoinFetch()
PUBLIC: Specify this relationship to always be join fetched using an INNER join.


useOuterJoinFetch

public void useOuterJoinFetch()
PUBLIC: Specify this relationship to always be join fetched using an OUTER join.


isCascadeOnDeleteSetOnDatabase

public boolean isCascadeOnDeleteSetOnDatabase()
ADVANCED: Return if delete cascading has been set on the database for the mapping's foreign key constraint.


setIsCascadeOnDeleteSetOnDatabase

public void setIsCascadeOnDeleteSetOnDatabase(boolean isCascadeOnDeleteSetOnDatabase)
ADVANCED: Set if delete cascading has been set on the database for the mapping's foreign key constraint. The behavior is dependent on the mapping.

OneToOne (target foreign key) - deletes target object (private owned)

OneToMany, AggregateCollection - deletes target objects (private owned)

ManyToMany - deletes from join table (only)

DirectCollection - delete from direct table


setIsCacheable

public void setIsCacheable(boolean cacheable)
Used to signal that this mapping references a protected/isolated entity and requires special merge/object building behaviour.

Overrides:
setIsCacheable in class DatabaseMapping

validateBeforeInitialization

public void validateBeforeInitialization(org.eclipse.persistence.internal.sessions.AbstractSession session)
                                  throws DescriptorException
INTERNAL: To validate mappings declaration

Overrides:
validateBeforeInitialization in class DatabaseMapping
Throws:
DescriptorException

valueFromPKList

public abstract java.lang.Object valueFromPKList(java.lang.Object[] pks,
                                                 org.eclipse.persistence.internal.sessions.AbstractSession session)
This method is used to load a relationship from a list of PKs. This list may be available if the relationship has been cached.


valueFromRow

public java.lang.Object valueFromRow(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                     org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                     ObjectBuildingQuery sourceQuery,
                                     org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey,
                                     org.eclipse.persistence.internal.sessions.AbstractSession executionSession,
                                     boolean isTargetProtected)
                              throws DatabaseException
INTERNAL: Return the value of the reference attribute or a value holder. Check whether the mapping's attribute should be optimized through batch and joining.

Overrides:
valueFromRow in class DatabaseMapping
Throws:
DatabaseException

shouldUseValueFromRowWithJoin

protected boolean shouldUseValueFromRowWithJoin(org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                                ObjectBuildingQuery sourceQuery)
INTERNAL: Indicates whether valueFromRow should call valueFromRowInternalWithJoin (true) or valueFromRowInternal (false)


valueFromRowInternalWithJoin

protected java.lang.Object valueFromRowInternalWithJoin(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                                        org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                                        ObjectBuildingQuery sourceQuery,
                                                        org.eclipse.persistence.internal.identitymaps.CacheKey parentCacheKey,
                                                        org.eclipse.persistence.internal.sessions.AbstractSession executionSession,
                                                        boolean isTargetProtected)
                                                 throws DatabaseException
INTERNAL: If the query used joining or partial attributes, build the target object directly. If isJoiningSupported()==true then this method must be overridden.

Throws:
DatabaseException

valueFromRowInternal

protected java.lang.Object valueFromRowInternal(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                                org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                                ObjectBuildingQuery sourceQuery,
                                                org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
                                         throws DatabaseException
INTERNAL: Return the value of the reference attribute or a value holder. Check whether the mapping's attribute should be optimized through batch and joining.

Throws:
DatabaseException

isExtendingPessimisticLockScope

protected boolean isExtendingPessimisticLockScope(ObjectBuildingQuery sourceQuery)
INTERNAL: Indicates whether the source query's pessimistic lock scope scope should be extended in the target query.


prepareHistoricalQuery

protected ReadQuery prepareHistoricalQuery(ReadQuery targetQuery,
                                           ObjectBuildingQuery sourceQuery,
                                           org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
INTERNAL: Allow for the mapping to perform any historical query additions. Return the new target query.


trimRowForJoin

public org.eclipse.persistence.internal.sessions.AbstractRecord trimRowForJoin(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                                                               org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                                                               org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
INTERNAL: Return a sub-partition of the row starting at the index for the mapping.


trimRowForJoin

public org.eclipse.persistence.internal.sessions.AbstractRecord trimRowForJoin(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                                                               java.lang.Object value,
                                                                               org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
INTERNAL: Return a sub-partition of the row starting at the index.


prepareNestedJoinQueryClone

protected ObjectLevelReadQuery prepareNestedJoinQueryClone(org.eclipse.persistence.internal.sessions.AbstractRecord row,
                                                           java.util.List dataResults,
                                                           org.eclipse.persistence.internal.queries.JoinedAttributeManager joinManager,
                                                           ObjectBuildingQuery sourceQuery,
                                                           org.eclipse.persistence.internal.sessions.AbstractSession executionSession)
INTERNAL: Prepare the clone of the nested query for joining. The nested query clones are stored on the execution (clone) joinManager to avoid cloning per row.


getBatchFetchType

public BatchFetchType getBatchFetchType()
PUBLIC: Return the type of batch fetching to use for all queries for this class if configured.


setBatchFetchType

public void setBatchFetchType(BatchFetchType batchFetchType)
PUBLIC: Set the type of batch fetching to use for all queries for this class.


EclipseLink 2.2.0, build 'v20110202-r8913' API Reference