PersistentCollection (Hibernate Core Aggregator 3.6.10.Final API)

All 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

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

Interface PersistentCollection

Method Summary

Method Detail

getOwner

setOwner

empty

setSnapshot

postAction

getValue

beginRead

endRead

afterInitialize

isDirectlyAccessible

unsetSession

setCurrentSession

initializeFromCache

entries

readFrom

getIdentifier

getIndex

getElement

getSnapshotElement

beforeInitialize

equalsSnapshot

isSnapshotEmpty

disassemble

needsRecreate

getSnapshot

forceInitialization

entryExists

needsInserting

needsUpdating

isRowUpdatePossible

getDeletes

isWrapper

wasInitialized

hasQueuedOperations

queuedAdditionIterator

getQueuedOrphans

getKey

getRole

isUnreferenced

isDirty

clearDirty

getStoredSnapshot

dirty

preInsert

afterRowInsert

getOrphans