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.<br> <br> 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<br> <br> Applications should <em>never</em> use classes in this package directly, unless extending the "framework" here.<br> <br> Changes to <em>structure</em> 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.
Modifier and Type | Method and Description |
---|---|
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 to get it 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 the given element/entry exist 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 identifier 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" operations?
|
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.
|
default boolean |
isElementRemoved() |
boolean |
isRowUpdatePossible()
Can each element in the collection be mapped unequivocally to a single row in the database? Generally
bags and sets are the only collections that cannot be.
|
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 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()
Iterator over the "queued" additions
|
Object |
readFrom(ResultSet rs,
CollectionPersister role,
CollectionAliases descriptor,
Object owner)
Read a row from the JDBC result set
|
boolean |
setCurrentSession(SharedSessionContractImplementor 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(SharedSessionContractImplementor currentSession)
Disassociate this collection from the given session.
|
boolean |
wasInitialized()
Is this instance initialized?
|
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.
void setOwner(Object entity)
Set the reference to the owning entity
entity
- The ownerboolean empty()
Is the collection empty? (don’t try to initialize the collection)
false
if the collection is non-empty; true
otherwise.void setSnapshot(Serializable key, String role, Serializable snapshot)
After flushing, re-init snapshot state.
key
- The collection instance key (fk value).role
- The collection rolesnapshot
- The snapshot statevoid postAction()
After flushing, clear any "queued" additions, since the database state is now synchronized with the memory state.
Object getValue()
Return the user-visible collection (or array) instance
void beginRead()
Called just before reading any rows from the JDBC result set
boolean endRead()
Called after reading all rows from the JDBC result set
boolean afterInitialize()
Called after initializing from cache
boolean isDirectlyAccessible()
Could the application possibly have a direct reference to the underlying collection implementation?
true
indicates that the application might have access to the underlying collection/array.boolean unsetSession(SharedSessionContractImplementor currentSession)
Disassociate this collection from the given session.
currentSession
- The session we are disassociating from. Used for validations.boolean setCurrentSession(SharedSessionContractImplementor session) throws HibernateException
Associate the collection with the given session.
session
- The session to associate withHibernateException
- if the collection was already associated
with another open sessionvoid initializeFromCache(CollectionPersister persister, Serializable disassembled, Object owner)
Read the state of the collection from a disassembled cached value
persister
- The collection persisterdisassembled
- The disassembled cached stateowner
- The collection ownerIterator entries(CollectionPersister persister)
Iterate all collection entries, during update of the database
persister
- The collection persister.Object readFrom(ResultSet rs, CollectionPersister role, CollectionAliases descriptor, Object owner) throws HibernateException, SQLException
Read a row from the JDBC result set
rs
- The JDBC ResultSetrole
- The collection roledescriptor
- The aliases used for the columns making up the collectionowner
- The collection ownerHibernateException
- Generally indicates a problem resolving data read from the ResultSetSQLException
- Indicates a problem accessing the ResultSetObject getIdentifier(Object entry, int i)
Get the identifier of the given collection entry. This refers to the collection identifier, not the
identifier of the (possibly) entity elements. This is only valid for invocation on the
idbag
collection.
entry
- The collection entry/elementi
- The assumed identifier (?)Object getIndex(Object entry, int i, CollectionPersister persister)
Get the index of the given collection entry
entry
- The collection entry/elementi
- The assumed indexpersister
- it was more elegant before we added this…Object getElement(Object entry)
Get the value of the given collection entry. Generally the given entry parameter value will just be returned. Might get a different value for a duplicate entries in a Set.
entry
- The object instance for which to get the collection element instance.Object getSnapshotElement(Object entry, int i)
Get the snapshot value of the given collection entry
entry
- The entryi
- The indexvoid beforeInitialize(CollectionPersister persister, int anticipatedSize)
Called before any elements are read into the collection, allowing appropriate initializations to occur.
persister
- The underlying collection persister.anticipatedSize
- The anticipated size of the collection after initialization is complete.boolean equalsSnapshot(CollectionPersister persister)
Does the current state exactly match the snapshot?
persister
- The collection persistertrue
if the current state and the snapshot state match.boolean isSnapshotEmpty(Serializable snapshot)
Is the snapshot empty?
snapshot
- The snapshot to checktrue
if the given snapshot is emptySerializable disassemble(CollectionPersister persister)
Disassemble the collection to get it ready for the cache
persister
- The collection persisterboolean needsRecreate(CollectionPersister persister)
Do we need to completely recreate this collection when it changes?
persister
- The collection persistertrue
if a change requires a recreate.Serializable getSnapshot(CollectionPersister persister)
Return a new snapshot of the current state of the collection
persister
- The collection persistervoid forceInitialization()
To be called internally by the session, forcing immediate initialization.
boolean entryExists(Object entry, int i)
Does the given element/entry exist in the collection?
entry
- The object to check if it exists as a collection elementi
- Unusedtrue
if the given entry is a collection elementboolean needsInserting(Object entry, int i, Type elemType)
Do we need to insert this element?
entry
- The collection element to checki
- The index (for indexed collections)elemType
- The type for the elementtrue
if the element needs insertingboolean needsUpdating(Object entry, int i, Type elemType)
Do we need to update this element?
entry
- The collection element to checki
- The index (for indexed collections)elemType
- The type for the elementtrue
if the element needs updatingboolean isRowUpdatePossible()
Can each element in the collection be mapped unequivocally to a single row in the database? Generally bags and sets are the only collections that cannot be.
true
if the row for each element is knownIterator getDeletes(CollectionPersister persister, boolean indexIsFormula)
Get all the elements that need deleting
persister
- The collection persisterindexIsFormula
- For indexed collections, tells whether the index is a formula (calculated value) mappingboolean isWrapper(Object collection)
Is this the wrapper for the given collection instance?
collection
- The collection to check whether this is wrapping ittrue
if this is a wrapper around that given collection instance.boolean wasInitialized()
Is this instance initialized?
boolean hasQueuedOperations()
Does this instance have any "queued" operations?
true
indicates there are pending, queued, delayed operationsIterator queuedAdditionIterator()
Iterator over the "queued" additions
Collection getQueuedOrphans(String entityName)
Get the "queued" orphans
entityName
- The name of the entity that makes up the elementsSerializable getKey()
Get the current collection key value
String getRole()
Get the current role name
boolean isUnreferenced()
Is the collection unreferenced?
true
if the collection is no longer referenced by an ownerboolean 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.
true
if the collection is dirtydefault boolean isElementRemoved()
void clearDirty()
Clear the dirty flag, after flushing changes to the database.
Serializable getStoredSnapshot()
Get the snapshot cached by the collection instance
void dirty()
Mark the collection as dirty
void preInsert(CollectionPersister persister)
Called before inserting rows, to ensure that any surrogate keys are fully generated
persister
- The collection persistervoid afterRowInsert(CollectionPersister persister, Object entry, int i)
Called after inserting a row, to fetch the natively generated id
persister
- The collection persisterentry
- The collection element just insertedi
- The element position/indexCollection getOrphans(Serializable snapshot, String entityName)
get all "orphaned" elements
snapshot
- The snapshot stateentityName
- The name of the entity that are the elements of the collectionCopyright © 2001-2018 Red Hat, Inc. All Rights Reserved.