Top Description Methods
org.hibernate.collection

public Interface PersistentCollection

Known Direct Implementers
org.hibernate.collection.AbstractPersistentCollection
Imports
java.io.Serializable, java.sql.ResultSet, .SQLException, java.util.Collection, .Iterator, org.hibernate.HibernateException, org.hibernate.engine.SessionImplementor, org.hibernate.loader.CollectionAliases, org.hibernate.persister.collection.CollectionPersister, org.hibernate.type.Type
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 TypeMethod and Description
public boolean
afterInitialize()

Called after initializing from cache

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

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

public void
beforeInitialize(CollectionPersister
The underlying collection persister.
persister, int
The anticipated size of the collection after initilization is complete.
anticipatedSize)

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

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 Serializable
disassemble(CollectionPersister persister)

Disassemble the collection, ready for the cache

public boolean
empty()

Is the collection empty?

public boolean
endRead()

Called after reading all rows from the JDBC result set

public Iterator<E>
entries(CollectionPersister persister)

Iterate all collection entries, during update of the database

public boolean
entryExists(Object entry, int i)

Does an element exist at this entry in the collection?

public boolean
equalsSnapshot(CollectionPersister persister)

Does the current state exactly match the snapshot?

public void
forceInitialization()

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

public Iterator<E>
getDeletes(CollectionPersister persister, boolean indexIsFormula)

Get all the elements that need deleting

public Object
getElement(Object entry)

Get the value of the given collection entry

public Object
getIdentifier(Object entry, int i)

Get the index of the given collection entry

public Object
getIndex(Object entry, int i, CollectionPersister
it was more elegant before we added this...
persister)

Get the index of the given collection entry

public Serializable
getKey()

Get the current collection key value

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

get all "orphaned" elements

public Object
getOwner()

Get the owning entity.

public Collection<E>
getQueuedOrphans(String entityName)

Get the "queued" orphans

public String
getRole()

Get the current role name

public Serializable
getSnapshot(CollectionPersister persister)

Return a new snapshot of the current state of the collection

public Object
getSnapshotElement(Object entry, int i)

Get the snapshot value of the given collection entry

public Serializable
getStoredSnapshot()

Get the snapshot cached by the collection instance

public Object
getValue()

return the user-visible collection (or array) instance

public boolean
hasQueuedOperations()

Does this instance have any "queued" additions?

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

Read the state of the collection from a disassembled cached value

public boolean
isDirectlyAccessible()

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

public boolean
isDirty()

Is the collection dirty?

public boolean
isRowUpdatePossible()

public boolean
isSnapshotEmpty(Serializable snapshot)

Is the snapshot empty?

public boolean
isUnreferenced()

Is the collection unreferenced?

public boolean
isWrapper(Object collection)

Is this the wrapper for the given underlying collection instance?

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

Do we need to insert this element?

public boolean
needsRecreate(CollectionPersister persister)

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

public boolean
needsUpdating(Object entry, int i, Type 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 persister)

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

public Iterator<E>
queuedAdditionIterator()

Iterate the "queued" additions

public Object
readFrom(ResultSet rs, CollectionPersister role, CollectionAliases descriptor, Object owner)

Read a row from the JDBC result set

public boolean

Returns:

false if the collection was already associated with the session
setCurrentSession(SessionImplementor session)

Associate the collection with the given session.

public void
setOwner(Object entity)

Set the reference to the owning entity

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

After flushing, re-init snapshot state.

public boolean

Returns:

true if this was currently associated with the given session
unsetSession(SessionImplementor currentSession)

Disassociate this collection from the given session.

public boolean
wasInitialized()

Is this instance initialized?

Method Detail

afterInitializeback to summary
public boolean afterInitialize()

Called after initializing from cache

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

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

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

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

Parameters
persister:CollectionPersister

The underlying collection persister.

anticipatedSize:int

The anticipated size of the collection after initilization is complete.

beginReadback to summary
public void beginRead()

Called just before reading any rows from the JDBC result set

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 Serializable disassemble(CollectionPersister persister) throws HibernateException

Disassemble the collection, ready for the cache

emptyback to summary
public boolean empty()

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

endReadback to summary
public boolean endRead()

Called after reading all rows from the JDBC result set

entriesback to summary
public Iterator<E> entries(CollectionPersister persister)

Iterate all collection entries, during update of the database

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

Does an element exist at this entry in the collection?

equalsSnapshotback to summary
public boolean equalsSnapshot(CollectionPersister persister) throws HibernateException

Does the current state exactly match the snapshot?

forceInitializationback to summary
public void forceInitialization() throws HibernateException

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

getDeletesback to summary
public Iterator<E> getDeletes(CollectionPersister persister, boolean indexIsFormula) throws HibernateException

Get all the elements that need deleting

getElementback to summary
public Object getElement(Object entry)

Get the value of the given collection entry

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

Get the index of the given collection entry

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

Get the index of the given collection entry

Parameters
persister:CollectionPersister

it was more elegant before we added this...

getKeyback to summary
public Serializable getKey()

Get the current collection key value

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

get all "orphaned" elements

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.

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

Get the "queued" orphans

getRoleback to summary
public String getRole()

Get the current role name

getSnapshotback to summary
public Serializable getSnapshot(CollectionPersister persister) throws HibernateException

Return a new snapshot of the current state of the collection

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

Get the snapshot value of the given collection entry

getStoredSnapshotback to summary
public Serializable getStoredSnapshot()

Get the snapshot cached by the collection instance

getValueback to summary
public Object getValue()

return the user-visible collection (or array) instance

hasQueuedOperationsback to summary
public boolean hasQueuedOperations()

Does this instance have any "queued" additions?

initializeFromCacheback to summary
public void initializeFromCache(CollectionPersister persister, Serializable disassembled, Object owner) throws HibernateException

Read the state of the collection from a disassembled cached value

isDirectlyAccessibleback to summary
public boolean isDirectlyAccessible()

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

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.

isRowUpdatePossibleback to summary
public boolean isRowUpdatePossible()
isSnapshotEmptyback to summary
public boolean isSnapshotEmpty(Serializable snapshot)

Is the snapshot empty?

isUnreferencedback to summary
public boolean isUnreferenced()

Is the collection unreferenced?

isWrapperback to summary
public boolean isWrapper(Object collection)

Is this the wrapper for the given underlying collection instance?

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

Do we need to insert this element?

needsRecreateback to summary
public boolean needsRecreate(CollectionPersister persister)

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

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

Do we need to update this element?

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) throws HibernateException

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

queuedAdditionIteratorback to summary
public Iterator<E> queuedAdditionIterator()

Iterate the "queued" additions

readFromback to summary
public Object readFrom(ResultSet rs, CollectionPersister role, CollectionAliases descriptor, Object owner) throws HibernateException, SQLException

Read a row from the JDBC result set

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

Associate the collection with the given session.

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

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

After flushing, re-init snapshot state.

unsetSessionback to summary
public boolean unsetSession(SessionImplementor currentSession)

Disassociate this collection from the given session.

Returns:boolean

true if this was currently associated with the given session

wasInitializedback to summary
public boolean wasInitialized()

Is this instance initialized?