Package org.hibernate.collection.spi

Interface 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.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      boolean afterInitialize()
      Called after initializing from cache
      void afterRowInsert​(CollectionPersister persister, java.lang.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
      java.io.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
      java.util.Iterator entries​(CollectionPersister persister)
      Iterate all collection entries, during update of the database
      boolean entryExists​(java.lang.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.
      java.util.Iterator getDeletes​(CollectionPersister persister, boolean indexIsFormula)
      Get all the elements that need deleting
      java.lang.Object getElement​(java.lang.Object entry)
      Get the value of the given collection entry.
      java.lang.Object getIdentifier​(java.lang.Object entry, int i)
      Get the identifier of the given collection entry.
      java.lang.Object getIndex​(java.lang.Object entry, int i, CollectionPersister persister)
      Get the index of the given collection entry
      java.io.Serializable getKey()
      Get the current collection key value
      java.util.Collection getOrphans​(java.io.Serializable snapshot, java.lang.String entityName)
      get all "orphaned" elements
      java.lang.Object getOwner()
      Get the owning entity.
      java.util.Collection getQueuedOrphans​(java.lang.String entityName)
      Get the "queued" orphans
      java.lang.String getRole()
      Get the current role name
      java.io.Serializable getSnapshot​(CollectionPersister persister)
      Return a new snapshot of the current state of the collection
      java.lang.Object getSnapshotElement​(java.lang.Object entry, int i)
      Get the snapshot value of the given collection entry
      java.io.Serializable getStoredSnapshot()
      Get the snapshot cached by the collection instance
      java.lang.Object getValue()
      Return the user-visible collection (or array) instance
      boolean hasQueuedOperations()
      Does this instance have any "queued" operations?
      void initializeFromCache​(CollectionPersister persister, java.io.Serializable disassembled, java.lang.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?
      default boolean isDirectlyProvidedCollection​(java.lang.Object collection)
      Was collection provided directly to this PersistentCollection (i.e., provided as an argument to a constructor)?
      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​(java.io.Serializable snapshot)
      Is the snapshot empty?
      boolean isUnreferenced()
      Is the collection unreferenced?
      boolean isWrapper​(java.lang.Object collection)
      Is this the wrapper for the given collection instance?
      boolean needsInserting​(java.lang.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​(java.lang.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
      java.util.Iterator queuedAdditionIterator()
      Iterator over the "queued" additions
      java.lang.Object readFrom​(java.sql.ResultSet rs, CollectionPersister role, CollectionAliases descriptor, java.lang.Object owner)
      Read a row from the JDBC result set
      boolean setCurrentSession​(SharedSessionContractImplementor session)
      Associate the collection with the given session.
      void setOwner​(java.lang.Object entity)
      Set the reference to the owning entity
      void setSnapshot​(java.io.Serializable key, java.lang.String role, java.io.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?

    • Method Detail

      • getOwner

        java.lang.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.
        Returns:
        The owner

      • setOwner

        void setOwner​(java.lang.Object entity)
        Set the reference to the owning entity
        Parameters:
        entity - The owner

      • empty

        boolean empty()
        Is the collection empty? (don't try to initialize the collection)
        Returns:
        false if the collection is non-empty; true otherwise.

      • setSnapshot

        void setSnapshot​(java.io.Serializable key,
                 java.lang.String role,
                 java.io.Serializable snapshot)
        After flushing, re-init snapshot state.
        Parameters:
        key - The collection instance key (fk value).
        role - The collection role
        snapshot - The snapshot state

      • postAction

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

      • getValue

        java.lang.Object getValue()
        Return the user-visible collection (or array) instance
        Returns:
        The underlying collection/array

      • 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
        Returns:
        Whether to end the read.

      • afterInitialize

        boolean afterInitialize()
        Called after initializing from cache
        Returns:
        ??

      • isDirectlyAccessible

        boolean isDirectlyAccessible()
        Could the application possibly have a direct reference to the underlying collection implementation?
        Returns:
        true indicates that the application might have access to the underlying collection/array.

      • unsetSession

        boolean unsetSession​(SharedSessionContractImplementor currentSession)
        Disassociate this collection from the given session.
        Parameters:
        currentSession - The session we are disassociating from. Used for validations.
        Returns:
        true if this was currently associated with the given session

      • setCurrentSession

        boolean setCurrentSession​(SharedSessionContractImplementor session)
                   throws HibernateException
        Associate the collection with the given session.
        Parameters:
        session - The session to associate with
        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,
                         java.io.Serializable disassembled,
                         java.lang.Object owner)
        Read the state of the collection from a disassembled cached value
        Parameters:
        persister - The collection persister
        disassembled - The disassembled cached state
        owner - The collection owner

      • entries

        java.util.Iterator entries​(CollectionPersister persister)
        Iterate all collection entries, during update of the database
        Parameters:
        persister - The collection persister.
        Returns:
        The iterator

      • readFrom

        java.lang.Object readFrom​(java.sql.ResultSet rs,
                          CollectionPersister role,
                          CollectionAliases descriptor,
                          java.lang.Object owner)
                   throws HibernateException,
                          java.sql.SQLException
        Read a row from the JDBC result set
        Parameters:
        rs - The JDBC ResultSet
        role - The collection role
        descriptor - The aliases used for the columns making up the collection
        owner - The collection owner
        Returns:
        The read object
        Throws:
        HibernateException - Generally indicates a problem resolving data read from the ResultSet
        java.sql.SQLException - Indicates a problem accessing the ResultSet

      • getIdentifier

        java.lang.Object getIdentifier​(java.lang.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.
        Parameters:
        entry - The collection entry/element
        i - The assumed identifier (?)
        Returns:
        The identifier value

      • getIndex

        java.lang.Object getIndex​(java.lang.Object entry,
                          int i,
                          CollectionPersister persister)
        Get the index of the given collection entry
        Parameters:
        entry - The collection entry/element
        i - The assumed index
        persister - it was more elegant before we added this...
        Returns:
        The index value

      • getElement

        java.lang.Object getElement​(java.lang.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.
        Parameters:
        entry - The object instance for which to get the collection element instance.
        Returns:
        The corresponding object that is part of the collection elements.

      • getSnapshotElement

        java.lang.Object getSnapshotElement​(java.lang.Object entry,
                                    int i)
        Get the snapshot value of the given collection entry
        Parameters:
        entry - The entry
        i - The index
        Returns:
        The snapshot state for that element

      • 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 initialization is complete.

      • equalsSnapshot

        boolean equalsSnapshot​(CollectionPersister persister)
        Does the current state exactly match the snapshot?
        Parameters:
        persister - The collection persister
        Returns:
        true if the current state and the snapshot state match.

      • isSnapshotEmpty

        boolean isSnapshotEmpty​(java.io.Serializable snapshot)
        Is the snapshot empty?
        Parameters:
        snapshot - The snapshot to check
        Returns:
        true if the given snapshot is empty

      • disassemble

        java.io.Serializable disassemble​(CollectionPersister persister)
        Disassemble the collection to get it ready for the cache
        Parameters:
        persister - The collection persister
        Returns:
        The disassembled state

      • needsRecreate

        boolean needsRecreate​(CollectionPersister persister)
        Do we need to completely recreate this collection when it changes?
        Parameters:
        persister - The collection persister
        Returns:
        true if a change requires a recreate.

      • getSnapshot

        java.io.Serializable getSnapshot​(CollectionPersister persister)
        Return a new snapshot of the current state of the collection
        Parameters:
        persister - The collection persister
        Returns:
        The snapshot

      • forceInitialization

        void forceInitialization()
        To be called internally by the session, forcing immediate initialization.

      • entryExists

        boolean entryExists​(java.lang.Object entry,
                    int i)
        Does the given element/entry exist in the collection?
        Parameters:
        entry - The object to check if it exists as a collection element
        i - Unused
        Returns:
        true if the given entry is a collection element

      • needsInserting

        boolean needsInserting​(java.lang.Object entry,
                       int i,
                       Type elemType)
        Do we need to insert this element?
        Parameters:
        entry - The collection element to check
        i - The index (for indexed collections)
        elemType - The type for the element
        Returns:
        true if the element needs inserting

      • needsUpdating

        boolean needsUpdating​(java.lang.Object entry,
                      int i,
                      Type elemType)
        Do we need to update this element?
        Parameters:
        entry - The collection element to check
        i - The index (for indexed collections)
        elemType - The type for the element
        Returns:
        true if the element needs updating

      • isRowUpdatePossible

        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.
        Returns:
        true if the row for each element is known

      • getDeletes

        java.util.Iterator getDeletes​(CollectionPersister persister,
                              boolean indexIsFormula)
        Get all the elements that need deleting
        Parameters:
        persister - The collection persister
        indexIsFormula - For indexed collections, tells whether the index is a formula (calculated value) mapping
        Returns:
        An iterator over the elements to delete

      • isWrapper

        boolean isWrapper​(java.lang.Object collection)
        Is this the wrapper for the given collection instance?
        Parameters:
        collection - The collection to check whether this is wrapping it
        Returns:
        true if this is a wrapper around that given collection instance.

      • wasInitialized

        boolean wasInitialized()
        Is this instance initialized?
        Returns:
        Was this collection initialized? Or is its data still not (fully) loaded?

      • hasQueuedOperations

        boolean hasQueuedOperations()
        Does this instance have any "queued" operations?
        Returns:
        true indicates there are pending, queued, delayed operations

      • queuedAdditionIterator

        java.util.Iterator queuedAdditionIterator()
        Iterator over the "queued" additions
        Returns:
        The iterator

      • getQueuedOrphans

        java.util.Collection getQueuedOrphans​(java.lang.String entityName)
        Get the "queued" orphans
        Parameters:
        entityName - The name of the entity that makes up the elements
        Returns:
        The orphaned elements

      • getKey

        java.io.Serializable getKey()
        Get the current collection key value
        Returns:
        the current collection key value

      • getRole

        java.lang.String getRole()
        Get the current role name
        Returns:
        the collection role name

      • isUnreferenced

        boolean isUnreferenced()
        Is the collection unreferenced?
        Returns:
        true if the collection is no longer referenced by an owner

      • 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.
        Returns:
        true if the collection is dirty

      • isElementRemoved

        default boolean isElementRemoved()

      • isDirectlyProvidedCollection

        default boolean isDirectlyProvidedCollection​(java.lang.Object collection)
        Was collection provided directly to this PersistentCollection (i.e., provided as an argument to a constructor)?

        Implementors that can copy elements out of a directly provided collection into the wrapped collection should override this method.

        Parameters:
        collection - The collection
        Returns:
        true, if collection was provided directly to this PersistentCollection; false, otherwise.

      • clearDirty

        void clearDirty()
        Clear the dirty flag, after flushing changes to the database.

      • getStoredSnapshot

        java.io.Serializable getStoredSnapshot()
        Get the snapshot cached by the collection instance
        Returns:
        The internally stored snapshot state

      • dirty

        void dirty()
        Mark the collection as dirty

      • preInsert

        void preInsert​(CollectionPersister persister)
        Called before inserting rows, to ensure that any surrogate keys are fully generated
        Parameters:
        persister - The collection persister

      • afterRowInsert

        void afterRowInsert​(CollectionPersister persister,
                    java.lang.Object entry,
                    int i)
        Called after inserting a row, to fetch the natively generated id
        Parameters:
        persister - The collection persister
        entry - The collection element just inserted
        i - The element position/index

      • getOrphans

        java.util.Collection getOrphans​(java.io.Serializable snapshot,
                                java.lang.String entityName)
        get all "orphaned" elements
        Parameters:
        snapshot - The snapshot state
        entityName - The name of the entity that are the elements of the collection
        Returns:
        The orphans