PersistentCollection
| org.hibernate.collection.PersistentCollection |
 Known Indirect Subclasses
|
Class Overview
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.
Summary
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Called after initializing from cache
| |||||||||||
Called after inserting a row, to fetch the natively generated id
| |||||||||||
Called before any elements are read into the collection,
allowing appropriate initializations to occur.
| |||||||||||
Called just before reading any rows from the JDBC result set
| |||||||||||
Clear the dirty flag, after flushing changes
to the database.
| |||||||||||
Mark the collection as dirty
| |||||||||||
Disassemble the collection, ready for the cache
| |||||||||||
Is the collection empty? (don't try to initialize the collection)
| |||||||||||
Called after reading all rows from the JDBC result set
| |||||||||||
Iterate all collection entries, during update of the database
| |||||||||||
Does an element exist at this entry in the collection?
| |||||||||||
Does the current state exactly match the snapshot?
| |||||||||||
To be called internally by the session, forcing
immediate initialization.
| |||||||||||
Get all the elements that need deleting
| |||||||||||
Get the value of the given collection entry
| |||||||||||
Get the index of the given collection entry
| |||||||||||
Get the index of the given collection entry
| |||||||||||
Get the current collection key value
| |||||||||||
get all "orphaned" elements
| |||||||||||
Get the owning entity.
| |||||||||||
Get the "queued" orphans
| |||||||||||
Get the current role name
| |||||||||||
Return a new snapshot of the current state of the collection
| |||||||||||
Get the snapshot value of the given collection entry
| |||||||||||
Get the snapshot cached by the collection
instance
| |||||||||||
return the user-visible collection (or array) instance
| |||||||||||
Does this instance have any "queued" additions?
| |||||||||||
Read the state of the collection from a disassembled cached value
| |||||||||||
Could the application possibly have a direct reference to
the underlying collection implementation?
| |||||||||||
Is the collection dirty? Note that this is only
reliable during the flush cycle, after the
collection elements are dirty checked against
the snapshot.
| |||||||||||
Is the snapshot empty?
| |||||||||||
Is the collection unreferenced?
| |||||||||||
Is this the wrapper for the given underlying collection instance?
| |||||||||||
Do we need to insert this element?
| |||||||||||
Do we need to completely recreate this collection when it changes?
| |||||||||||
Do we need to update this element?
| |||||||||||
After flushing, clear any "queued" additions, since the
database state is now synchronized with the memory state.
| |||||||||||
Called before inserting rows, to ensure that any surrogate keys
are fully generated
| |||||||||||
Iterate the "queued" additions
| |||||||||||
Read a row from the JDBC result set
| |||||||||||
Associate the collection with the given session.
| |||||||||||
Set the reference to the owning entity
| |||||||||||
After flushing, re-init snapshot state.
| |||||||||||
Disassociate this collection from the given session.
| |||||||||||
Is this instance initialized?
| |||||||||||
Public Methods
public abstract boolean afterInitialize ()
Called after initializing from cache
public abstract void afterRowInsert (CollectionPersister persister, Object entry, int i)
Called after inserting a row, to fetch the natively generated id
Throws
| HibernateException |
|---|
public abstract 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. |
public abstract void beginRead ()
Called just before reading any rows from the JDBC result set
public abstract void clearDirty ()
Clear the dirty flag, after flushing changes to the database.
public abstract void dirty ()
Mark the collection as dirty
public abstract Serializable disassemble (CollectionPersister persister)
Disassemble the collection, ready for the cache
Throws
| HibernateException |
|---|
public abstract boolean empty ()
Is the collection empty? (don't try to initialize the collection)
public abstract boolean endRead ()
Called after reading all rows from the JDBC result set
public abstract Iterator entries (CollectionPersister persister)
Iterate all collection entries, during update of the database
public abstract boolean entryExists (Object entry, int i)
Does an element exist at this entry in the collection?
public abstract boolean equalsSnapshot (CollectionPersister persister)
Does the current state exactly match the snapshot?
Throws
| HibernateException |
|---|
public abstract void forceInitialization ()
To be called internally by the session, forcing immediate initialization.
Throws
| HibernateException |
|---|
public abstract Iterator getDeletes (CollectionPersister persister, boolean indexIsFormula)
Get all the elements that need deleting
Throws
| HibernateException |
|---|
public abstract Object getIdentifier (Object entry, int i)
Get the index of the given collection entry
public abstract 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... |
|---|
public abstract Collection getOrphans (Serializable snapshot, String entityName)
get all "orphaned" elements
Throws
| HibernateException |
|---|
public abstract 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.
public abstract Serializable getSnapshot (CollectionPersister persister)
Return a new snapshot of the current state of the collection
Throws
| HibernateException |
|---|
public abstract Object getSnapshotElement (Object entry, int i)
Get the snapshot value of the given collection entry
public abstract Serializable getStoredSnapshot ()
Get the snapshot cached by the collection instance
public abstract boolean hasQueuedOperations ()
Does this instance have any "queued" additions?
public abstract void initializeFromCache (CollectionPersister persister, Serializable disassembled, Object owner)
Read the state of the collection from a disassembled cached value
Throws
| HibernateException |
|---|
public abstract boolean isDirectlyAccessible ()
Could the application possibly have a direct reference to the underlying collection implementation?
public abstract 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.
public abstract boolean isRowUpdatePossible ()
public abstract boolean isUnreferenced ()
Is the collection unreferenced?
public abstract boolean isWrapper (Object collection)
Is this the wrapper for the given underlying collection instance?
public abstract boolean needsInserting (Object entry, int i, Type elemType)
Do we need to insert this element?
Throws
| HibernateException |
|---|
public abstract boolean needsRecreate (CollectionPersister persister)
Do we need to completely recreate this collection when it changes?
public abstract boolean needsUpdating (Object entry, int i, Type elemType)
Do we need to update this element?
Throws
| HibernateException |
|---|
public abstract void postAction ()
After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.
public abstract void preInsert (CollectionPersister persister)
Called before inserting rows, to ensure that any surrogate keys are fully generated
Throws
| HibernateException |
|---|
public abstract Object readFrom (ResultSet rs, CollectionPersister role, CollectionAliases descriptor, Object owner)
Read a row from the JDBC result set
Throws
| HibernateException | |
|---|---|
| SQLException |
public abstract boolean setCurrentSession (SessionImplementor session)
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 |
|---|
public abstract void setSnapshot (Serializable key, String role, Serializable snapshot)
After flushing, re-init snapshot state.
public abstract boolean unsetSession (SessionImplementor currentSession)
Disassociate this collection from the given session.
Returns
- true if this was currently associated with the given session
public abstract boolean wasInitialized ()
Is this instance initialized?