org.hibernate.collection.spi

Interface PersistentCollection

All Known Implementing Classes:

AbstractPersistentCollection, PersistentArrayHolder, PersistentBag, PersistentIdentifierBag, PersistentList, PersistentMap, PersistentSet, PersistentSortedMap, PersistentSortedSet

public interface PersistentCollection

Persistent collections are treated as value objects by Hibernate. ie. they have no independent existence beyond the object 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 designed to support tracking of changes to the collection's persistent state and lazy instantiation of collection elements. The downside is that only certain abstract collection types are supported and any extra semantics are lost

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 (ie. 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 Type	Method and Description
boolean	afterInitialize() Called after initializing from cache
void	afterRowInsert(CollectionPersister persister, Object entry, int i) Called after inserting a row, to fetch the natively generated id
void	beforeInitialize(CollectionPersister persister, int anticipatedSize) Called before any elements are read into the collection, allowing appropriate initializations to occur.
void	beginRead() Called just before reading any rows from the JDBC result set
void	clearDirty() Clear the dirty flag, after flushing changes to the database.
void	dirty() Mark the collection as dirty
Serializable	disassemble(CollectionPersister persister) Disassemble the collection to get it ready for the cache
boolean	empty() Is the collection empty? (don't try to initialize the collection)
boolean	endRead() Called after reading all rows from the JDBC result set
Iterator	entries(CollectionPersister persister) Iterate all collection entries, during update of the database
boolean	entryExists(Object entry, int i) Does the given element/entry exist in the collection?
boolean	equalsSnapshot(CollectionPersister persister) Does the current state exactly match the snapshot?
void	forceInitialization() To be called internally by the session, forcing immediate initialization.
Iterator	getDeletes(CollectionPersister persister, boolean indexIsFormula) Get all the elements that need deleting
Object	getElement(Object entry) Get the value of the given collection entry.
Object	getIdentifier(Object entry, int i) Get the identifier of the given collection entry.
Object	getIndex(Object entry, int i, CollectionPersister persister) Get the index of the given collection entry
Serializable	getKey() Get the current collection key value
Collection	getOrphans(Serializable snapshot, String entityName) get all "orphaned" elements
Object	getOwner() Get the owning entity.
Collection	getQueuedOrphans(String entityName) Get the "queued" orphans
String	getRole() Get the current role name
Serializable	getSnapshot(CollectionPersister persister) Return a new snapshot of the current state of the collection
Object	getSnapshotElement(Object entry, int i) Get the snapshot value of the given collection entry
Serializable	getStoredSnapshot() Get the snapshot cached by the collection instance
Object	getValue() Return the user-visible collection (or array) instance
boolean	hasQueuedOperations() Does this instance have any "queued" operations?
void	initializeFromCache(CollectionPersister persister, Serializable disassembled, Object owner) Read the state of the collection from a disassembled cached value
boolean	isDirectlyAccessible() Could the application possibly have a direct reference to the underlying collection implementation?
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.
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.
default boolean	isElementRemoved()
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.
boolean	isSnapshotEmpty(Serializable snapshot) Is the snapshot empty?
boolean	isUnreferenced() Is the collection unreferenced?
boolean	isWrapper(Object collection) Is this the wrapper for the given collection instance?
boolean	needsInserting(Object entry, int i, Type elemType) Do we need to insert this element?
boolean	needsRecreate(CollectionPersister persister) Do we need to completely recreate this collection when it changes?
boolean	needsUpdating(Object entry, int i, Type elemType) Do we need to update this element?
void	postAction() After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.
void	preInsert(CollectionPersister persister) Called before inserting rows, to ensure that any surrogate keys are fully generated
Iterator	queuedAdditionIterator() Iterator over the "queued" additions
Object	readFrom(ResultSet rs, CollectionPersister role, CollectionAliases descriptor, Object owner) Read a row from the JDBC result set
boolean	setCurrentSession(SharedSessionContractImplementor session) Associate the collection with the given session.
void	setOwner(Object entity) Set the reference to the owning entity
void	setSnapshot(Serializable key, String role, Serializable snapshot) After flushing, re-init snapshot state.
boolean	unsetSession(SharedSessionContractImplementor currentSession) Disassociate this collection from the given session.
boolean	wasInitialized() Is this instance initialized?

Method Detail

getOwner

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:

The owner

setOwner

void setOwner(Object entity)

Set the reference to the owning entity

Parameters:

entity - The owner

empty

boolean empty()

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

Returns:

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

setSnapshot

void setSnapshot(Serializable key,
                 String role,
                 Serializable snapshot)

After flushing, re-init snapshot state.

Parameters:

key - The collection instance key (fk value).

role - The collection role

snapshot - The snapshot state

postAction

void postAction()

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

getValue

Object getValue()

Return the user-visible collection (or array) instance

Returns:

The underlying collection/array

beginRead

void beginRead()

Called just before reading any rows from the JDBC result set

endRead

boolean endRead()

Called after reading all rows from the JDBC result set

Returns:

Whether to end the read.

afterInitialize

boolean afterInitialize()

Called after initializing from cache

Returns:

??

isDirectlyAccessible

boolean isDirectlyAccessible()

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

Returns:

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

unsetSession

boolean unsetSession(SharedSessionContractImplementor currentSession)

Disassociate this collection from the given session.

Parameters:

currentSession - The session we are disassociating from. Used for validations.

Returns:

true if this was currently associated with the given session

setCurrentSession

boolean setCurrentSession(SharedSessionContractImplementor session)
                   throws HibernateException

Associate the collection with the given session.

Parameters:

session - The session to associate with

Returns:

false if the collection was already associated with the session

Throws:

HibernateException - if the collection was already associated with another open session

initializeFromCache

void initializeFromCache(CollectionPersister persister,
                         Serializable disassembled,
                         Object owner)

Read the state of the collection from a disassembled cached value

Parameters:

persister - The collection persister

disassembled - The disassembled cached state

owner - The collection owner

entries

Iterator entries(CollectionPersister persister)

Iterate all collection entries, during update of the database

Parameters:

persister - The collection persister.

Returns:

The iterator

readFrom

Object readFrom(ResultSet rs,
                CollectionPersister role,
                CollectionAliases descriptor,
                Object owner)
         throws HibernateException,
                SQLException

Read a row from the JDBC result set

Parameters:

rs - The JDBC ResultSet

role - The collection role

descriptor - The aliases used for the columns making up the collection

owner - The collection owner

Returns:

The read object

Throws:

HibernateException - Generally indicates a problem resolving data read from the ResultSet

SQLException - Indicates a problem accessing the ResultSet

getIdentifier

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 - The collection entry/element

i - The assumed identifier (?)

Returns:

The identifier value

getIndex

Object getIndex(Object entry,
                int i,
                CollectionPersister persister)

Get the index of the given collection entry

Parameters:

entry - The collection entry/element

i - The assumed index

persister - it was more elegant before we added this...

Returns:

The index value

getElement

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 - The object instance for which to get the collection element instance.

Returns:

The corresponding object that is part of the collection elements.

getSnapshotElement

Object getSnapshotElement(Object entry,
                          int i)

Get the snapshot value of the given collection entry

Parameters:

entry - The entry

i - The index

Returns:

The snapshot state for that element

beforeInitialize

void beforeInitialize(CollectionPersister persister,
                      int anticipatedSize)

Called before any elements are read into the collection, allowing appropriate initializations to occur.

Parameters:

persister - The underlying collection persister.

anticipatedSize - The anticipated size of the collection after initialization is complete.

equalsSnapshot

boolean equalsSnapshot(CollectionPersister persister)

Does the current state exactly match the snapshot?

Parameters:

persister - The collection persister

Returns:

true if the current state and the snapshot state match.

isSnapshotEmpty

boolean isSnapshotEmpty(Serializable snapshot)

Is the snapshot empty?

Parameters:

snapshot - The snapshot to check

Returns:

true if the given snapshot is empty

disassemble

Serializable disassemble(CollectionPersister persister)

Disassemble the collection to get it ready for the cache

Parameters:

persister - The collection persister

Returns:

The disassembled state

needsRecreate

boolean needsRecreate(CollectionPersister persister)

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

Parameters:

persister - The collection persister

Returns:

true if a change requires a recreate.

getSnapshot

Serializable getSnapshot(CollectionPersister persister)

Return a new snapshot of the current state of the collection

Parameters:

persister - The collection persister

Returns:

The snapshot

forceInitialization

void forceInitialization()

To be called internally by the session, forcing immediate initialization.

entryExists

boolean entryExists(Object entry,
                    int i)

Does the given element/entry exist in the collection?

Parameters:

entry - The object to check if it exists as a collection element

i - Unused

Returns:

true if the given entry is a collection element

needsInserting

boolean needsInserting(Object entry,
                       int i,
                       Type elemType)

Do we need to insert this element?

Parameters:

entry - The collection element to check

i - The index (for indexed collections)

elemType - The type for the element

Returns:

true if the element needs inserting

needsUpdating

boolean needsUpdating(Object entry,
                      int i,
                      Type elemType)

Do we need to update this element?

Parameters:

entry - The collection element to check

i - The index (for indexed collections)

elemType - The type for the element

Returns:

true if the element needs updating

isRowUpdatePossible

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:

true if the row for each element is known

getDeletes

Iterator getDeletes(CollectionPersister persister,
                    boolean indexIsFormula)

Get all the elements that need deleting

Parameters:

persister - The collection persister

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

Returns:

An iterator over the elements to delete

isWrapper

boolean isWrapper(Object collection)

Is this the wrapper for the given collection instance?

Parameters:

collection - The collection to check whether this is wrapping it

Returns:

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

wasInitialized

boolean wasInitialized()

Is this instance initialized?

Returns:

Was this collection initialized? Or is its data still not (fully) loaded?

hasQueuedOperations

boolean hasQueuedOperations()

Does this instance have any "queued" operations?

Returns:

true indicates there are pending, queued, delayed operations

queuedAdditionIterator

Iterator queuedAdditionIterator()

Iterator over the "queued" additions

Returns:

The iterator

getQueuedOrphans

Collection getQueuedOrphans(String entityName)

Get the "queued" orphans

Parameters:

entityName - The name of the entity that makes up the elements

Returns:

The orphaned elements

getKey

Serializable getKey()

Get the current collection key value

Returns:

the current collection key value

getRole

String getRole()

Get the current role name

Returns:

the collection role name

isUnreferenced

boolean isUnreferenced()

Is the collection unreferenced?

Returns:

true if the collection is no longer referenced by an owner

isDirty

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:

true if the collection is dirty

isElementRemoved

default boolean isElementRemoved()

isDirectlyProvidedCollection

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 - The collection

Returns:

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

clearDirty

void clearDirty()

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

getStoredSnapshot

Serializable getStoredSnapshot()

Get the snapshot cached by the collection instance

Returns:

The internally stored snapshot state

dirty

void dirty()

Mark the collection as dirty

preInsert

void preInsert(CollectionPersister persister)

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

Parameters:

persister - The collection persister

afterRowInsert

void afterRowInsert(CollectionPersister persister,
                    Object entry,
                    int i)

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

Parameters:

persister - The collection persister

entry - The collection element just inserted

i - The element position/index

getOrphans

Collection getOrphans(Serializable snapshot,
                      String entityName)

get all "orphaned" elements

Parameters:

snapshot - The snapshot state

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

Returns:

The orphans