Interface CollectionPersister

All Superinterfaces:

FilterRestrictable, Restrictable, WhereRestrictable

All Known Implementing Classes:

AbstractCollectionPersister, BasicCollectionPersister, OneToManyPersister

@SPI({USE,IMPLEMENT})
public interface CollectionPersister
extends Restrictable

A strategy for persisting a mapped collection role. A CollectionPersister orchestrates rendering of SQL statements corresponding to basic lifecycle events, including insert, update, and delete statements, and their execution via JDBC.

Concrete implementations of this interface handle one-to-many and many-to-many association cardinalities, and to a certain extent abstract the details of those mappings from collaborators.

Note that an instance of PersistentCollection may change roles. This object implements persistence of a collection instance while the instance is referenced in a particular role.

This interface defines a contract between the persistence strategy and the actual persistent collection framework and session. It does not define operations that are required for querying collections, nor for loading by outer join. Implementations are highly coupled to the PersistentCollection hierarchy, since double dispatch is used to load and update collection elements.

Unless a custom PersisterFactory is used, it is expected that implementations of CollectionPersister define a constructor accepting the following arguments:

1. Collection - The metadata about the collection to be handled by the persister,
2. CollectionDataAccess - the second level caching strategy for this collection, and
3. RuntimeModelCreationContext - access to additional information useful while constructing the persister.

See Also:

• PersistentCollection
• PluralAttributeMapping

Method Summary

Modifier and Type	Method	Description
void	applyBaseManyToManyRestrictions(Consumer<Predicate> predicateConsumer, TableGroup tableGroup, boolean useQualifier, Map<String,Filter> enabledFilters, Set<String> treatAsDeclarations, SqlAstCreationState creationState)
void	decompose(org.hibernate.action.queue.internal.PreparedCollectionMutation mutation, int ordinalBase, SharedSessionContractImplementor session, DecompositionContext decompositionContext, Consumer<FlushOperation> operationConsumer)	Decomposes a prepared collection mutation into graph-native operations.
void	deleteRows(PersistentCollection<?> collection, Object key, SharedSessionContractImplementor session)	Delete the persistent state of any elements that were removed from the collection
boolean	elementExists(Object key, Object element, SharedSessionContractImplementor session)
default PluralAttributeMapping	getAttributeMapping()
default int	getBatchSize()
CollectionDataAccess	getCacheAccessStrategy()	Access to the collection's cache region
CacheEntryStructure	getCacheEntryStructure()	Get the structure used to store data into the collection's cache region
String[]	getCollectionPropertyColumnAliases(String propertyName, String string)
CollectionSemantics<?,?>	getCollectionSemantics()
String[]	getCollectionSpaces()	Get the "space" that holds the persistent state
CollectionType	getCollectionType()	Deprecated, for removal: This API element is subject to removal in a future version. Hibernate is moving away from Type.
Object	getElementByIndex(Object key, Object index, SharedSessionContractImplementor session, Object owner)
Class<?>	getElementClass()	Return the element class of an array, or null otherwise
String[]	getElementColumnAliases(String suffix)	Deprecated, for removal: This API element is subject to removal in a future version. Read-by-position makes this irrelevant.
boolean[]	getElementColumnIsSettable()
EntityPersister	getElementPersister()	Get the persister of the element class, if this is a collection of entities (optional operation).
Type	getElementType()	Deprecated, for removal: This API element is subject to removal in a future version. Hibernate is moving away from Type.
SessionFactoryImplementor	getFactory()
BeforeExecutionGenerator	getGenerator()	Get the surrogate key generation strategy (optional operation)
String	getIdentifierColumnAlias(String suffix)	Deprecated, for removal: This API element is subject to removal in a future version. Read-by-position makes this irrelevant.
String	getIdentifierColumnName()
Type	getIdentifierType()	Deprecated, for removal: This API element is subject to removal in a future version. Hibernate is moving away from Type.
String[]	getIndexColumnAliases(String suffix)	Deprecated, for removal: This API element is subject to removal in a future version. Read-by-position makes this irrelevant.
boolean[]	getIndexColumnIsSettable()
UnaryOperator<Object>	getIndexIncrementer()
Type	getIndexType()	Deprecated, for removal: This API element is subject to removal in a future version. Hibernate is moving away from Type.
String[]	getKeyColumnAliases(String suffix)	Deprecated, for removal: This API element is subject to removal in a future version. Read-by-position makes this irrelevant.
Type	getKeyType()	Deprecated, for removal: This API element is subject to removal in a future version. Hibernate is moving away from Type.
String	getMappedByProperty()
NavigableRole	getNavigableRole()	The NavigableRole for this collection.
EntityPersister	getOwnerEntityPersister()	Get the persister of the entity that "owns" this collection
default String	getRole()	Get the name of this collection role (the fully qualified class name, extended by a "property path")
RowMutationOperations	getRowMutationOperations()
int	getSize(Object key, SharedSessionContractImplementor session)
Comparator<?>	getSortingComparator()	For sorted collections, the comparator to use.
String	getTableName()
boolean	hasCache()	Is this collection role cacheable
boolean	hasIndex()	Is this an "indexed" collection? (list or map)
boolean	hasManyToManyOrdering()
boolean	hasOrdering()	Is this an ordered collection? (An ordered collection is ordered by the initialization operation, not by sorting that happens in memory, as in the case of a sorted collection.)
boolean	hasOrphanDelete()	Does this collection implement "orphan delete"?
boolean	indexExists(Object key, Object index, SharedSessionContractImplementor session)
void	initialize(Object key, SharedSessionContractImplementor session)	Initialize the given collection with the given key
void	insertRows(PersistentCollection<?> collection, Object key, SharedSessionContractImplementor session)	Insert the persistent state of any new collection elements
default boolean	isAffectedByEnabledFetchProfiles(LoadQueryInfluencers influencers)
default boolean	isAffectedByEnabledFilters(Set<ManagedMappingType> visitedTypes, LoadQueryInfluencers influencers, boolean onlyApplyForLoadByKey)
default boolean	isAffectedByEnabledFilters(LoadQueryInfluencers influencers)
default boolean	isAffectedByEnabledFilters(LoadQueryInfluencers influencers, boolean onlyApplyForLoadByKeyFilters)
boolean	isAffectedByEnabledFilters(SharedSessionContractImplementor session)
default boolean	isAffectedByEntityGraph(LoadQueryInfluencers influencers)
boolean	isArray()	Is this an array?
default boolean	isBatchLoadable()
boolean	isCascadeDeleteEnabled()	Is cascade delete handled by the database-level foreign key constraint definition?
default boolean	isExtraLazy()
boolean	isInverse()	Is this collection "inverse", so state changes are not propagated to the database.
boolean	isLazy()	Is this collection lazily initialized?
boolean	isManyToMany()	Is this a many-to-many association? Note that this is mainly a convenience feature as the single persister does not contain all the information needed to handle a many-to-many itself, as internally it is looked at as two many-to-ones.
boolean	isMutable()	Can the elements of this collection change?
boolean	isOneToMany()	Is this a one-to-many association?
boolean	isPrimitiveArray()	Is this an array of primitive values?
boolean	isRowDeleteEnabled()
boolean	isRowInsertEnabled()
default boolean	isSubselectLoadable()
boolean	isVersioned()	Does this collection cause version increment of the owning entity?
default boolean	needsRemove()	Whether remove(Object, SharedSessionContractImplementor) might actually do something, or if it is definitely a no-op.
void	postInstantiate()
void	processQueuedOps(PersistentCollection<?> collection, Object key, SharedSessionContractImplementor session)	Process queued operations within the PersistentCollection.
void	recreate(PersistentCollection<?> collection, Object key, SharedSessionContractImplementor session)	(Re)create the collection's persistent state
void	remove(Object id, SharedSessionContractImplementor session)	Completely remove the persistent state of the collection
String	selectFragment(String alias, String columnSuffix)	Generate a list of collection index and element columns
void	updateRows(PersistentCollection<?> collection, Object key, SharedSessionContractImplementor session)	Update the persistent state of any elements that were modified
boolean	useShallowQueryCacheLayout()

Methods inherited from interface FilterRestrictable

applyFilterRestrictions

Methods inherited from interface Restrictable

applyBaseRestrictions

Methods inherited from interface WhereRestrictable

applyWhereRestrictions, hasWhereRestrictions

Method Details

getNavigableRole

@Nonnull
NavigableRole getNavigableRole()

The NavigableRole for this collection.

getRole

@Nonnull
default String getRole()

Get the name of this collection role (the fully qualified class name, extended by a "property path")

getAttributeMapping

@Nonnull
default PluralAttributeMapping getAttributeMapping()

decompose

@Internal
void decompose(@Nonnull
 org.hibernate.action.queue.internal.PreparedCollectionMutation mutation,
 int ordinalBase,
 @Nonnull
 SharedSessionContractImplementor session,
 @Nonnull
 DecompositionContext decompositionContext,
 @Nonnull
 Consumer<FlushOperation> operationConsumer)

Decomposes a prepared collection mutation into graph-native operations.

getOwnerEntityPersister

@Nonnull
EntityPersister getOwnerEntityPersister()

Get the persister of the entity that "owns" this collection

initialize

void initialize(@Nonnull
 Object key,
 @Nonnull
 SharedSessionContractImplementor session)
         throws HibernateException

Initialize the given collection with the given key

Throws:

HibernateException

hasCache

boolean hasCache()

Is this collection role cacheable

needsRemove

default boolean needsRemove()

Whether remove(Object, SharedSessionContractImplementor) might actually do something, or if it is definitely a no-op.

getRowMutationOperations

@Nonnull
@Internal
RowMutationOperations getRowMutationOperations()

isRowInsertEnabled

@Internal
boolean isRowInsertEnabled()

isRowDeleteEnabled

@Internal
boolean isRowDeleteEnabled()

getIndexColumnIsSettable

@Nullable
@Internal
boolean[] getIndexColumnIsSettable()

getElementColumnIsSettable

@Nonnull
@Internal
boolean[] getElementColumnIsSettable()

getIndexIncrementer

@Nonnull
@Internal
UnaryOperator<Object> getIndexIncrementer()

getCacheAccessStrategy

@Nullable
CollectionDataAccess getCacheAccessStrategy()

Access to the collection's cache region

getCacheEntryStructure

@Nonnull
CacheEntryStructure getCacheEntryStructure()

Get the structure used to store data into the collection's cache region

useShallowQueryCacheLayout

@Incubating(since="6.5")
boolean useShallowQueryCacheLayout()

getElementClass

@Nullable
Class<?> getElementClass()

Return the element class of an array, or null otherwise

isPrimitiveArray

boolean isPrimitiveArray()

Is this an array of primitive values?

isArray

boolean isArray()

Is this an array?

isOneToMany

boolean isOneToMany()

Is this a one-to-many association?

isManyToMany

boolean isManyToMany()

Is this a many-to-many association? Note that this is mainly a convenience feature as the single persister does not contain all the information needed to handle a many-to-many itself, as internally it is looked at as two many-to-ones.

hasIndex

boolean hasIndex()

Is this an "indexed" collection? (list or map)

isLazy

boolean isLazy()

Is this collection lazily initialized?

isInverse

boolean isInverse()

Is this collection "inverse", so state changes are not propagated to the database.

remove

void remove(@Nonnull
 Object id,
 @Nonnull
 SharedSessionContractImplementor session)

Completely remove the persistent state of the collection

recreate

void recreate(@Nonnull
 PersistentCollection<?> collection,
 @Nonnull
 Object key,
 @Nonnull
 SharedSessionContractImplementor session)

(Re)create the collection's persistent state

deleteRows

void deleteRows(@Nonnull
 PersistentCollection<?> collection,
 @Nonnull
 Object key,
 @Nonnull
 SharedSessionContractImplementor session)

Delete the persistent state of any elements that were removed from the collection

updateRows

void updateRows(@Nonnull
 PersistentCollection<?> collection,
 @Nonnull
 Object key,
 @Nonnull
 SharedSessionContractImplementor session)

Update the persistent state of any elements that were modified

insertRows

void insertRows(@Nonnull
 PersistentCollection<?> collection,
 @Nonnull
 Object key,
 @Nonnull
 SharedSessionContractImplementor session)

Insert the persistent state of any new collection elements

processQueuedOps

void processQueuedOps(@Nonnull
 PersistentCollection<?> collection,
 @Nonnull
 Object key,
 @Nonnull
 SharedSessionContractImplementor session)

Process queued operations within the PersistentCollection.

getGenerator

@Nullable
BeforeExecutionGenerator getGenerator()

Get the surrogate key generation strategy (optional operation)

hasOrphanDelete

boolean hasOrphanDelete()

Does this collection implement "orphan delete"?

hasOrdering

boolean hasOrdering()

Is this an ordered collection? (An ordered collection is ordered by the initialization operation, not by sorting that happens in memory, as in the case of a sorted collection.)

hasManyToManyOrdering

boolean hasManyToManyOrdering()

getCollectionSpaces

@Nonnull
String[] getCollectionSpaces()

Get the "space" that holds the persistent state

isCascadeDeleteEnabled

boolean isCascadeDeleteEnabled()

Is cascade delete handled by the database-level foreign key constraint definition?

isVersioned

boolean isVersioned()

Does this collection cause version increment of the owning entity?

isMutable

boolean isMutable()

Can the elements of this collection change?

postInstantiate

void postInstantiate()
              throws MappingException

Throws:

MappingException

getFactory

@Nonnull
SessionFactoryImplementor getFactory()

isAffectedByEnabledFilters

boolean isAffectedByEnabledFilters(@Nonnull
 SharedSessionContractImplementor session)

isAffectedByEnabledFilters

default boolean isAffectedByEnabledFilters(@Nonnull
 LoadQueryInfluencers influencers)

isAffectedByEnabledFilters

default boolean isAffectedByEnabledFilters(@Nonnull
 LoadQueryInfluencers influencers,
 boolean onlyApplyForLoadByKeyFilters)

isAffectedByEnabledFilters

default boolean isAffectedByEnabledFilters(@Nonnull
 Set<ManagedMappingType> visitedTypes,
 @Nonnull
 LoadQueryInfluencers influencers,
 boolean onlyApplyForLoadByKey)

isAffectedByEntityGraph

default boolean isAffectedByEntityGraph(@Nonnull
 LoadQueryInfluencers influencers)

isAffectedByEnabledFetchProfiles

default boolean isAffectedByEnabledFetchProfiles(@Nonnull
 LoadQueryInfluencers influencers)

isExtraLazy

default boolean isExtraLazy()

getSize

int getSize(@Nonnull
 Object key,
 @Nonnull
 SharedSessionContractImplementor session)

indexExists

boolean indexExists(@Nonnull
 Object key,
 @Nonnull
 Object index,
 @Nonnull
 SharedSessionContractImplementor session)

elementExists

boolean elementExists(@Nonnull
 Object key,
 @Nullable
 Object element,
 @Nonnull
 SharedSessionContractImplementor session)

getElementByIndex

@Nullable
Object getElementByIndex(@Nonnull
 Object key,
 @Nonnull
 Object index,
 @Nonnull
 SharedSessionContractImplementor session,
 @Nullable
 Object owner)

getBatchSize

default int getBatchSize()

isBatchLoadable

default boolean isBatchLoadable()

isSubselectLoadable

default boolean isSubselectLoadable()

getMappedByProperty

@Nullable
String getMappedByProperty()

Returns:

the name of the property this collection is mapped by

getSortingComparator

@Nullable
Comparator<?> getSortingComparator()

For sorted collections, the comparator to use. Non-parameterized because for SORTED_SET the elements are compared but for SORTED_MAP the keys are compared

See Also:

• CollectionClassification.SORTED_MAP
• CollectionClassification.SORTED_SET

getCollectionSemantics

@Nonnull
CollectionSemantics<?,?> getCollectionSemantics()

applyBaseManyToManyRestrictions

void applyBaseManyToManyRestrictions(@Nonnull
 Consumer<Predicate> predicateConsumer,
 @Nonnull
 TableGroup tableGroup,
 boolean useQualifier,
 @Nonnull
 Map<String,Filter> enabledFilters,
 @Nullable
 Set<String> treatAsDeclarations,
 @Nullable
 SqlAstCreationState creationState)

getKeyColumnAliases

@Nonnull
@Deprecated(since="6",
            forRemoval=true)
String[] getKeyColumnAliases(@Nonnull
 String suffix)

Deprecated, for removal: This API element is subject to removal in a future version.

Read-by-position makes this irrelevant. Currently still used by SQLQueryParser

Generates the collection's key column aliases, based on the given suffix.

Parameters:

suffix - The suffix to use in the key column alias generation.

Returns:

The key column aliases.

getIndexColumnAliases

@Nullable
@Deprecated(since="6",
            forRemoval=true)
String[] getIndexColumnAliases(@Nonnull
 String suffix)

Deprecated, for removal: This API element is subject to removal in a future version.

Read-by-position makes this irrelevant. Currently still used by SQLQueryParser

Generates the collection's index column aliases, based on the given suffix.

Parameters:

suffix - The suffix to use in the index column alias generation.

Returns:

The key column aliases, or null if not indexed.

getElementColumnAliases

@Nonnull
@Deprecated(since="6",
            forRemoval=true)
String[] getElementColumnAliases(@Nonnull
 String suffix)

Deprecated, for removal: This API element is subject to removal in a future version.

Read-by-position makes this irrelevant. Currently still used by SQLQueryParser

Generates the collection's element column aliases, based on the given suffix.

Parameters:

suffix - The suffix to use in the element column alias generation.

Returns:

The key column aliases.

getIdentifierColumnAlias

@Nullable
@Deprecated(since="6",
            forRemoval=true)
String getIdentifierColumnAlias(@Nonnull
 String suffix)

Deprecated, for removal: This API element is subject to removal in a future version.

Read-by-position makes this irrelevant. Currently still used by SQLQueryParser

Generates the collection's identifier column aliases, based on the given suffix.

Parameters:

suffix - The suffix to use in the key column alias generation.

Returns:

The key column aliases.

getCollectionType

@Nonnull
@Deprecated(forRemoval=true)
CollectionType getCollectionType()

Deprecated, for removal: This API element is subject to removal in a future version.

Hibernate is moving away from Type. Corresponding mapping metamodel calls should be used instead - here (generally), PluralAttributeMapping

Get the associated Type

getKeyType

@Nonnull
@Deprecated(forRemoval=true)
Type getKeyType()

Deprecated, for removal: This API element is subject to removal in a future version.

Hibernate is moving away from Type. Corresponding mapping metamodel calls should be used instead - here, PluralAttributeMapping.getKeyDescriptor()

Get the "key" type (the type of the foreign key)

getIndexType

@Nullable
@Deprecated(forRemoval=true)
Type getIndexType()

Deprecated, for removal: This API element is subject to removal in a future version.

Hibernate is moving away from Type. Corresponding mapping metamodel calls should be used instead - here, PluralAttributeMapping.getIndexDescriptor()

Get the "index" type for a list or map (optional operation)

getElementType

@Nonnull
@Deprecated(forRemoval=true)
Type getElementType()

Deprecated, for removal: This API element is subject to removal in a future version.

Hibernate is moving away from Type. Corresponding mapping metamodel calls should be used instead - here, PluralAttributeMapping.getElementDescriptor()

Get the "element" type

getIdentifierType

@Nullable
@Deprecated(forRemoval=true)
Type getIdentifierType()

Deprecated, for removal: This API element is subject to removal in a future version.

Hibernate is moving away from Type. Corresponding mapping metamodel calls should be used instead - here, PluralAttributeMapping.getIdentifierDescriptor()

Get the type of the surrogate key

getIdentifierColumnName

@Nullable
String getIdentifierColumnName()

getTableName

@Nonnull
String getTableName()

selectFragment

@Nonnull
String selectFragment(@Nonnull
 String alias,
 @Nonnull
 String columnSuffix)

Generate a list of collection index and element columns

getCollectionPropertyColumnAliases

@Nullable
String[] getCollectionPropertyColumnAliases(@Nonnull
 String propertyName,
 @Nonnull
 String string)

getElementPersister

@Nullable
EntityPersister getElementPersister()

Get the persister of the element class, if this is a collection of entities (optional operation). Note that for a one-to-many association, the returned persister must be OuterJoinLoadable.