Package org.eclipse.persistence.mappings

Class CollectionMapping

    • Field Detail

      • deleteAllQuery

        protected transient ModifyQuery deleteAllQuery
        Used for delete all in m-m, dc and delete all optimization in 1-m.

      • hasCustomDeleteAllQuery

        protected transient boolean hasCustomDeleteAllQuery

      • hasOrderBy

        protected boolean hasOrderBy

      • listOrderField

        protected DatabaseField listOrderField
        Field holds the order of elements in the list in the db, requires collection of type List, may be not null only in case isListOrderFieldSupported==true

      • isListOrderFieldSupported

        protected boolean isListOrderFieldSupported
        Indicates whether the mapping supports listOrderField, if it doesn't attempt to set listOrderField throws exception.

      • changeOrderTargetQuery

        protected transient DataModifyQuery changeOrderTargetQuery
        Query used when order of list members is changed. Used only if listOrderField!=null

      • orderCorrectionType

        protected OrderCorrectionType orderCorrectionType
        Specifies what should be done if the list of values read from listOrserField is invalid (there should be no nulls, no duplicates, no "holes").

      • mustDeleteReferenceObjectsOneByOne

        protected Boolean mustDeleteReferenceObjectsOneByOne
        Store if the mapping can batch delete reference objects.

      • isSynchronizeOnMerge

        protected static boolean isSynchronizeOnMerge
        Flag to indicate if collection needs to be synchronized instead of cloning during merge.

    • Constructor Detail

      • CollectionMapping

        public CollectionMapping()
        PUBLIC: Default constructor.

    • Method Detail

      • addAscendingOrdering

        public void addAscendingOrdering​(String queryKeyName)
        PUBLIC: Provide order support for queryKeyName in ascending order

      • addDescendingOrdering

        public void addDescendingOrdering​(String queryKeyName)
        PUBLIC: Provide order support for queryKeyName in descending order.

      • addOrderBy

        public void addOrderBy​(String queryKeyName,
                       boolean isDescending)
        PUBLIC: Provide order support for queryKeyName in descending or ascending order. Called from the jpa metadata processing of an order by value.

      • addAggregateOrderBy

        public void addAggregateOrderBy​(String aggregateName,
                                String queryKeyName,
                                boolean isDescending)
        PUBLIC: Provide order support for queryKeyName in ascending or descending order. Called from the jpa metadata processing of an order by value. The aggregate name may be chained through the dot notation.

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

      • copyElement

        protected Object copyElement​(Object original,
                             CopyGroup group)
        INTERNAL: Copies member's value

      • buildElementUnitOfWorkClone

        public Object buildElementUnitOfWorkClone​(Object element,
                                          Object parent,
                                          Integer refreshCascade,
                                          UnitOfWorkImpl unitOfWork,
                                          boolean isExisting,
                                          boolean isFromSharedCache)
        INTERNAL: Clone the element, if necessary.

      • buildElementClone

        public Object buildElementClone​(Object element,
                                Object parent,
                                CacheKey parentCacheKey,
                                Integer refreshCascade,
                                AbstractSession cloningSession,
                                boolean isExisting,
                                boolean isFromSharedCache)
        INTERNAL: Clone the element, if necessary.

      • buildExpression

        public Expression buildExpression​(Object queryObject,
                                  QueryByExamplePolicy policy,
                                  Expression expressionBuilder,
                                  Map processedObjects,
                                  AbstractSession session)
        INTERNAL: In case Query By Example is used, this method generates an expression from a attribute value pair. Since this is an Aggregate mapping, a recursive call is made to the buildExpressionFromExample method of ObjectBuilder.
        Overrides:
        buildExpression in class DatabaseMapping

      • buildReferencesPKList

        public Object[] buildReferencesPKList​(Object entity,
                                      Object attribute,
                                      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.
        Specified by:
        buildReferencesPKList in class ForeignReferenceMapping

      • collectQueryParameters

        public void collectQueryParameters​(Set<DatabaseField> record)
        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
        Specified by:
        collectQueryParameters in class ForeignReferenceMapping

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

      • compareCollectionsForChange

        public void compareCollectionsForChange​(Object oldCollection,
                                        Object newCollection,
                                        ChangeRecord changeRecord,
                                        AbstractSession session)
        INTERNAL: This method is used to calculate the differences between two collections.

      • compareListsAndWrite

        protected void compareListsAndWrite​(List previousList,
                                    List currentList,
                                    WriteObjectQuery query)
                             throws DatabaseException,
                                    OptimisticLockException
        INTERNAL: Old and new lists are compared and only the changes are written to the database. Currently there's no support for listOrderField in CollectionMapping in case there's no change sets, so this method currently never called (currently only overriding method in AggregateCollectionMapping is called). This method should be implemented to support listOrderField functionality without change sets.
        Throws:
        DatabaseException
        OptimisticLockException

      • compareLists

        protected boolean compareLists​(List firstList,
                               List secondList,
                               AbstractSession session,
                               boolean withPrivateOwned)
        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 ForeignReferenceMapping
        Parameters:
        classLoader -

      • extractKeyFromTargetRow

        protected Object extractKeyFromTargetRow​(AbstractRecord row,
                                         AbstractSession session)
        INTERNAL: Extract the source primary key value from the target 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.

      • getDeleteAllQuery

        protected ModifyQuery getDeleteAllQuery()

      • getOrderByQueryKeyExpressions

        public List<Expression> getOrderByQueryKeyExpressions()
        INTERNAL: Return the ordering query keys. Used for Workbench integration.

      • getSelectionQueryContainerPolicy

        protected ContainerPolicy getSelectionQueryContainerPolicy()
        INTERNAL: Get the container policy from the selection query for this mapping. This method is overridden in DirectCollectionMapping since its selection query is a DataReadQuery.

      • getListOrderField

        public DatabaseField getListOrderField()
        PUBLIC: Field holds the order of elements in the list in the db, requires collection of type List; may be not null only in case isListOrderFieldSupported==true.

      • getTargetPrimaryKeyFields

        public List<DatabaseField> getTargetPrimaryKeyFields()
        INTERNAL: Returns list of primary key fields from the reference descriptor.

      • getOrderCorrectionType

        public OrderCorrectionType getOrderCorrectionType()
        PUBLIC: Specifies what should be done if the list of values read from listOrserField is invalid (there should be no nulls, no duplicates, no "holes").

      • hasCustomDeleteAllQuery

        protected boolean hasCustomDeleteAllQuery()

      • hasOrderBy

        public boolean hasOrderBy()
        INTERNAL: Return true if ascending or descending ordering has been set on this mapping via the @OrderBy annotation.

      • initializeListOrderField

        protected void initializeListOrderField​(AbstractSession session)
        INTERNAL: Initializes listOrderField. Precondition: listOrderField != null.

      • initializeListOrderFieldTable

        protected void initializeListOrderFieldTable​(AbstractSession session)
        INTERNAL: Initializes listOrderField's table, does nothing by default. Precondition: listOrderField != null.

      • buildListOrderField

        protected void buildListOrderField()
        INTERNAL: Verifies listOrderField's table, if none found sets the default one. Precondition: listOrderField != null.

      • shouldUseLazyInstantiationForIndirectCollection

        public Boolean shouldUseLazyInstantiationForIndirectCollection()
        ADVANCED: This method should only be called after this mapping's indirection policy has been set IndirectList and IndirectSet can be configured not to instantiate the list from the database when you add and remove from them. IndirectList defaults to this behavior. When Set to true, the collection associated with this TransparentIndirection will be setup so as not to instantiate for adds and removes. The weakness of this setting for an IndirectSet is that when the set is not instantiated, if a duplicate element is added, it will not be detected until commit time.

      • shouldUseListOrderFieldTableExpression

        public boolean shouldUseListOrderFieldTableExpression()
        INTERNAL: Indicates whether getListOrderFieldExpression method should create field expression based on table expression.

      • initializeChangeOrderTargetQuery

        protected void initializeChangeOrderTargetQuery​(AbstractSession session)
        INTERNAL: Initialize changeOrderTargetQuery.

      • isCollectionMapping

        public boolean isCollectionMapping()
        INTERNAL: Return whether this mapping is a Collection type.
        Overrides:
        isCollectionMapping in class DatabaseMapping

      • isMapKeyObjectRelationship

        public boolean isMapKeyObjectRelationship()
        INTERNAL: Return if this mapping has a mapped key that uses a OneToOne (object).

      • isAttributeValueInstantiatedOrChanged

        public boolean isAttributeValueInstantiatedOrChanged​(Object object)
        INTERNAL: The referenced object is checked if it is instantiated or not, also check if it has been changed (as indirect collections avoid instantiation on add/remove.

      • iterateOnElement

        public void iterateOnElement​(DescriptorIterator iterator,
                             Object element)
        INTERNAL: Iterate on the specified element.

      • mustDeleteReferenceObjectsOneByOne

        public boolean mustDeleteReferenceObjectsOneByOne()
        ADVANCED: Return whether the reference objects must be deleted one by one, as opposed to with a single DELETE statement.

      • mergeIntoObject

        public void mergeIntoObject​(Object target,
                            boolean isTargetUnInitialized,
                            Object source,
                            MergeManager mergeManager,
                            AbstractSession targetSession)
        INTERNAL: Merge changes from the source to the target object. This merge is only called when a changeSet for the target does not exist or the target is uninitialized
        Specified by:
        mergeIntoObject in class DatabaseMapping

      • objectOrderChangedDuringUpdate

        protected void objectOrderChangedDuringUpdate​(WriteObjectQuery query,
                                              Object orderChangedObject,
                                              int orderIndex)

      • getAdditionalFieldsBaseExpression

        protected Expression getAdditionalFieldsBaseExpression​(ReadQuery query)
        INTERNAL: Return the base expression to use for adding fields to the query. Normally this is the query's builder, but may be the join table for m-m.

      • prepareTranslationRow

        protected void prepareTranslationRow​(AbstractRecord translationRow,
                                     Object object,
                                     ClassDescriptor descriptor,
                                     AbstractSession session)
        INTERNAL: copies the non primary key information into the row currently used only in ManyToMany

      • setContainerPolicy

        public void setContainerPolicy​(ContainerPolicy containerPolicy)
        ADVANCED: Configure the mapping to use a container policy. The policy manages the access to the collection.
        Specified by:
        setContainerPolicy in interface ContainerMapping

      • setCustomDeleteAllQuery

        public void setCustomDeleteAllQuery​(ModifyQuery query)
        PUBLIC: The default delete all query for mapping can be overridden by specifying the new query. This query is responsible for doing the deletion required by the mapping, such as deletion of all the rows from join table for M-M, or optimized delete all of target objects for 1-M.

      • setDeleteAllQuery

        protected void setDeleteAllQuery​(ModifyQuery query)

      • setDeleteAllSQLString

        public void setDeleteAllSQLString​(String sqlString)
        PUBLIC: Set the receiver's delete all 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 of all the rows from join table for M-M, or optimized delete all of target objects for 1-M. Example, 'delete from PROJ_EMP where EMP_ID = #EMP_ID'.

      • setDeleteAllCall

        public void setDeleteAllCall​(Call call)
        PUBLIC: Set the receiver's delete all call. 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. This call is responsible for doing the deletion required by the mapping, such as deletion of all the rows from join table for M-M, or optimized delete all of target objects for 1-M. Example, 'new SQLCall("delete from PROJ_EMP where EMP_ID = #EMP_ID")'.

      • setHasCustomDeleteAllQuery

        protected void setHasCustomDeleteAllQuery​(boolean bool)

      • setSelectionQueryContainerPolicy

        protected void setSelectionQueryContainerPolicy​(ContainerPolicy containerPolicy)
        INTERNAL: Set the container policy on the selection query for this mapping. This method is overridden in DirectCollectionMapping since its selection query is a DataReadQuery.

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

      • setUseLazyInstantiationForIndirectCollection

        public void setUseLazyInstantiationForIndirectCollection​(Boolean useLazyInstantiation)
        ADVANCED: Calling this method will only affect behavior of mappings using transparent indirection This method should only be called after this mapping's indirection policy has been set IndirectList and IndirectSet can be configured not to instantiate the list from the database when you add and remove from them. IndirectList defaults to this behavior. When Set to true, the collection associated with this TransparentIndirection will be setup so as not to instantiate for adds and removes. The weakness of this setting for an IndirectSet is that when the set is not instantiated, if a duplicate element is added, it will not be detected until commit time.

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

      • isListOrderFieldSupported

        public boolean isListOrderFieldSupported()
        PUBLIC: indicates whether the mapping supports listOrderField, if it doesn't attempt to set listOrderField throws exception.

      • setListOrderField

        public void setListOrderField​(DatabaseField field)
        PUBLIC: Field holds the order of elements in the list in the db, requires collection of type List. Throws exception if the mapping doesn't support listOrderField.

      • setListOrderFieldName

        public void setListOrderFieldName​(String fieldName)
        PUBLIC: Field holds the order of elements in the list in the db, requires collection of type List. Throws exception if the mapping doesn't support listOrderField.

      • setMustDeleteReferenceObjectsOneByOne

        public void setMustDeleteReferenceObjectsOneByOne​(Boolean deleteOneByOne)
        ADVANCED:: Return whether the reference objects must be deleted one by one, as opposed to with a single DELETE statement. Note: Calling this method disables an optimization of the delete behavior

      • setOrderCorrectionType

        public void setOrderCorrectionType​(OrderCorrectionType orderCorrectionType)
        PUBLIC: Specifies what should be done if the list of values read from listOrserField is invalid (there should be no nulls, no duplicates, no "holes").

      • useCollectionClass

        public void useCollectionClass​(Class concreteClass)
        PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects. Note that if listOrderField is used then setListOrderField method should be called before this method.

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

        Specified by:
        useCollectionClass in interface ContainerMapping

      • useSortedSetClass

        public void useSortedSetClass​(Class concreteClass,
                              Comparator comparator)
        PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.

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

      • useSortedSetClassName

        public void useSortedSetClassName​(String className)
        INTERNAL: Configure the mapping to use an instance of the specified container class name to hold the target objects. This method is used by MW.

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

      • useSortedSetClassName

        public void useSortedSetClassName​(String className,
                                  String comparatorClassName)
        INTERNAL: Configure the mapping to use an instance of the specified container class name to hold the target objects. This method is used by MW.

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

      • useCollectionClassName

        public void useCollectionClassName​(String concreteClassName)
        INTERNAL: Used to set the collection class by name. This is required when building from metadata to allow the correct class loader to be used.
        Specified by:
        useCollectionClassName in interface ContainerMapping

      • useListClassName

        public void useListClassName​(String concreteClassName)
        INTERNAL: Used to set the collection class by name. This is required when building from metadata to allow the correct class loader to be used.
        Specified by:
        useListClassName in interface ContainerMapping

      • useMapClass

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

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

        To facilitate resolving the method, the mapping's referenceClass must set before calling this method.

        Specified by:
        useMapClass in interface ContainerMapping

      • useMapClass

        public void useMapClass​(Class concreteClass)
        PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects. The key used to index a value in the Map is an instance of the composite primary key class.

        To facilitate resolving the primary key class, the mapping's referenceClass must set before calling this method.

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

      • useTransparentCollection

        public void useTransparentCollection()
        PUBLIC: If transparent indirection is used, a special collection will be placed in the source object's attribute. Fetching of the contents of the collection from the database will be delayed until absolutely necessary. (Any message sent to the collection will cause the contents to be faulted in from the database.) This can result in rather significant performance gains, without having to change the source object's attribute from Collection (or List or Vector) to ValueHolderInterface.

      • useTransparentSet

        public void useTransparentSet()
        PUBLIC: If transparent indirection is used, a special collection will be placed in the source object's attribute. Fetching of the contents of the collection from the database will be delayed until absolutely necessary. (Any message sent to the collection will cause the contents to be faulted in from the database.) This can result in rather significant performance gains, without having to change the source object's attribute from Set to ValueHolderInterface.

      • useTransparentList

        public void useTransparentList()
        PUBLIC: If transparent indirection is used, a special collection will be placed in the source object's attribute. Fetching of the contents of the collection from the database will be delayed until absolutely necessary. (Any message sent to the collection will cause the contents to be faulted in from the database.) This can result in rather significant performance gains, without having to change the source object's attribute from List to ValueHolderInterface.

      • useTransparentMap

        public void useTransparentMap​(String methodName)
        PUBLIC: If transparent indirection is used, a special map will be placed in the source object's attribute. Fetching of the contents of the map from the database will be delayed until absolutely necessary. (Any message sent to the map will cause the contents to be faulted in from the database.) This can result in rather significant performance gains, without having to change the source object's attribute from Map (or Map or Hashtable) to ValueHolderInterface.

        The key used in the Map is the value returned by a call to the zero parameter method named methodName. The method should be a zero argument method implemented (or inherited) by the value to be inserted into the Map.