org.hibernate.collection

Interface PersistentCollection

Known Implementing Classes:
AbstractPersistentCollection, PersistentArrayHolder, PersistentBag, PersistentElementHolder, PersistentIdentifierBag, PersistentIndexedElementHolder, PersistentList, PersistentListElementHolder, PersistentMap, PersistentMapElementHolder, 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

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, 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 an element exist at this entry 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 index 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" additions?
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?
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.
boolean
isRowUpdatePossible()
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 underlying 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()
Iterate the "queued" additions
Object
readFrom(ResultSet rs, CollectionPersister role, CollectionAliases descriptor, Object owner)
Read a row from the JDBC result set
boolean
setCurrentSession(SessionImplementor 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(SessionImplementor currentSession)
Disassociate this collection from the given session.
boolean
wasInitialized()
Is this instance initialized?

Method Details

afterInitialize

public boolean afterInitialize()
Called after initializing from cache

afterRowInsert

public void afterRowInsert(CollectionPersister persister,
                           Object entry,
                           int i)
            throws HibernateException
Called after inserting a row, to fetch the natively generated id

beforeInitialize

public 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 initilization is complete.

beginRead

public void beginRead()
Called just before reading any rows from the JDBC result set

clearDirty

public void clearDirty()
Clear the dirty flag, after flushing changes to the database.

dirty

public void dirty()
Mark the collection as dirty

disassemble

public Serializable disassemble(CollectionPersister persister)
            throws HibernateException
Disassemble the collection, ready for the cache

empty

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

endRead

public boolean endRead()
Called after reading all rows from the JDBC result set

entries

public Iterator entries(CollectionPersister persister)
Iterate all collection entries, during update of the database

entryExists

public boolean entryExists(Object entry,
                           int i)
Does an element exist at this entry in the collection?

equalsSnapshot

public boolean equalsSnapshot(CollectionPersister persister)
            throws HibernateException
Does the current state exactly match the snapshot?

forceInitialization

public void forceInitialization()
            throws HibernateException
To be called internally by the session, forcing immediate initialization.

getDeletes

public Iterator getDeletes(CollectionPersister persister,
                           boolean indexIsFormula)
            throws HibernateException
Get all the elements that need deleting

getElement

public Object getElement(Object entry)
Get the value of the given collection entry

getIdentifier

public Object getIdentifier(Object entry,
                            int i)
Get the index of the given collection entry

getIndex

public Object getIndex(Object entry,
                       int i,
                       CollectionPersister persister)
Get the index of the given collection entry
Parameters:
persister - it was more elegant before we added this...

getKey

public Serializable getKey()
Get the current collection key value

getOrphans

public Collection getOrphans(Serializable snapshot,
                             String entityName)
            throws HibernateException
get all "orphaned" elements

getOwner

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.

getQueuedOrphans

public Collection getQueuedOrphans(String entityName)
Get the "queued" orphans

getRole

public String getRole()
Get the current role name

getSnapshot

public Serializable getSnapshot(CollectionPersister persister)
            throws HibernateException
Return a new snapshot of the current state of the collection

getSnapshotElement

public Object getSnapshotElement(Object entry,
                                 int i)
Get the snapshot value of the given collection entry

getStoredSnapshot

public Serializable getStoredSnapshot()
Get the snapshot cached by the collection instance

getValue

public Object getValue()
return the user-visible collection (or array) instance

hasQueuedOperations

public boolean hasQueuedOperations()
Does this instance have any "queued" additions?

initializeFromCache

public void initializeFromCache(CollectionPersister persister,
                                Serializable disassembled,
                                Object owner)
            throws HibernateException
Read the state of the collection from a disassembled cached value

isDirectlyAccessible

public boolean isDirectlyAccessible()
Could the application possibly have a direct reference to the underlying collection implementation?

isDirty

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.

isRowUpdatePossible

public boolean isRowUpdatePossible()

isSnapshotEmpty

public boolean isSnapshotEmpty(Serializable snapshot)
Is the snapshot empty?

isUnreferenced

public boolean isUnreferenced()
Is the collection unreferenced?

isWrapper

public boolean isWrapper(Object collection)
Is this the wrapper for the given underlying collection instance?

needsInserting

public boolean needsInserting(Object entry,
                              int i,
                              Type elemType)
            throws HibernateException
Do we need to insert this element?

needsRecreate

public boolean needsRecreate(CollectionPersister persister)
Do we need to completely recreate this collection when it changes?

needsUpdating

public boolean needsUpdating(Object entry,
                             int i,
                             Type elemType)
            throws HibernateException
Do we need to update this element?

postAction

public void postAction()
After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.

preInsert

public void preInsert(CollectionPersister persister)
            throws HibernateException
Called before inserting rows, to ensure that any surrogate keys are fully generated

queuedAdditionIterator

public Iterator queuedAdditionIterator()
Iterate the "queued" additions

readFrom

public Object readFrom(ResultSet rs,
                       CollectionPersister role,
                       CollectionAliases descriptor,
                       Object owner)
            throws HibernateException,
                   SQLException
Read a row from the JDBC result set

setCurrentSession

public boolean setCurrentSession(SessionImplementor session)
            throws HibernateException
Associate the collection with the given session.
Returns:
false if the collection was already associated with the session
Throws:
HibernateException - if the collection was already associated with another open session

setOwner

public void setOwner(Object entity)
Set the reference to the owning entity

setSnapshot

public void setSnapshot(Serializable key,
                        String role,
                        Serializable snapshot)
After flushing, re-init snapshot state.

unsetSession

public boolean unsetSession(SessionImplementor currentSession)
Disassociate this collection from the given session.
Returns:
true if this was currently associated with the given session

wasInitialized

public boolean wasInitialized()
Is this instance initialized?