Package org.hibernate.engine.spi

Interface PersistenceContext

public interface PersistenceContext
Represents the state of "stuff" Hibernate is tracking, including (not exhaustive):
  • entities
  • collections
  • snapshots
  • proxies

Often referred to as the "first level cache".

  • Field Details

    • NO_ROW

      static final Object NO_ROW
      Marker object used to indicate (via reference checking) that no row was returned.

  • Method Details

    • isStateless

      boolean isStateless()

    • getSession

      SharedSessionContractImplementor getSession()
      Get the session to which this persistence context is bound.
      Returns:
      The session.

    • getLoadContexts

      LoadContexts getLoadContexts()
      Retrieve this persistence context's managed load context.
      Returns:
      The load context

    • hasLoadContext

      default boolean hasLoadContext()

    • useUnownedCollection

      PersistentCollection<?> useUnownedCollection(CollectionKey key)
      Take ownership of a previously unowned collection, if one. This method returns null if no such collection was previously added () or was previously removed.

      This should indicate the owner is being loaded and we are ready to "link" them.

      Parameters:
      key - The collection key for which to locate a collection collection
      Returns:
      The unowned collection, or null

    • getBatchFetchQueue

      BatchFetchQueue getBatchFetchQueue()
      Get the BatchFetchQueue, instantiating one if necessary.
      Returns:
      The batch fetch queue in effect for this persistence context

    • clear

      void clear()
      Clear the state of the persistence context

    • setEntryStatus

      void setEntryStatus(EntityEntry entry, Status status)
      Set the status of an entry
      Parameters:
      entry - The entry for which to set the status
      status - The new status

    • afterTransactionCompletion

      void afterTransactionCompletion()
      Called after transactions end

    • getDatabaseSnapshot

      Object[] getDatabaseSnapshot(Object id, EntityPersister persister)
      Get the current state of the entity as known to the underlying database, or null if there is no corresponding row. This operation might result in a select query being executed against the database.
      Parameters:
      id - The identifier of the entity for which to grab a snapshot
      persister - The persister of the entity.
      Returns:
      The entity's (non-cached) snapshot
      See Also:

    • getCachedDatabaseSnapshot

      Object[] getCachedDatabaseSnapshot(EntityKey key)
      Retrieve the cached database snapshot for the requested entity key.

      This differs from getDatabaseSnapshot(java.lang.Object, org.hibernate.persister.entity.EntityPersister) in two important ways:

      1. no snapshot is obtained from the database if not already cached, and
      2. an entry of NO_ROW here results in an exception.
      Parameters:
      key - The entity key for which to retrieve the cached snapshot
      Returns:
      The cached snapshot
      Throws:
      IllegalStateException - if the cached snapshot was NO_ROW.

    • getNaturalIdSnapshot

      Object getNaturalIdSnapshot(Object id, EntityPersister persister)
      Get the values of the natural id fields as known to the underlying database, or null if the entity has no natural id or there is no corresponding row.
      Parameters:
      id - The identifier of the entity for which to grab a snapshot
      persister - The persister of the entity.
      Returns:
      The current (non-cached) snapshot of the entity's natural id state.

    • addEntity

      void addEntity(EntityKey key, Object entity)
      Add a canonical mapping from entity key to entity instance
      Parameters:
      key - The key under which to add an entity
      entity - The entity instance to add

    • getEntity

      Object getEntity(EntityKey key)
      Get the entity instance associated with the given key
      Parameters:
      key - The key under which to look for an entity
      Returns:
      The matching entity, or null

    • containsEntity

      boolean containsEntity(EntityKey key)
      Is there an entity with the given key in the persistence context
      Parameters:
      key - The key under which to look for an entity
      Returns:
      true indicates an entity was found; otherwise false

    • removeEntity

      Object removeEntity(EntityKey key)
      Remove an entity. Also clears up all other state associated with the entity aside from the EntityEntry
      Parameters:
      key - The key whose matching entity should be removed
      Returns:
      The matching entity

    • addEntity

      void addEntity(EntityUniqueKey euk, Object entity)
      Add an entity to the cache by unique key
      Parameters:
      euk - The unique (non-primary) key under which to add an entity
      entity - The entity instance

    • getEntity

      Object getEntity(EntityUniqueKey euk)
      Get an entity cached by unique key
      Parameters:
      euk - The unique (non-primary) key under which to look for an entity
      Returns:
      The located entity

    • getEntry

      EntityEntry getEntry(Object entity)
      Retrieve the EntityEntry representation of the given entity.
      Parameters:
      entity - The entity instance for which to locate the corresponding entry
      Returns:
      The entry

    • removeEntry

      EntityEntry removeEntry(Object entity)
      Remove an entity entry from the session cache
      Parameters:
      entity - The entity instance for which to remove the corresponding entry
      Returns:
      The matching entry

    • isEntryFor

      boolean isEntryFor(Object entity)
      Is there an EntityEntry registration for this entity instance?
      Parameters:
      entity - The entity instance for which to check for an entry
      Returns:
      true indicates a matching entry was found.

    • getCollectionEntry

      CollectionEntry getCollectionEntry(PersistentCollection<?> coll)
      Get the collection entry for a persistent collection
      Parameters:
      coll - The persistent collection instance for which to locate the collection entry
      Returns:
      The matching collection entry

    • addEntity

      EntityEntry addEntity(Object entity, Status status, Object[] loadedState, EntityKey entityKey, Object version, LockMode lockMode, boolean existsInDatabase, EntityPersister persister, boolean disableVersionIncrement)
      Adds an entity to the internal caches.

    • addEntry

      EntityEntry addEntry(Object entity, Status status, Object[] loadedState, Object rowId, Object id, Object version, LockMode lockMode, boolean existsInDatabase, EntityPersister persister, boolean disableVersionIncrement)
      Generates an appropriate EntityEntry instance and adds it to the event source's internal caches.

    • addReferenceEntry

      EntityEntry addReferenceEntry(Object entity, Status status)

    • containsCollection

      boolean containsCollection(PersistentCollection<?> collection)
      Is the given collection associated with this persistence context?

    • containsProxy

      boolean containsProxy(Object proxy)
      Is the given proxy associated with this persistence context?

    • reassociateIfUninitializedProxy

      boolean reassociateIfUninitializedProxy(Object value)
      Takes the given object and, if it represents a proxy, reassociates it with this event source.
      Parameters:
      value - The possible proxy to be reassociated.
      Returns:
      Whether the passed value represented an actual proxy which got initialized.

    • reassociateProxy

      void reassociateProxy(Object value, Object id)
      If a deleted entity instance is re-saved, and it has a proxy, we need to reset the identifier of the proxy

    • unproxy

      Object unproxy(Object maybeProxy)
      Get the entity instance underlying the given proxy, throwing an exception if the proxy is uninitialized. If the given object is not a proxy, simply return the argument.

    • unproxyAndReassociate

      Object unproxyAndReassociate(Object maybeProxy)
      Possibly unproxy the given reference and reassociate it with the current session.
      Parameters:
      maybeProxy - The reference to be unproxied if it currently represents a proxy.
      Returns:
      The unproxied instance.

    • checkUniqueness

      void checkUniqueness(EntityKey key, Object object)
      Attempts to check whether the given key represents an entity already loaded within the current session.
      Parameters:
      object - The entity reference against which to perform the uniqueness check.

    • narrowProxy

      Object narrowProxy(Object proxy, EntityPersister persister, EntityKey key, Object object)
      If the existing proxy is insufficiently "narrow" (derived), instantiate a new proxy and overwrite the registration of the old one. This breaks == and occurs only for "class" proxies rather than "interface" proxies. Also init the proxy to point to the given target implementation if necessary.
      Parameters:
      proxy - The proxy instance to be narrowed.
      persister - The persister for the proxied entity.
      key - The internal cache key for the proxied entity.
      object - (optional) the actual proxied entity instance.
      Returns:
      An appropriately narrowed instance.

    • proxyFor

      Object proxyFor(EntityPersister persister, EntityKey key, Object impl)
      Return the existing proxy associated with the given EntityKey, or the third argument (the entity associated with the key) if no proxy exists. Init the proxy to the target implementation, if necessary.

    • proxyFor

      Object proxyFor(Object impl)
      Return the existing proxy associated with the given EntityKey, or the argument (the entity associated with the key) if no proxy exists. (slower than the form above)

    • proxyFor

      Object proxyFor(EntityHolder holder, EntityPersister persister)
      Return the existing proxy associated with the given EntityHolder, or the entity if no proxy exists.

    • addEnhancedProxy

      void addEnhancedProxy(EntityKey key, PersistentAttributeInterceptable entity)
      Cross between addEntity(EntityKey, Object) and addProxy(EntityKey, Object) for use with enhancement-as-proxy

    • getCollectionOwner

      Object getCollectionOwner(Object key, CollectionPersister collectionPersister)
      Get the entity that owns this persistent collection

    • getLoadedCollectionOwnerOrNull

      Object getLoadedCollectionOwnerOrNull(PersistentCollection<?> collection)
      Get the entity that owned this persistent collection when it was loaded
      Parameters:
      collection - The persistent collection
      Returns:
      the owner if its entity ID is available from the collection's loaded key and the owner entity is in the persistence context; otherwise, returns null

    • getLoadedCollectionOwnerIdOrNull

      Object getLoadedCollectionOwnerIdOrNull(PersistentCollection<?> collection)
      Get the ID for the entity that owned this persistent collection when it was loaded
      Parameters:
      collection - The persistent collection
      Returns:
      the owner ID if available from the collection's loaded key; otherwise, returns null

    • addUninitializedCollection

      void addUninitializedCollection(CollectionPersister persister, PersistentCollection<?> collection, Object id)
      add a collection we just loaded up (still needs initializing)

    • addUninitializedDetachedCollection

      void addUninitializedDetachedCollection(CollectionPersister persister, PersistentCollection<?> collection)
      add a detached uninitialized collection

    • addNewCollection

      void addNewCollection(CollectionPersister persister, PersistentCollection<?> collection)
      Add a new collection (ie. a newly created one, just instantiated by the application, with no database state or snapshot)
      Parameters:
      collection - The collection to be associated with the persistence context

    • addInitializedDetachedCollection

      void addInitializedDetachedCollection(CollectionPersister collectionPersister, PersistentCollection<?> collection)
      add an (initialized) collection that was created by another session and passed into update() (ie. one with a snapshot and existing state on the database)

    • replaceCollection

      void replaceCollection(CollectionPersister persister, PersistentCollection<?> oldCollection, PersistentCollection<?> collection)
      Replaces a directly accessible collection with the given one
      Parameters:
      oldCollection -
      collection - The collection to be associated with the persistence context
      Since:
      7.0

    • addInitializedCollection

      CollectionEntry addInitializedCollection(CollectionPersister persister, PersistentCollection<?> collection, Object id)
      add a collection we just pulled out of the cache (does not need initializing)

    • getCollection

      PersistentCollection<?> getCollection(CollectionKey collectionKey)
      Get the collection instance associated with the CollectionKey

    • addNonLazyCollection

      void addNonLazyCollection(PersistentCollection<?> collection)
      Register a collection for non-lazy loading at the end of the two-phase load

    • initializeNonLazyCollections

      void initializeNonLazyCollections() throws HibernateException
      Force initialization of all non-lazy collections encountered during the current two-phase load (actually, this is a no-op, unless this is the "outermost" load)
      Throws:
      HibernateException

    • initializeNonLazyCollections

      void initializeNonLazyCollections(Consumer<PersistentCollection<?>> initializeAction)
      Force initialization of all non-lazy collections encountered during the current two-phase load (actually, this is a no-op, unless this is the "outermost" load) allowing to customize how the initialization should occur
      Parameters:
      initializeAction - the function that initialize the collection
      See Also:

    • getCollectionHolder

      PersistentCollection<?> getCollectionHolder(Object array)
      Get the PersistentCollection object for an array

    • addCollectionHolder

      void addCollectionHolder(PersistentCollection<?> holder)
      Register a PersistentCollection object for an array. Associates a holder with an array - MUST be called after loading array, since the array instance is not created until endLoad().

    • removeCollectionHolder

      PersistentCollection<?> removeCollectionHolder(Object array)
      Remove the mapping of collection to holder during eviction of the owning entity

    • getSnapshot

      Serializable getSnapshot(PersistentCollection<?> coll)
      Get the snapshot of the pre-flush collection state

    • getProxy

      Object getProxy(EntityKey key)
      Get an existing proxy by key

    • addProxy

      void addProxy(EntityKey key, Object proxy)
      Add a proxy to the session cache

    • removeProxy

      Object removeProxy(EntityKey key)
      Remove a proxy from the session cache.

      Additionally, ensure that any load optimization references such as batch or subselect loading get cleaned up as well.

      Parameters:
      key - The key of the entity proxy to be removed
      Returns:
      The proxy reference.

    • claimEntityHolderIfPossible

      @Incubating EntityHolder claimEntityHolderIfPossible(EntityKey key, @Nullable Object entity, JdbcValuesSourceProcessingState processingState, EntityInitializer<?> initializer)
      Return an existing entity holder for the entity key, possibly creating one if necessary. Will claim the entity holder by registering the given entity initializer, if it isn't claimed yet.
      Parameters:
      key - The key under which to add an entity
      entity - The entity instance to add
      processingState - The processing state which initializes the entity if successfully claimed
      initializer - The initializer to claim the entity instance

    • addEntityHolder

      @Incubating EntityHolder addEntityHolder(EntityKey key, Object entity)

    • getEntityHolder

      @Nullable EntityHolder getEntityHolder(EntityKey key)

    • containsEntityHolder

      boolean containsEntityHolder(EntityKey key)

    • removeEntityHolder

      @Nullable EntityHolder removeEntityHolder(EntityKey key)

    • postLoad

      @Incubating void postLoad(JdbcValuesSourceProcessingState processingState, Consumer<EntityHolder> loadedConsumer)

    • getEntitiesByKey

      @Internal Map<EntityKey,Object> getEntitiesByKey()
      Doubly internal

    • getEntitySnapshotsByKey

      @Internal Map<EntityKey,Object> getEntitySnapshotsByKey()

    • getOrInitializeEntitySnapshotsByKey

      @Internal Map<EntityKey,Object> getOrInitializeEntitySnapshotsByKey()

    • getEntityHoldersByKey

      @Internal Map<EntityKey,EntityHolder> getEntityHoldersByKey()
      Doubly internal

    • reentrantSafeEntityEntries

      Map.Entry<Object,EntityEntry>[] reentrantSafeEntityEntries()
      Provides access to the entity/EntityEntry combos associated with the persistence context in a manner that is safe from reentrant access. Specifically, it is safe from additions/removals while iterating.

    • getNumberOfManagedEntities

      int getNumberOfManagedEntities()

    • getCollectionEntries

      @Internal @Nullable Map<PersistentCollection<?>,CollectionEntry> getCollectionEntries()
      Doubly internal

    • forEachCollectionEntry

      void forEachCollectionEntry(BiConsumer<PersistentCollection<?>,CollectionEntry> action, boolean concurrent)
      Execute some action on each entry of the collectionEntries map, optionally iterating on a defensive copy.
      Parameters:
      action - the lambda to apply on each PersistentCollection,CollectionEntry map entry of the PersistenceContext.
      concurrent - set this to false for improved efficiency, but that would make it illegal to make changes to the underlying collectionEntries map.

    • getCollectionsByKey

      @Deprecated Map<CollectionKey,PersistentCollection<?>> getCollectionsByKey()
      Deprecated.
      this method should be removed; alternative methods are available that better express the intent, allowing for better optimisations. Not aggressively removing this as it's an SPI, but also useful for testing and other contexts which are not performance sensitive. N.B. This might return an immutable map: do not use for mutations!
      Get the mapping from collection key to collection instance

    • getCascadeLevel

      int getCascadeLevel()
      How deep are we cascaded?

    • incrementCascadeLevel

      int incrementCascadeLevel()
      Called before cascading

    • decrementCascadeLevel

      int decrementCascadeLevel()
      Called after cascading

    • isFlushing

      boolean isFlushing()
      Is a flush cycle currently in process?

    • setFlushing

      void setFlushing(boolean flushing)
      Called before and after the flush cycle

    • beforeLoad

      void beforeLoad()
      Call this before beginning a two-phase load

    • afterLoad

      void afterLoad()
      Call this after finishing a two-phase load

    • isLoadFinished

      boolean isLoadFinished()
      Is in a two-phase load?

    • toString

      String toString()
      Returns a string representation of the object.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the object.

    • getOwnerId

      Object getOwnerId(String entityName, String propertyName, Object childEntity, Map mergeMap)
      Search this persistence context for an associated entity instance which is considered the "owner" of the given childEntity, and return that owner's id value. This is performed in the scenario of a uni-directional, non-inverse one-to-many collection (which means that the collection elements do not maintain a direct reference to the owner).

      As such, the processing here is basically to loop over every entity currently associated with this persistence context and for those of the correct entity (sub) type to extract its collection role property value and see if the child is contained within that collection. If so, we have found the owner; if not, we go on.

      Also need to account for mergeMap which acts as a local copy cache managed for the duration of a merge operation. It represents a map of the detached entity instances pointing to the corresponding managed instance.

      Parameters:
      entityName - The entity name for the entity type which would own the child
      propertyName - The name of the property on the owning entity type which would name this child association.
      childEntity - The child entity instance for which to locate the owner instance id.
      mergeMap - A map of non-persistent instances from an on-going merge operation (possibly null).
      Returns:
      The id of the entityName instance which is said to own the child; null if an appropriate owner not located.

    • getIndexInOwner

      Object getIndexInOwner(String entity, String property, Object childObject, Map mergeMap)
      Search the persistence context for an index of the child object, given a collection role

    • addNullProperty

      void addNullProperty(EntityKey ownerKey, String propertyName)
      Record the fact that the association belonging to the keyed entity is null.

    • isPropertyNull

      boolean isPropertyNull(EntityKey ownerKey, String propertyName)
      Is the association property belonging to the keyed entity null?

    • isDefaultReadOnly

      boolean isDefaultReadOnly()
      Will entities and proxies that are loaded into this persistence context be made read-only by default?

      To determine the read-only/modifiable setting for a particular entity or proxy, call isReadOnly(Object).

      Returns:
      true, loaded entities/proxies will be made read-only by default; false, loaded entities/proxies will be made modifiable by default.
      See Also:

    • setDefaultReadOnly

      void setDefaultReadOnly(boolean readOnly)
      Change the default for entities and proxies loaded into this persistence context from modifiable to read-only mode, or from read-only mode to modifiable.

      Read-only entities are not dirty-checked and snapshots of persistent state are not maintained. Read-only entities can be modified, but changes are not persisted.

      When a proxy is initialized, the loaded entity will have the same read-only/modifiable setting as the uninitialized proxy has, regardless of the persistence context's current setting.

      To change the read-only/modifiable setting for a particular entity or proxy that is already in this session, call setReadOnly(Object,boolean).

      Parameters:
      readOnly - true, the default for loaded entities/proxies is read-only; false, the default for loaded entities/proxies is modifiable
      See Also:

    • isReadOnly

      boolean isReadOnly(Object entityOrProxy)
      Is the entity or proxy read-only?

      To determine the default read-only/modifiable setting used for entities and proxies that are loaded into the session use Session.isDefaultReadOnly()

      Parameters:
      entityOrProxy - an entity or proxy
      Returns:
      true if the object is read-only; otherwise false to indicate that the object is modifiable.

    • setReadOnly

      void setReadOnly(Object entityOrProxy, boolean readOnly)
      Set an unmodified persistent object to read-only mode, or a read-only object to modifiable mode.

      Read-only entities are not dirty-checked and snapshots of persistent state are not maintained. Read-only entities can be modified, but changes are not persisted.

      When a proxy is initialized, the loaded entity will have the same read-only/modifiable setting as the uninitialized proxy has, regardless of the session's current setting.

      If the entity or proxy already has the specified read-only/modifiable setting, then this method does nothing.

      Parameters:
      entityOrProxy - an entity or proxy
      readOnly - if true, the entity or proxy is made read-only; otherwise, the entity or proxy is made modifiable.
      See Also:

    • isRemovingOrphanBeforeUpdates

      boolean isRemovingOrphanBeforeUpdates()

    • beginRemoveOrphanBeforeUpdates

      void beginRemoveOrphanBeforeUpdates()

    • endRemoveOrphanBeforeUpdates

      void endRemoveOrphanBeforeUpdates()

    • replaceDelayedEntityIdentityInsertKeys

      void replaceDelayedEntityIdentityInsertKeys(EntityKey oldKey, Object generatedId)

    • replaceEntityEntryRowId

      @Internal void replaceEntityEntryRowId(Object entity, Object rowId)

    • addChildParent

      void addChildParent(Object child, Object parent)
      Add a child/parent relation to cache for cascading op
      Parameters:
      child - The child of the relationship
      parent - The parent of the relationship

    • removeChildParent

      void removeChildParent(Object child)
      Remove child/parent relation from cache
      Parameters:
      child - The child to be removed.

    • registerInsertedKey

      void registerInsertedKey(EntityPersister persister, Object id)
      Register keys inserted during the current transaction
      Parameters:
      persister - The entity persister
      id - The id

    • wasInsertedDuringTransaction

      boolean wasInsertedDuringTransaction(EntityPersister persister, Object id)
      Allows callers to check to see if the identified entity was inserted during the current transaction.
      Parameters:
      persister - The entity persister
      id - The id
      Returns:
      True if inserted during this transaction, false otherwise.

    • containsNullifiableEntityKey

      boolean containsNullifiableEntityKey(Supplier<EntityKey> sek)
      Checks if a certain EntityKey was registered as nullifiable on this PersistenceContext.
      Parameters:
      sek - a supplier for the EntityKey; this allows to not always needing to create the key; for example if the map is known to be empty there is no need to create one to check.
      Returns:
      true if the EntityKey had been registered before using registerNullifiableEntityKey(EntityKey)
      See Also:

    • registerNullifiableEntityKey

      void registerNullifiableEntityKey(EntityKey key)
      Registers an EntityKey as nullifiable on this PersistenceContext.

    • isNullifiableEntityKeysEmpty

      boolean isNullifiableEntityKeysEmpty()
      Returns:
      true if no EntityKey was registered as nullifiable on this PersistenceContext.
      See Also:

    • containsDeletedUnloadedEntityKey

      boolean containsDeletedUnloadedEntityKey(EntityKey ek)

    • registerDeletedUnloadedEntityKey

      void registerDeletedUnloadedEntityKey(EntityKey key)

    • removeDeletedUnloadedEntityKey

      void removeDeletedUnloadedEntityKey(EntityKey key)

    • containsDeletedUnloadedEntityKeys

      boolean containsDeletedUnloadedEntityKeys()

    • getCollectionEntriesSize

      int getCollectionEntriesSize()
      The size of the internal map storing all collection entries. (The map is not exposed directly, but the size is often useful)
      Returns:
      the size

    • removeCollectionEntry

      CollectionEntry removeCollectionEntry(PersistentCollection<?> collection)
      Remove a PersistentCollection from the PersistenceContext.
      Parameters:
      collection - the collection to remove
      Returns:
      the matching CollectionEntry, if any was removed.

    • clearCollectionsByKey

      void clearCollectionsByKey()
      Remove all state of the collections-by-key map.

    • addCollectionByKey

      PersistentCollection<?> addCollectionByKey(CollectionKey collectionKey, PersistentCollection<?> persistentCollection)
      Adds a collection in the collections-by-key map.
      Returns:
      the previous collection, it the key was already mapped.

    • removeCollectionByKey

      void removeCollectionByKey(CollectionKey collectionKey)
      Remove a collection-by-key mapping.
      Parameters:
      collectionKey - the key to clear

    • managedEntitiesIterator

      Iterator<Object> managedEntitiesIterator()
      A read-only iterator on all entities managed by this persistence context

    • getNaturalIdResolutions

      NaturalIdResolutions getNaturalIdResolutions()
      Access to the natural-id helper for this persistence context
      Returns:
      This persistence context's natural-id helper

    • detachEntity

      default @Nullable EntityHolder detachEntity(EntityKey key)
      Remove the EntityHolder and set its state to DETACHED.