FileDocCategorySizeDatePackage
PersistentCollection.javaAPI DocHibernate 3.2.58354Wed Jul 05 13:17:28 BST 2006org.hibernate.collection

PersistentCollection

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

Fields Summary
Constructors Summary
Methods Summary
public booleanafterInitialize()
Called after initializing from cache

public voidafterRowInsert(org.hibernate.persister.collection.CollectionPersister persister, java.lang.Object entry, int i)
Called after inserting a row, to fetch the natively generated id

public voidbeforeInitialize(org.hibernate.persister.collection.CollectionPersister persister, int anticipatedSize)
Called before any elements are read into the collection, allowing appropriate initializations to occur.

param
persister The underlying collection persister.
param
anticipatedSize The anticipated size of the collection after initilization is complete.

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

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

public voiddirty()
Mark the collection as dirty

public java.io.Serializabledisassemble(org.hibernate.persister.collection.CollectionPersister persister)
Disassemble the collection, ready for the cache

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

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

public java.util.Iteratorentries(org.hibernate.persister.collection.CollectionPersister persister)
Iterate all collection entries, during update of the database

public booleanentryExists(java.lang.Object entry, int i)
Does an element exist at this entry in the collection?

public booleanequalsSnapshot(org.hibernate.persister.collection.CollectionPersister persister)
Does the current state exactly match the snapshot?

public voidforceInitialization()
To be called internally by the session, forcing immediate initialization.

public java.util.IteratorgetDeletes(org.hibernate.persister.collection.CollectionPersister persister, boolean indexIsFormula)
Get all the elements that need deleting

public java.lang.ObjectgetElement(java.lang.Object entry)
Get the value of the given collection entry

public java.lang.ObjectgetIdentifier(java.lang.Object entry, int i)
Get the index of the given collection entry

public java.lang.ObjectgetIndex(java.lang.Object entry, int i, org.hibernate.persister.collection.CollectionPersister persister)
Get the index of the given collection entry

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

public java.io.SerializablegetKey()
Get the current collection key value

public java.util.CollectiongetOrphans(java.io.Serializable snapshot, java.lang.String entityName)
get all "orphaned" elements

public java.lang.ObjectgetOwner()
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.

public java.util.CollectiongetQueuedOrphans(java.lang.String entityName)
Get the "queued" orphans

public java.lang.StringgetRole()
Get the current role name

public java.io.SerializablegetSnapshot(org.hibernate.persister.collection.CollectionPersister persister)
Return a new snapshot of the current state of the collection

public java.lang.ObjectgetSnapshotElement(java.lang.Object entry, int i)
Get the snapshot value of the given collection entry

public java.io.SerializablegetStoredSnapshot()
Get the snapshot cached by the collection instance

public java.lang.ObjectgetValue()
return the user-visible collection (or array) instance

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

public voidinitializeFromCache(org.hibernate.persister.collection.CollectionPersister persister, java.io.Serializable disassembled, java.lang.Object owner)
Read the state of the collection from a disassembled cached value

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

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

public booleanisRowUpdatePossible()

public booleanisSnapshotEmpty(java.io.Serializable snapshot)
Is the snapshot empty?

public booleanisUnreferenced()
Is the collection unreferenced?

public booleanisWrapper(java.lang.Object collection)
Is this the wrapper for the given underlying collection instance?

public booleanneedsInserting(java.lang.Object entry, int i, org.hibernate.type.Type elemType)
Do we need to insert this element?

public booleanneedsRecreate(org.hibernate.persister.collection.CollectionPersister persister)
Do we need to completely recreate this collection when it changes?

public booleanneedsUpdating(java.lang.Object entry, int i, org.hibernate.type.Type elemType)
Do we need to update this element?

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

public voidpreInsert(org.hibernate.persister.collection.CollectionPersister persister)
Called before inserting rows, to ensure that any surrogate keys are fully generated

public java.util.IteratorqueuedAdditionIterator()
Iterate the "queued" additions

public java.lang.ObjectreadFrom(java.sql.ResultSet rs, org.hibernate.persister.collection.CollectionPersister role, org.hibernate.loader.CollectionAliases descriptor, java.lang.Object owner)
Read a row from the JDBC result set

public booleansetCurrentSession(org.hibernate.engine.SessionImplementor session)
Associate the collection with the given session.

return
false if the collection was already associated with the session
throws
HibernateException if the collection was already associated with another open session

public voidsetOwner(java.lang.Object entity)
Set the reference to the owning entity

public voidsetSnapshot(java.io.Serializable key, java.lang.String role, java.io.Serializable snapshot)
After flushing, re-init snapshot state.

public booleanunsetSession(org.hibernate.engine.SessionImplementor currentSession)
Disassociate this collection from the given session.

return
true if this was currently associated with the given session

public booleanwasInitialized()
Is this instance initialized?