Package org.hibernate.collection.spi

Interface PersistentCollection<E>

Type Parameters:
E - the collection element type, or map value type
All Superinterfaces:
LazyInitializable
All Known Implementing Classes:
AbstractPersistentCollection, PersistentArrayHolder, PersistentBag, PersistentIdentifierBag, PersistentList, PersistentMap, PersistentSet, PersistentSortedMap, PersistentSortedSet
@Incubating public interface PersistentCollection<E> extends LazyInitializable
Persistent collections are treated as value objects by Hibernate. They have no independent existence beyond the entity 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 allows for tracking of changes to the persistent state of the collection and lazy fetching of the collection elements. The downside is that only certain abstract collection types are supported and any extra semantics associated with the particular implementation of the generic collection type are lost. For example, every List behaves like an ArrayList, and every SortedMap behaves like a TreeMap.

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 (composite elements) are discovered by cloning their state when the collection is initialized and comparing at flush time.

  • Method Details

    • getOwner

      @Nullable 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(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(@Nullable Object key, @Nullable String role, @Nullable 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

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

    • 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

    • entries

      Iterator<?> entries(CollectionPersister persister)
      Iterate all collection entries, during update of the database
      Parameters:
      persister - The collection persister.
      Returns:
      The iterator

    • getIdentifier

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

    • getIndex

      Object getIndex(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

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

      Object getSnapshotElement(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

    • 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(Serializable snapshot)
      Is the snapshot empty?
      Parameters:
      snapshot - The snapshot to check
      Returns:
      true if the given snapshot is empty

    • 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

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

    • entryExists

      boolean entryExists(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

    • includeInRecreate

      default boolean includeInRecreate(Object entry, int i, PersistentCollection<?> collection, PluralAttributeMapping attributeDescriptor)
      Whether the given entry should be included in recreation events
      API Note:
      Defined to match signature of InsertRowsCoordinator.EntryFilter.include(java.lang.Object, int, org.hibernate.collection.spi.PersistentCollection<?>, org.hibernate.metamodel.mapping.PluralAttributeMapping)

    • needsInserting

      boolean needsInserting(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

    • includeInInsert

      default boolean includeInInsert(Object entry, int entryPosition, PersistentCollection<?> collection, PluralAttributeMapping attributeDescriptor)
      Whether to include the entry for insertion operations
      API Note:
      Defined to match signature of InsertRowsCoordinator.EntryFilter.include(java.lang.Object, int, org.hibernate.collection.spi.PersistentCollection<?>, org.hibernate.metamodel.mapping.PluralAttributeMapping)

    • needsUpdating

      default boolean needsUpdating(Object entry, int entryPosition, PluralAttributeMapping attributeDescriptor)
      Do we need to update this element?
      Parameters:
      entry - The collection element to check
      entryPosition - The index (for indexed collections)
      attributeDescriptor - The type for the element
      Returns:
      true if the element needs updating

    • needsUpdating

      boolean needsUpdating(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

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

    • isInitializing

      boolean isInitializing()
      Is this PersistentCollection in the process of being initialized?

    • beforeInitialize

      void beforeInitialize(CollectionPersister persister, int anticipatedSize)
      Called prior to the initialization of this yet-uninitialized collection. Pairs with afterInitialize()

    • initializeFromCache

      void initializeFromCache(CollectionPersister persister, Object disassembled, 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

    • beginRead

      void beginRead()
      Called just before reading any rows from the JDBC result set. Pairs with endRead()

    • injectLoadedState

      void injectLoadedState(PluralAttributeMapping attributeMapping, List<?> loadingState)
      Inject the state loaded for a collection instance.

    • endRead

      boolean endRead()
      Called after reading all rows from the JDBC result set. Pairs with beginRead()
      See Also:

    • afterInitialize

      boolean afterInitialize()
      Called after initialization is complete. Pairs with beforeInitialize(org.hibernate.persister.collection.CollectionPersister, int)

    • disassemble

      Object disassemble(CollectionPersister persister)
      Disassemble the collection to get it ready for the cache
      Parameters:
      persister - The collection persister
      Returns:
      The disassembled state

    • hasQueuedOperations

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

    • queuedAdditionIterator

      Iterator<E> queuedAdditionIterator()
      Iterator over the "queued" additions
      Returns:
      The iterator

    • getQueuedOrphans

      Collection<E> getQueuedOrphans(String entityName)
      Get the "queued" orphans
      Parameters:
      entityName - The name of the entity that makes up the elements
      Returns:
      The orphaned elements

    • getKey

      @Nullable Object getKey()
      Get the current collection key value
      Returns:
      the current collection key value

    • getRole

      @Nullable 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(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

      @Nullable 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, 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

      Collection<E> getOrphans(Serializable snapshot, 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

    • getSize

      int getSize()
      Obtain the size of this collection without initializing it

    • elementExists

      boolean elementExists(Object element)
      Determine if the given element belongs to this collection without initializing it

    • elementByIndex

      Object elementByIndex(Object index)
      Obtain the element os this collection associated with the given index without initializing it

    • initializeEmptyCollection

      void initializeEmptyCollection(CollectionPersister persister)

    • isNewlyInstantiated

      default boolean isNewlyInstantiated()
      Is the collection newly instantiated?
      Returns:
      true if the collection is newly instantiated

    • render

      default String render()
      Like Object.toString() but without the silliness of rendering the elements