Top Description Methods
org.hibernate.collection.spi

public Interface PersistentCollection<E>

extends LazyInitializable
Known Direct Implementers
org.hibernate.collection.spi.AbstractPersistentCollection
Annotations
@Incubating
Type Parameters
<E>
the collection element type, or map value type
Imports
java.io.Serializable, java.util.Collection, .Iterator, .List, org.hibernate.HibernateException, .Incubating, org.hibernate.engine.spi.SharedSessionContractImplementor, org.hibernate.metamodel.mapping.PluralAttributeMapping, org.hibernate.persister.collection.CollectionPersister, org.hibernate.persister.collection.mutation.InsertRowsCoordinator, org.hibernate.type.Type, org.checkerframework.checker.nullness.qual.Nullable
Persistent collections are treated as value objects by Hibernate. They have no independent existence beyond the entity holding a reference to them. Unlike instances of entity classes, they are automatically deleted when unreferenced and automatically become persistent when held by a persistent object. Collections can be passed between different objects (change "roles") and this might cause their elements to move from one database table to another.

Hibernate "wraps" a Java collection in an instance of PersistentCollection. This mechanism is allows for tracking of changes to the persistent state of the collection and lazy fetching of the collection elements. The downside is that only certain abstract collection types are supported and any extra semantics associated with the particular implementation of the generic collection type are lost. For example, every java.util.List behaves like an ArrayList, and every java.util.SortedMap behaves like a TreeMap.

Applications should never use classes in this package directly, unless extending the "framework" here.

Changes to structure of the collection are recorded by the collection calling back to the session. Changes to mutable elements (composite elements) are discovered by cloning their state when the collection is initialized and comparing at flush time.

Author
Gavin King

Method Summary

Modifier and TypeMethod and Description
public boolean
afterInitialize()

Called after initialization is complete.

public void
afterRowInsert(CollectionPersister
The collection persister
persister, Object
The collection element just inserted
entry, int
The element position/index
i)

Called after inserting a row, to fetch the natively generated id

public void
beforeInitialize(CollectionPersister persister, int anticipatedSize)

Called prior to the initialization of this yet-uninitialized collection.

public void
beginRead()

Called just before reading any rows from the JDBC result set.

public void
clearDirty()

Clear the dirty flag, after flushing changes to the database.

public void
dirty()

Mark the collection as dirty

public Object

Returns:

The disassembled state
disassemble(CollectionPersister
The collection persister
persister)

Disassemble the collection to get it ready for the cache

public Object
elementByIndex(Object index)

Obtain the element os this collection associated with the given index without initializing it

public boolean
elementExists(Object element)

Determine if the given element belongs to this collection without initializing it

public boolean

Returns:

false if the collection is non-empty; true otherwise.
empty()

Is the collection empty?

public boolean
endRead()

Called after reading all rows from the JDBC result set.

public Iterator<?>

Returns:

The iterator
entries(CollectionPersister
The collection persister.
persister)

Iterate all collection entries, during update of the database

public boolean

Returns:

true if the given entry is a collection element
entryExists(Object
The object to check if it exists as a collection element
entry, int
Unused
i)

Does the given element/entry exist in the collection?

public boolean

Returns:

true if the current state and the snapshot state match.
equalsSnapshot(CollectionPersister
The collection persister
persister)

Does the current state exactly match the snapshot?

public Iterator<?>

Returns:

An iterator over the elements to delete
getDeletes(CollectionPersister
The collection persister
persister, boolean
For indexed collections, tells whether the index is a formula (calculated value) mapping
indexIsFormula)

Get all the elements that need deleting

public Object

Returns:

The corresponding object that is part of the collection elements.
getElement(Object
The object instance for which to get the collection element instance.
entry)

Get the value of the given collection entry.

public Object

Returns:

The identifier value
getIdentifier(Object
The collection entry/element
entry, int
The assumed identifier (?)
i)

Get the identifier of the given collection entry.

public Object

Returns:

The index value
getIndex(Object
The collection entry/element
entry, int
The assumed index
i, CollectionPersister
it was more elegant before we added this...
persister)

Get the index of the given collection entry

public Object

Returns:

the current collection key value
getKey()

Get the current collection key value

public Collection<E>

Returns:

The orphans
getOrphans(Serializable
The snapshot state
snapshot, String
The name of the entity that are the elements of the collection
entityName)

get all "orphaned" elements

public Object

Returns:

The owner
getOwner()

Get the owning entity.

public Collection<E>

Returns:

The orphaned elements
getQueuedOrphans(String
The name of the entity that makes up the elements
entityName)

Get the "queued" orphans

public String

Returns:

the collection role name
getRole()

Get the current role name

public int
getSize()

Obtain the size of this collection without initializing it

public Serializable

Returns:

The snapshot
getSnapshot(CollectionPersister
The collection persister
persister)

Return a new snapshot of the current state of the collection

public Object

Returns:

The snapshot state for that element
getSnapshotElement(Object
The entry
entry, int
The index
i)

Get the snapshot value of the given collection entry

public Serializable

Returns:

The internally stored snapshot state
getStoredSnapshot()

Get the snapshot cached by the collection instance

public Object

Returns:

The underlying collection/array
getValue()

Return the user-visible collection (or array) instance

public boolean

Returns:

true indicates there are pending, queued, delayed operations
hasQueuedOperations()

Does this instance have any "queued" operations?

public default boolean
includeInInsert(Object entry, int entryPosition, PersistentCollection<?> collection, PluralAttributeMapping attributeDescriptor)

Whether to include the entry for insertion operations

public default boolean
includeInRecreate(Object entry, int i, PersistentCollection<?> collection, PluralAttributeMapping attributeDescriptor)

Whether the given entry should be included in recreation events

public void
initializeEmptyCollection(CollectionPersister persister)

public void
initializeFromCache(CollectionPersister
The collection persister
persister, Object
The disassembled cached state
disassembled, Object
The collection owner
owner)

Read the state of the collection from a disassembled cached value

public void
injectLoadedState(PluralAttributeMapping attributeMapping, List<?> loadingState)

Inject the state loaded for a collection instance.

public boolean

Returns:

true indicates that the application might have access to the underlying collection/array.
isDirectlyAccessible()

Could the application possibly have a direct reference to the underlying collection implementation?

public default boolean

Returns:

true, if collection was provided directly to this PersistentCollection; false, otherwise.
isDirectlyProvidedCollection(Object
The collection
collection)

Was collection provided directly to this PersistentCollection (i.e., provided as an argument to a constructor)?

public boolean

Returns:

true if the collection is dirty
isDirty()

Is the collection dirty?

public default boolean
isElementRemoved()

public boolean
isInitializing()

Is this PersistentCollection in the process of being initialized?

public default boolean

Returns:

true if the collection is newly instantiated
isNewlyInstantiated()

Is the collection newly instantiated?

public boolean

Returns:

true if the row for each element is known
isRowUpdatePossible()

Can each element in the collection be mapped unequivocally to a single row in the database?

public boolean

Returns:

true if the given snapshot is empty
isSnapshotEmpty(Serializable
The snapshot to check
snapshot)

Is the snapshot empty?

public boolean

Returns:

true if the collection is no longer referenced by an owner
isUnreferenced()

Is the collection unreferenced?

public boolean

Returns:

true if this is a wrapper around that given collection instance.
isWrapper(Object
The collection to check whether this is wrapping it
collection)

Is this the wrapper for the given collection instance?

public boolean

Returns:

true if the element needs inserting
needsInserting(Object
The collection element to check
entry, int
The index (for indexed collections)
i, Type
The type for the element
elemType)

Do we need to insert this element?

public boolean

Returns:

true if a change requires a recreate.
needsRecreate(CollectionPersister
The collection persister
persister)

Do we need to completely recreate this collection when it changes?

public default boolean

Returns:

true if the element needs updating
needsUpdating(Object
The collection element to check
entry, int
The index (for indexed collections)
entryPosition, PluralAttributeMapping
The type for the element
attributeDescriptor)

Do we need to update this element?

public boolean

Returns:

true if the element needs updating
needsUpdating(Object
The collection element to check
entry, int
The index (for indexed collections)
i, Type
The type for the element
elemType)

Do we need to update this element?

public void
postAction()

After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.

public void
preInsert(CollectionPersister
The collection persister
persister)

Called before inserting rows, to ensure that any surrogate keys are fully generated

public Iterator<E>

Returns:

The iterator
queuedAdditionIterator()

Iterator over the "queued" additions

public default String
render()

Like Object#toString() but without the silliness of rendering the elements

public boolean

Returns:

false if the collection was already associated with the session
setCurrentSession(SharedSessionContractImplementor
The session to associate with
session)

Associate the collection with the given session.

public void
setOwner(Object
The owner
entity)

Set the reference to the owning entity

public void
setSnapshot(@Nullable Object
The collection instance key (fk value).
key, @Nullable String
The collection role
role, @Nullable Serializable
The snapshot state
snapshot)

After flushing, re-init snapshot state.

public boolean

Returns:

true if this was currently associated with the given session
unsetSession(SharedSessionContractImplementor
The session we are disassociating from. Used for validations.
currentSession)

Disassociate this collection from the given session.

Inherited from org.hibernate.collection.spi.LazyInitializable:
forceInitializationwasInitialized

Method Detail

afterInitializeback to summary
public boolean afterInitialize()

Called after initialization is complete. Pairs with beforeInitialize

afterRowInsertback to summary
public void afterRowInsert(CollectionPersister persister, Object entry, int i)

Called after inserting a row, to fetch the natively generated id

Parameters
persister:CollectionPersister

The collection persister

entry:Object

The collection element just inserted

i:int

The element position/index

beforeInitializeback to summary
public void beforeInitialize(CollectionPersister persister, int anticipatedSize)

Called prior to the initialization of this yet-uninitialized collection. Pairs with afterInitialize

beginReadback to summary
public void beginRead()

Called just before reading any rows from the JDBC result set. Pairs with endRead

clearDirtyback to summary
public void clearDirty()

Clear the dirty flag, after flushing changes to the database.

dirtyback to summary
public void dirty()

Mark the collection as dirty

disassembleback to summary
public Object disassemble(CollectionPersister persister)

Disassemble the collection to get it ready for the cache

Parameters
persister:CollectionPersister

The collection persister

Returns:Object

The disassembled state

elementByIndexback to summary
public Object elementByIndex(Object index)

Obtain the element os this collection associated with the given index without initializing it

elementExistsback to summary
public boolean elementExists(Object element)

Determine if the given element belongs to this collection without initializing it

emptyback to summary
public boolean empty()

Is the collection empty? (don't try to initialize the collection)

Returns:boolean

false if the collection is non-empty; true otherwise.

endReadback to summary
public boolean endRead()

Called after reading all rows from the JDBC result set. Pairs with beginRead

Annotations
@SuppressWarnings:UnusedReturnValue
See Also
injectLoadedState
entriesback to summary
public Iterator<?> entries(CollectionPersister persister)

Iterate all collection entries, during update of the database

Parameters
persister:CollectionPersister

The collection persister.

Returns:Iterator<?>

The iterator

entryExistsback to summary
public boolean entryExists(Object entry, int i)

Does the given element/entry exist in the collection?

Parameters
entry:Object

The object to check if it exists as a collection element

i:int

Unused

Returns:boolean

true if the given entry is a collection element

equalsSnapshotback to summary
public boolean equalsSnapshot(CollectionPersister persister)

Does the current state exactly match the snapshot?

Parameters
persister:CollectionPersister

The collection persister

Returns:boolean

true if the current state and the snapshot state match.

getDeletesback to summary
public Iterator<?> getDeletes(CollectionPersister persister, boolean indexIsFormula)

Get all the elements that need deleting

Parameters
persister:CollectionPersister

The collection persister

indexIsFormula:boolean

For indexed collections, tells whether the index is a formula (calculated value) mapping

Returns:Iterator<?>

An iterator over the elements to delete

getElementback to summary
public Object getElement(Object entry)

Get the value of the given collection entry. Generally the given entry parameter value will just be returned. Might get a different value for a duplicate entries in a Set.

Parameters
entry:Object

The object instance for which to get the collection element instance.

Returns:Object

The corresponding object that is part of the collection elements.

getIdentifierback to summary
public Object getIdentifier(Object entry, int i)

Get the identifier of the given collection entry. This refers to the collection identifier, not the identifier of the (possibly) entity elements. This is only valid for invocation on the idbag collection.

Parameters
entry:Object

The collection entry/element

i:int

The assumed identifier (?)

Returns:Object

The identifier value

getIndexback to summary
public Object getIndex(Object entry, int i, CollectionPersister persister)

Get the index of the given collection entry

Parameters
entry:Object

The collection entry/element

i:int

The assumed index

persister:CollectionPersister

it was more elegant before we added this...

Returns:Object

The index value

getKeyback to summary
public Object getKey()

Get the current collection key value

Returns:Object

the current collection key value

getOrphansback to summary
public Collection<E> getOrphans(Serializable snapshot, String entityName)

get all "orphaned" elements

Parameters
snapshot:Serializable

The snapshot state

entityName:String

The name of the entity that are the elements of the collection

Returns:Collection<E>

The orphans

getOwnerback to summary
public Object getOwner()

Get the owning entity. Note that the owner is only set during the flush cycle, and when a new collection wrapper is created while loading an entity.

Returns:Object

The owner

getQueuedOrphansback to summary
public Collection<E> getQueuedOrphans(String entityName)

Get the "queued" orphans

Parameters
entityName:String

The name of the entity that makes up the elements

Returns:Collection<E>

The orphaned elements

getRoleback to summary
public String getRole()

Get the current role name

Returns:String

the collection role name

getSizeback to summary
public int getSize()

Obtain the size of this collection without initializing it

getSnapshotback to summary
public Serializable getSnapshot(CollectionPersister persister)

Return a new snapshot of the current state of the collection

Parameters
persister:CollectionPersister

The collection persister

Returns:Serializable

The snapshot

getSnapshotElementback to summary
public Object getSnapshotElement(Object entry, int i)

Get the snapshot value of the given collection entry

Parameters
entry:Object

The entry

i:int

The index

Returns:Object

The snapshot state for that element

getStoredSnapshotback to summary
public Serializable getStoredSnapshot()

Get the snapshot cached by the collection instance

Returns:Serializable

The internally stored snapshot state

getValueback to summary
public Object getValue()

Return the user-visible collection (or array) instance

Returns:Object

The underlying collection/array

hasQueuedOperationsback to summary
public boolean hasQueuedOperations()

Does this instance have any "queued" operations?

Returns:boolean

true indicates there are pending, queued, delayed operations

includeInInsertback to summary
public default boolean includeInInsert(Object entry, int entryPosition, PersistentCollection<?> collection, PluralAttributeMapping attributeDescriptor)

Whether to include the entry for insertion operations

API Note

Defined to match signature of InsertRowsCoordinator.EntryFilter#include

includeInRecreateback to summary
public default boolean includeInRecreate(Object entry, int i, PersistentCollection<?> collection, PluralAttributeMapping attributeDescriptor)

Whether the given entry should be included in recreation events

API Note

Defined to match signature of InsertRowsCoordinator.EntryFilter#include

initializeEmptyCollectionback to summary
public void initializeEmptyCollection(CollectionPersister persister)
initializeFromCacheback to summary
public void initializeFromCache(CollectionPersister persister, Object disassembled, Object owner)

Read the state of the collection from a disassembled cached value

Parameters
persister:CollectionPersister

The collection persister

disassembled:Object

The disassembled cached state

owner:Object

The collection owner

injectLoadedStateback to summary
public void injectLoadedState(PluralAttributeMapping attributeMapping, List<?> loadingState)

Inject the state loaded for a collection instance.

isDirectlyAccessibleback to summary
public boolean isDirectlyAccessible()

Could the application possibly have a direct reference to the underlying collection implementation?

Returns:boolean

true indicates that the application might have access to the underlying collection/array.

isDirectlyProvidedCollectionback to summary
public default boolean isDirectlyProvidedCollection(Object collection)

Was collection provided directly to this PersistentCollection (i.e., provided as an argument to a constructor)?

Implementors that can copy elements out of a directly provided collection into the wrapped collection should override this method.

Parameters
collection:Object

The collection

Returns:boolean

true, if collection was provided directly to this PersistentCollection; false, otherwise.

isDirtyback to summary
public boolean isDirty()

Is the collection dirty? Note that this is only reliable during the flush cycle, after the collection elements are dirty checked against the snapshot.

Returns:boolean

true if the collection is dirty

isElementRemovedback to summary
public default boolean isElementRemoved()
isInitializingback to summary
public boolean isInitializing()

Is this PersistentCollection in the process of being initialized?

isNewlyInstantiatedback to summary
public default boolean isNewlyInstantiated()

Is the collection newly instantiated?

Returns:boolean

true if the collection is newly instantiated

isRowUpdatePossibleback to summary
public boolean isRowUpdatePossible()

Can each element in the collection be mapped unequivocally to a single row in the database? Generally bags and sets are the only collections that cannot be.

Returns:boolean

true if the row for each element is known

isSnapshotEmptyback to summary
public boolean isSnapshotEmpty(Serializable snapshot)

Is the snapshot empty?

Parameters
snapshot:Serializable

The snapshot to check

Returns:boolean

true if the given snapshot is empty

isUnreferencedback to summary
public boolean isUnreferenced()

Is the collection unreferenced?

Returns:boolean

true if the collection is no longer referenced by an owner

isWrapperback to summary
public boolean isWrapper(Object collection)

Is this the wrapper for the given collection instance?

Parameters
collection:Object

The collection to check whether this is wrapping it

Returns:boolean

true if this is a wrapper around that given collection instance.

needsInsertingback to summary
public boolean needsInserting(Object entry, int i, Type elemType)

Do we need to insert this element?

Parameters
entry:Object

The collection element to check

i:int

The index (for indexed collections)

elemType:Type

The type for the element

Returns:boolean

true if the element needs inserting

needsRecreateback to summary
public boolean needsRecreate(CollectionPersister persister)

Do we need to completely recreate this collection when it changes?

Parameters
persister:CollectionPersister

The collection persister

Returns:boolean

true if a change requires a recreate.

needsUpdatingback to summary
public default boolean needsUpdating(Object entry, int entryPosition, PluralAttributeMapping attributeDescriptor)

Do we need to update this element?

Parameters
entry:Object

The collection element to check

entryPosition:int

The index (for indexed collections)

attributeDescriptor:PluralAttributeMapping

The type for the element

Returns:boolean

true if the element needs updating

needsUpdatingback to summary
public boolean needsUpdating(Object entry, int i, Type elemType)

Do we need to update this element?

Parameters
entry:Object

The collection element to check

i:int

The index (for indexed collections)

elemType:Type

The type for the element

Returns:boolean

true if the element needs updating

postActionback to summary
public void postAction()

After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.

preInsertback to summary
public void preInsert(CollectionPersister persister)

Called before inserting rows, to ensure that any surrogate keys are fully generated

Parameters
persister:CollectionPersister

The collection persister

queuedAdditionIteratorback to summary
public Iterator<E> queuedAdditionIterator()

Iterator over the "queued" additions

Returns:Iterator<E>

The iterator

renderback to summary
public default String render()

Like Object#toString() but without the silliness of rendering the elements

setCurrentSessionback to summary
public boolean setCurrentSession(SharedSessionContractImplementor session) throws HibernateException

Associate the collection with the given session.

Parameters
session:SharedSessionContractImplementor

The session to associate with

Returns:boolean

false if the collection was already associated with the session

Exceptions
HibernateException:
if the collection was already associated with another open session
setOwnerback to summary
public void setOwner(Object entity)

Set the reference to the owning entity

Parameters
entity:Object

The owner

setSnapshotback to summary
public void setSnapshot(@Nullable Object key, @Nullable String role, @Nullable Serializable snapshot)

After flushing, re-init snapshot state.

Parameters
key:@Nullable Object

The collection instance key (fk value).

role:@Nullable String

The collection role

snapshot:@Nullable Serializable

The snapshot state

unsetSessionback to summary
public boolean unsetSession(SharedSessionContractImplementor currentSession)

Disassociate this collection from the given session.

Parameters
currentSession:SharedSessionContractImplementor

The session we are disassociating from. Used for validations.

Returns:boolean

true if this was currently associated with the given session