Package org.eclipse.persistence.mappings

Class DirectCollectionMapping

    • Field Detail

      • valueConverter

        protected Converter valueConverter
        Allows user defined conversion between the object value and the database value.

      • valueConverterClassName

        protected String valueConverterClassName

      • referenceTable

        protected DatabaseTable referenceTable
        Stores the reference table

      • directField

        protected DatabaseField directField
        The direct field name is converted and stored

      • insertQuery

        protected DataModifyQuery insertQuery
        Used for insertion for m-m and dc, not used in 1-m.

      • changeSetDeleteQuery

        protected ModifyQuery changeSetDeleteQuery
        Used for deletion when ChangeSets are used

      • changeSetDeleteNullQuery

        protected transient ModifyQuery changeSetDeleteNullQuery

      • hasCustomDeleteQuery

        protected boolean hasCustomDeleteQuery

      • hasCustomInsertQuery

        protected boolean hasCustomInsertQuery

      • deleteAtIndexQuery

        protected ModifyQuery deleteAtIndexQuery
        Used (only in case listOrderField != null) to delete object with particular orderFieldValue

      • updateAtIndexQuery

        protected ModifyQuery updateAtIndexQuery
        Used (only in case listOrderField != null) to update orderFieldValue of object with particular orderFieldValue

      • hasCustomDeleteAtIndexQuery

        protected boolean hasCustomDeleteAtIndexQuery

      • hasCustomUpdateAtIndexQuery

        protected boolean hasCustomUpdateAtIndexQuery

      • attributeClassification

        protected transient Class attributeClassification
        Since:
        Java Persistence API 2.0 Referenced by MapAttributeImpl to pick up the BasicMap value parameter type To specify the conversion type

      • attributeClassificationName

        protected String attributeClassificationName

    • Constructor Detail

      • DirectCollectionMapping

        public DirectCollectionMapping()
        PUBLIC: Default constructor.

    • Method Detail

      • addAscendingOrdering

        public void addAscendingOrdering()
        PUBLIC: Provide ascending order support for this direct collection mapping.

      • addDescendingOrdering

        public void addDescendingOrdering()
        PUBLIC: Provide descending order support for this direct collection mapping.

      • addOrdering

        public void addOrdering​(Expression expression)
        ADVANCED: Used this method to add custom ordering expressions when fetching the collection. This could be things like expressions using a functions like UPPER or NULLS LAST etc.

      • isRelationalMapping

        public boolean isRelationalMapping()
        Description copied from class: DatabaseMapping
        INTERNAL: All relational mappings should implement this method to return true.
        Overrides:
        isRelationalMapping in class DatabaseMapping

      • getValueConverter

        public Converter getValueConverter()
        PUBLIC: Return the converter on the mapping. A converter can be used to convert between the direct collection's object value and database value.

      • setValueConverter

        public void setValueConverter​(Converter valueConverter)
        PUBLIC: Set the converter on the mapping. A converter can be used to convert between the direct collection's object value and database value.

      • setValueConverterClassName

        public void setValueConverterClassName​(String valueConverterClassName)
        PUBLIC: Set the converter class name on the mapping. Initialized in convertClassNamesToClasses. A converter can be used to convert between the direct collection's object value and database value.

      • addReferenceKeyField

        public void addReferenceKeyField​(DatabaseField referenceForeignKeyField,
                                 DatabaseField sourcePrimaryKeyField)
        PUBLIC: Add the reference key field. This is used for composite reference keys. This is the foreign key field in the direct table referencing the primary key of the source object. Both the reference field and the source field that it references must be provided.

      • addReferenceKeyFieldName

        public void addReferenceKeyFieldName​(String referenceForeignKeyFieldName,
                                     String sourcePrimaryKeyFieldName)
        PUBLIC: Add the name of the reference key field. This is used for composite reference keys. This is the foreign key field in the direct table referencing the primary key of the source object. Both the reference field name and the name of the source field that it references must be provided.

      • buildCopy

        public void buildCopy​(Object copy,
                      Object original,
                      CopyGroup group)
        INTERNAL: Copy of the attribute of the object. This is NOT used for unit of work but for templatizing an object.
        Overrides:
        buildCopy in class CollectionMapping

      • buildElementClone

        public Object buildElementClone​(Object element,
                                Object parent,
                                CacheKey parentCacheKey,
                                Integer refreshCascade,
                                AbstractSession cloningSession,
                                boolean isExisting,
                                boolean isFromSharedCache)
        INTERNAL: Clone the element, if necessary. DirectCollections hold on to objects that do not have Descriptors (e.g. int, String). These objects do not need to be cloned, unless they use a converter - they are immutable.
        Overrides:
        buildElementClone in class CollectionMapping

      • buildListOrderField

        protected void buildListOrderField()
        INTERNAL: Verifies listOrderField's table: it must be reference table. Precondition: listOrderField != null.
        Overrides:
        buildListOrderField in class CollectionMapping

      • compareListsForChange

        public void compareListsForChange​(List oldList,
                                  List newList,
                                  ChangeRecord changeRecord,
                                  AbstractSession session)
        INTERNAL: This method is used to calculate the differences between two Lists.

      • compareLists

        protected boolean compareLists​(List firstList,
                               List secondList)
        Compare two lists. For equality the order of the elements should be the same. Used only if listOrderField != null

      • convertClassNamesToClasses

        public void convertClassNamesToClasses​(ClassLoader classLoader)
        INTERNAL: Convert all the class-name-based settings in this mapping to actual class-based settings This method is implemented by subclasses as necessary.
        Overrides:
        convertClassNamesToClasses in class CollectionMapping
        Parameters:
        classLoader -

      • fixRealObjectReferences

        public void fixRealObjectReferences​(Object object,
                                    Map objectInformation,
                                    Map processedObjects,
                                    ObjectLevelReadQuery query,
                                    DistributedSession session)
        INTERNAL: At this point, we realize we don't have indirection; so we need to replace the reference object(s) with the corresponding object(s) from the remote session. The reference objects for a DirectCollectionMapping are primitives, so they do not need to be replaced.
        Overrides:
        fixRealObjectReferences in class CollectionMapping

      • getAttributeClassification

        public Class getAttributeClassification()
        PUBLIC: Some databases do not properly support all of the base data types. For these databases, the base data type must be explicitly specified in the mapping to tell EclipseLink to force the instance variable value to that data type.
        Overrides:
        getAttributeClassification in class DatabaseMapping
        Since:
        Java Persistence API 2.0

      • getAttributeClassificationName

        public String getAttributeClassificationName()
        INTERNAL: Return the class name of the attribute type. This is only used by the MW.
        Since:
        Java Persistence API 2.0

      • getDeleteQuery

        protected ModifyQuery getDeleteQuery()

      • getDeleteNullQuery

        protected ModifyQuery getDeleteNullQuery()

      • getDeleteAtIndexQuery

        protected ModifyQuery getDeleteAtIndexQuery()

      • getUpdateAtIndexQuery

        protected ModifyQuery getUpdateAtIndexQuery()

      • getSelectFields

        public Vector getSelectFields()
        INTERNAL: Returns the set of fields that should be selected to build this mapping's value(s). This is used by expressions to determine which fields to include in the select clause for non-object expressions.
        Overrides:
        getSelectFields in class DatabaseMapping

      • getSelectTables

        public Vector getSelectTables()
        INTERNAL: Returns the table(s) that should be selected to build this mapping's value(s). This is used by expressions to determine which tables to include in the from clause for non-object expressions.
        Overrides:
        getSelectTables in class DatabaseMapping

      • getDirectField

        public DatabaseField getDirectField()
        INTERNAL: Return the direct field. This is the field in the direct table to store the values.

      • getDirectFieldName

        public String getDirectFieldName()
        PUBLIC: Returns the name of the field name in the reference table.

      • getOrderByExpressions

        public List<Expression> getOrderByExpressions()
        PUBLIC: Return the order by expression.

      • getHistoryPolicy

        public HistoryPolicy getHistoryPolicy()
        PUBLIC: Allow history support on the reference table.

      • getReferenceKeyFieldNames

        public Vector getReferenceKeyFieldNames()
        INTERNAL: Return the reference key field names associated with the mapping. These are in-order with the sourceKeyFieldNames.

      • getReferenceKeyFields

        public Vector<DatabaseField> getReferenceKeyFields()
        INTERNAL: Return the reference key fields.

      • getReferenceTable

        public DatabaseTable getReferenceTable()
        INTERNAL: Return the direct table. This is the table to store the values.

      • getReferenceTableName

        public String getReferenceTableName()
        PUBLIC: Returns the name of the reference table

      • getReferenceTableQualifiedName

        public String getReferenceTableQualifiedName()
        PUBLIC: Returns the qualified name of the reference table.

      • 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. DirectCollectionMapping can not be part of a bi-directional mapping
        Overrides:
        getRelationshipPartner in class ForeignReferenceMapping

      • getSourceKeyFieldNames

        public Vector getSourceKeyFieldNames()
        PUBLIC: Return the source key field names associated with the mapping. These are in-order with the referenceKeyFieldNames.

      • getSourceKeyFields

        public Vector<DatabaseField> getSourceKeyFields()
        INTERNAL: Return the source key fields.

      • hasCustomDeleteQuery

        protected boolean hasCustomDeleteQuery()

      • hasCustomInsertQuery

        protected boolean hasCustomInsertQuery()

      • hasCustomDeleteAtIndexQuery

        protected boolean hasCustomDeleteAtIndexQuery()

      • hasCustomUpdateAtIndexQuery

        protected boolean hasCustomUpdateAtIndexQuery()

      • hasNestedIdentityReference

        public boolean hasNestedIdentityReference()
        INTERNAL: Indicates whether the mapping (or at least one of its nested mappings, at any nested depth) references an entity. To return true the mapping (or nested mapping) should be ForeignReferenceMapping with non-null and non-aggregate reference descriptor.
        Overrides:
        hasNestedIdentityReference in class ForeignReferenceMapping

      • initializeDeleteAllQuery

        protected void initializeDeleteAllQuery​(AbstractSession session)
        Initialize delete all query. This query is used to delete the collection of objects from the reference table.

      • initializeDeleteQuery

        protected void initializeDeleteQuery​(AbstractSession session)

      • initializeDeleteNullQuery

        protected void initializeDeleteNullQuery​(AbstractSession session)

      • initializeDeleteAtIndexQuery

        protected void initializeDeleteAtIndexQuery​(AbstractSession session)

      • initializeUpdateAtIndexQuery

        protected void initializeUpdateAtIndexQuery​(AbstractSession session)

      • shouldUseListOrderFieldTableExpression

        public boolean shouldUseListOrderFieldTableExpression()
        INTERNAL: Indicates whether getListOrderFieldExpression method should create field expression on table expression.
        Overrides:
        shouldUseListOrderFieldTableExpression in class CollectionMapping

      • initializeInsertQuery

        protected void initializeInsertQuery​(AbstractSession session)
        Initialize insert query. This query is used to insert the collection of objects into the reference table.

      • initializeSelectionCriteria

        protected void initializeSelectionCriteria​(AbstractSession session)

      • initializeSelectionStatement

        protected void initializeSelectionStatement​(AbstractSession session)

      • initializeSourceKeys

        protected void initializeSourceKeys​(AbstractSession session)
        The source keys are initialized

      • initializeSourceKeysWithDefaults

        protected void initializeSourceKeysWithDefaults​(AbstractSession session)
        INTERNAL: If a user does not specify the source key then the primary keys of the source table are used.

      • isKeyForSourceSpecified

        protected boolean isKeyForSourceSpecified()
        INTERNAL: Checks if source and target keys are mentioned by the user or not.

      • isLockableMapping

        public boolean isLockableMapping()
        INTERNAL: Return whether this mapping should be traversed when we are locking
        Overrides:
        isLockableMapping in class ForeignReferenceMapping
        Returns:

      • mergeAddRemoveChanges

        protected void mergeAddRemoveChanges​(Object valueOfTarget,
                                     Object delegateTarget,
                                     DirectCollectionChangeRecord changeRecord,
                                     MergeManager mergeManager,
                                     AbstractSession session)
        INTERNAL: Merge changes by adding and removing from the change record to the target object, and its delegate object if instance of IndirectCollection. It will also reorder the collection if required.

      • getFieldValue

        public Object getFieldValue​(Object attributeValue,
                            AbstractSession session)
        INTERNAL: Convert the attribute value to a field value. Process any converter if defined.

      • getObjectValue

        public Object getObjectValue​(Object fieldValue,
                             AbstractSession session)
        INTERNAL: Convert the field value to an attribute value. Process any converter if defined.

      • initOrRebuildSelectQuery

        protected void initOrRebuildSelectQuery()
        INTERNAL: Used by DirectMapMapping to rebuild select query.

      • 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 ForeignReferenceMapping

      • setAttributeClassification

        public void setAttributeClassification​(Class attributeClassification)
        PUBLIC: Some databases do not properly support all of the base data types. For these databases, the base data type must be explicitly specified in the mapping to tell EclipseLink to force the instance variable value to that data type.
        Since:
        Java Persistence API 2.0 Migrated from AbstractDirectMapping

      • setAttributeClassificationName

        public void setAttributeClassificationName​(String attributeClassificationName)
        INTERNAL: Set the name of the class for MW usage.
        Since:
        Java Persistence API 2.0 Migrated from AbstractDirectMapping

      • setDeleteQuery

        protected void setDeleteQuery​(ModifyQuery query)

      • setDeleteSQLString

        public void setDeleteSQLString​(String sqlString)
        PUBLIC: Set the receiver's delete SQL string. This allows the user to override the SQL generated by TopLink, with there own SQL or procedure call. The arguments are translated from the fields of the source row, through replacing the field names marked by '#' with the values for those fields. This SQL is responsible for doing the deletion required by the mapping, such as deletion from join table for M-M. Example, 'delete from RESPONS where EMP_ID = #EMP_ID and DESCRIP = #DESCRIP'.

      • setCustomDeleteQuery

        public void setCustomDeleteQuery​(ModifyQuery query)
        PUBLIC: The default delete query for this mapping can be overridden by specifying the new query. This query is responsible for doing the deletion required by the mapping, such as deletion from join table for M-M. The query should delete a specific row from the DirectCollectionTable bases on the DirectField.

      • setCustomDeleteAtIndexQuery

        public void setCustomDeleteAtIndexQuery​(ModifyQuery query)
        PUBLIC: The default delete by index query for this mapping can be overridden by specifying the new query. This query used (only in case listOrderField != null) to delete object with particular orderFieldValue.

      • setCustomInsertQuery

        public void setCustomInsertQuery​(DataModifyQuery query)
        PUBLIC: The default insert query for mapping can be overridden by specifying the new query. This query inserts the row into the direct table.

      • setCustomUpdateAtIndexQuery

        public void setCustomUpdateAtIndexQuery​(ModifyQuery query)
        PUBLIC: The default delete by index query for this mapping can be overridden by specifying the new query. This query used (only in case listOrderField != null) to update orderFieldValue of object with particular orderFieldValue.

      • setDirectField

        public void setDirectField​(DatabaseField field)
        PUBLIC: Set the direct field in the reference table. This is the field that the primitive data value is stored in.

      • setDirectFieldClassification

        public void setDirectFieldClassification​(Class fieldType)
        ADVANCED: Set the class type of the field value. This can be used if field value differs from the object value, has specific typing requirements such as usage of java.sql.Blob or NChar. This must be called after the field name has been set.

      • setDirectFieldClassificationName

        public void setDirectFieldClassificationName​(String className)
        ADVANCED: Set the class type of the field value. This can be used if field value differs from the object value, has specific typing requirements such as usage of java.sql.Blob or NChar. This must be called after the field name has been set.

      • setDirectFieldName

        public void setDirectFieldName​(String fieldName)
        PUBLIC: Set the direct field name in the reference table. This is the field that the primitive data value is stored in.

      • setHasCustomDeleteQuery

        protected void setHasCustomDeleteQuery​(boolean bool)

      • setHasCustomInsertQuery

        protected void setHasCustomInsertQuery​(boolean bool)

      • setInsertQuery

        protected void setInsertQuery​(DataModifyQuery insertQuery)

      • setInsertSQLString

        public void setInsertSQLString​(String sqlString)
        PUBLIC: Set the receiver's insert SQL string. This allows the user to override the SQL generated by TopLink, with there own SQL or procedure call. The arguments are translated from the fields of the source row, through replacing the field names marked by '#' with the values for those fields. This is used to insert an entry into the direct table.

        Example, 'insert into RESPONS (EMP_ID, RES_DESC) values (#EMP_ID, #RES_DESC)'.

      • setReferenceKeyFieldName

        public void setReferenceKeyFieldName​(String fieldName)
        PUBLIC: Set the name of the reference key field. This is the foreign key field in the direct table referencing the primary key of the source object. This method is used if the reference key consists of only a single field.

      • setReferenceKeyFieldNames

        public void setReferenceKeyFieldNames​(Vector fieldNames)
        INTERNAL: Set the reference key field names associated with the mapping. These must be in-order with the sourceKeyFieldNames.

      • setReferenceKeyFields

        public void setReferenceKeyFields​(Vector<DatabaseField> aVector)
        INTERNAL: Set the reference fields.

      • setReferenceTable

        public void setReferenceTable​(DatabaseTable table)
        INTERNAL: Set the reference table.

      • 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.
        Overrides:
        setSelectionCriteria in class ForeignReferenceMapping

      • setReferenceTableName

        public void setReferenceTableName​(String tableName)
        PUBLIC: Set the reference table name.

      • setHistoryPolicy

        public void setHistoryPolicy​(HistoryPolicy policy)
        PUBLIC: Support history on the reference table.

      • setSessionName

        public void setSessionName​(String name)
        PUBLIC: Set the name of the session to execute the mapping's queries under. This can be used by the session broker to override the default session to be used for the target class.
        Overrides:
        setSessionName in class CollectionMapping

      • setSourceKeyFieldNames

        public void setSourceKeyFieldNames​(Vector fieldNames)
        INTERNAL: Set the source key field names associated with the mapping. These must be in-order with the referenceKeyFieldNames.

      • setSourceKeyFields

        public void setSourceKeyFields​(Vector<DatabaseField> sourceKeyFields)
        INTERNAL: Set the source fields.

      • collectQueryParameters

        public void collectQueryParameters​(Set<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 CollectionMapping

      • calculateDeferredChanges

        public void calculateDeferredChanges​(ChangeRecord changeRecord,
                                     AbstractSession session)
        INTERNAL: Used by AttributeLevelChangeTracking to update a changeRecord with calculated changes as apposed to detected changes. If an attribute can not be change tracked it's changes can be detected through this process.
        Overrides:
        calculateDeferredChanges in class CollectionMapping

      • simpleAddToCollectionChangeRecord

        protected void simpleAddToCollectionChangeRecord​(Object objectToAdd,
                                                 Integer index,
                                                 boolean isSet,
                                                 ObjectChangeSet changeSet,
                                                 AbstractSession session,
                                                 boolean isChangeApplied)

      • simpleRemoveFromCollectionChangeRecord

        protected void simpleRemoveFromCollectionChangeRecord​(Object objectToRemove,
                                                      Integer index,
                                                      boolean isSet,
                                                      ObjectChangeSet changeSet,
                                                      AbstractSession session,
                                                      boolean isChangeApplied)

      • updateChangeRecord

        public void updateChangeRecord​(Object clone,
                               Object newValue,
                               Object oldValue,
                               ObjectChangeSet objectChangeSet,
                               UnitOfWorkImpl uow)
        INTERNAL: Either create a new change record or update with the new value. This is used by attribute change tracking. Specifically in a collection mapping this will be called when the customer Set a new collection. In this case we will need to mark the change record with the new and the old versions of the collection. And mark the ObjectChangeSet with the attribute name then when the changes are calculated force a compare on the collections to determine changes.
        Overrides:
        updateChangeRecord in class CollectionMapping

      • isCandidateForPrivateOwnedRemoval

        public boolean isCandidateForPrivateOwnedRemoval()
        INTERNAL: DirectCollectionMapping contents should not be considered for addition to the UnitOfWork private owned objects list for removal.
        Overrides:
        isCandidateForPrivateOwnedRemoval in class DatabaseMapping

      • isCascadedLockingSupported

        public boolean isCascadedLockingSupported()
        INTERNAL Return true if this mapping supports cascaded version optimistic locking.
        Overrides:
        isCascadedLockingSupported in class DatabaseMapping