Package org.hibernate.collection

Interface PersistentCollection

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.

  • Method Details

    • 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