org.hibernate.collection
Interface PersistentCollection

All Known Implementing Classes:
AbstractPersistentCollection

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)
          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
 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.
 CollectionSnapshot getCollectionSnapshot()
          Returns the collectionSnapshot.
 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
 Collection getOrphans(Serializable snapshot, String entityName)
          get all "orphaned" elements
 Object getOwner()
           
 Serializable getSnapshot(CollectionPersister persister)
          Return a new snapshot of the current state of the collection, or null if no persister is passed
 Object getSnapshotElement(Object entry, int i)
          Get the snapshot value of the given collection entry
 Object getValue()
          return the user-visible collection (or array) instance
 boolean hasQueuedAdditions()
          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 isRowUpdatePossible()
           
 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 postFlush()
          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
 void setCollectionSnapshot(CollectionSnapshot collectionSnapshot)
          Sets the collectionSnapshot.
 boolean setCurrentSession(SessionImplementor session)
          Associate the collection with the given session.
 void setOwner(Object entity)
           
 boolean unsetSession(SessionImplementor currentSession)
          Disassociate this collection from the given session.
 boolean wasInitialized()
          Is this instance initialized?
 

Method Detail

getOwner

public Object getOwner()

setOwner

public void setOwner(Object entity)

empty

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


postFlush

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


getValue

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


beginRead

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


endRead

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


afterInitialize

public boolean afterInitialize()
Called after initializing from cache


isDirectlyAccessible

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


unsetSession

public boolean unsetSession(SessionImplementor currentSession)
Disassociate this collection from the given session.

Returns:
true if this was currently associated with the given session

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

initializeFromCache

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

Throws:
HibernateException

entries

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


readFrom

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

Throws:
HibernateException
SQLException

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...

getElement

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


getSnapshotElement

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


beforeInitialize

public void beforeInitialize(CollectionPersister persister)
Called before any elements are read into the collection, allowing appropriate initializations to occur.


equalsSnapshot

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

Throws:
HibernateException

disassemble

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

Throws:
HibernateException

needsRecreate

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


getSnapshot

public Serializable getSnapshot(CollectionPersister persister)
                         throws HibernateException
Return a new snapshot of the current state of the collection, or null if no persister is passed

Throws:
HibernateException

forceInitialization

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

Throws:
HibernateException

entryExists

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


needsInserting

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

Throws:
HibernateException

needsUpdating

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

Throws:
HibernateException

isRowUpdatePossible

public boolean isRowUpdatePossible()

getDeletes

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

Throws:
HibernateException

isWrapper

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


wasInitialized

public boolean wasInitialized()
Is this instance initialized?


hasQueuedAdditions

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


queuedAdditionIterator

public Iterator queuedAdditionIterator()
Iterate the "queued" additions


getCollectionSnapshot

public CollectionSnapshot getCollectionSnapshot()
Returns the collectionSnapshot.

Returns:
CollectionSnapshot

setCollectionSnapshot

public void setCollectionSnapshot(CollectionSnapshot collectionSnapshot)
Sets the collectionSnapshot.

Parameters:
collectionSnapshot - The collectionSnapshot to set

preInsert

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

Throws:
HibernateException

afterRowInsert

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

Throws:
HibernateException

getOrphans

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

Throws:
HibernateException