org.hibernate.engine

Interface PersistenceContext

Known Implementing Classes:
StatefulPersistenceContext

public interface PersistenceContext

Holds the state of the persistence context, including the first-level cache, entries, snapshots, proxies, etc.
Author:
Gavin King

Method Summary

void
addCollectionHolder(PersistentCollection holder)
Register a PersistentCollection object for an array.
EntityEntry
addEntity(Object entity, Status status, Object[] loadedState, EntityKey entityKey, Object version, LockMode lockMode, boolean existsInDatabase, EntityPersister persister, boolean disableVersionIncrement, boolean lazyPropertiesAreUnfetched)
Adds an entity to the internal caches.
void
addEntity(EntityKey key, Object entity)
Add a canonical mapping from entity key to entity instance
void
addEntity(EntityUniqueKey euk, Object entity)
Add an entity to the cache by unique key
EntityEntry
addEntry(Object entity, Status status, Object[] loadedState, Object rowId, Serializable id, Object version, LockMode lockMode, boolean existsInDatabase, EntityPersister persister, boolean disableVersionIncrement, boolean lazyPropertiesAreUnfetched)
Generates an appropriate EntityEntry instance and adds it to the event source's internal caches.
CollectionEntry
addInitializedCollection(CollectionPersister persister, PersistentCollection collection, Serializable id)
add a collection we just pulled out of the cache (does not need initializing)
void
addInitializedDetachedCollection(CollectionPersister collectionPersister, PersistentCollection collection)
add an (initialized) collection that was created by another session and passed into update() (ie.
void
addNewCollection(CollectionPersister persister, PersistentCollection collection)
Add a new collection (ie.
void
addNonLazyCollection(PersistentCollection collection)
Register a collection for non-lazy loading at the end of the two-phase load
void
addNullProperty(EntityKey ownerKey, String propertyName)
Record the fact that the association belonging to the keyed entity is null.
void
addProxy(EntityKey key, Object proxy)
Add a proxy to the session cache
void
addUninitializedCollection(CollectionPersister persister, PersistentCollection collection, Serializable id)
add a collection we just loaded up (still needs initializing)
void
addUninitializedDetachedCollection(CollectionPersister persister, PersistentCollection collection)
add a detached uninitialized collection
void
addUnownedCollection(CollectionKey key, PersistentCollection collection)
Add a collection which has no owner loaded
void
afterLoad()
Call this after finishing a two-phase load
void
afterTransactionCompletion()
Called after transactions end
void
beforeLoad()
Call this before begining a two-phase load
void
checkUniqueness(EntityKey key, Object object)
Attempts to check whether the given key represents an entity already loaded within the current session.
void
clear()
Clear the state of the persistence context
boolean
containsCollection(PersistentCollection collection)
Is the given collection associated with this persistence context?
boolean
containsEntity(EntityKey key)
Is there an entity with the given key in the persistence context
boolean
containsProxy(Object proxy)
Is the given proxy associated with this persistence context?
int
decrementCascadeLevel()
Called after cascading
BatchFetchQueue
getBatchFetchQueue()
Get the BatchFetchQueue, instantiating one if necessary.
Object[]
getCachedDatabaseSnapshot(EntityKey key)
int
getCascadeLevel()
How deep are we cascaded?
PersistentCollection
getCollection(CollectionKey collectionKey)
Get the collection instance associated with the CollectionKey
Map
getCollectionEntries()
Get the mapping from collection instance to collection entry
CollectionEntry
getCollectionEntry(PersistentCollection coll)
Get the collection entry for a persistent collection
CollectionEntry
getCollectionEntryOrNull(Object collection)
Get the collection entry for a collection passed to filter, which might be a collection wrapper, an array, or an unwrapped collection.
PersistentCollection
getCollectionHolder(Object array)
Get the PersistentCollection object for an array
Object
getCollectionOwner(Serializable key, CollectionPersister collectionPersister)
Get the entity that owns this persistent collection
Map
getCollectionsByKey()
Get the mapping from collection key to collection instance
Object[]
getDatabaseSnapshot(Serializable id, EntityPersister persister)
Get the current state of the entity as known to the underlying database, or null if there is no corresponding row
Map
getEntitiesByKey()
Get the mapping from key value to entity instance
Object
getEntity(EntityKey key)
Get the entity instance associated with the given EntityKey
Object
getEntity(EntityUniqueKey euk)
Get an entity cached by unique key
Map
getEntityEntries()
Get the mapping from entity instance to entity entry
EntityEntry
getEntry(Object entity)
Retreive the EntityEntry representation of the given entity.
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
LoadContexts
getLoadContexts()
Retrieve this persistence context's managed load context.
Serializable
getLoadedCollectionOwnerIdOrNull(PersistentCollection collection)
Get the ID for the entity that owned this persistent collection when it was loaded
Object
getLoadedCollectionOwnerOrNull(PersistentCollection collection)
Get the entity that owned this persistent collection when it was loaded
Object[]
getNaturalIdSnapshot(Serializable 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.
HashSet
getNullifiableEntityKeys()
Retrieve the set of EntityKeys representing nullifiable references
Serializable
getOwnerId(String entity, String property, Object childObject, Map mergeMap)
Search the persistence context for an owner for the child object, given a collection role
Object
getProxy(EntityKey key)
Get an existing proxy by key
SessionImplementor
getSession()
Get the session to which this persistence context is bound.
Serializable
getSnapshot(PersistentCollection coll)
Get the snapshot of the pre-flush collection state
boolean
hasNonReadOnlyEntities()
int
incrementCascadeLevel()
Called before cascading
void
initializeNonLazyCollections()
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)
boolean
isEntryFor(Object entity)
Is there an EntityEntry for this instance?
boolean
isFlushing()
Is a flush cycle currently in process?
boolean
isPropertyNull(EntityKey ownerKey, String propertyName)
Is the association property belonging to the keyed entity null?
boolean
isStateless()
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.
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.
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.
boolean
reassociateIfUninitializedProxy(Object value)
Takes the given object and, if it represents a proxy, reassociates it with this event source.
void
reassociateProxy(Object value, Serializable id)
If a deleted entity instance is re-saved, and it has a proxy, we need to reset the identifier of the proxy
PersistentCollection
removeCollectionHolder(Object array)
Remove the mapping of collection to holder during eviction of the owning entity
Object
removeEntity(EntityKey key)
Remove an entity from the session cache, also clear up other state associated with the entity, all except for the EntityEntry
EntityEntry
removeEntry(Object entity)
Remove an entity entry from the session cache
Object
removeProxy(EntityKey key)
Remove a proxy from the session cache
void
replaceDelayedEntityIdentityInsertKeys(EntityKey oldKey, Serializable generatedId)
void
setEntryStatus(EntityEntry entry, Status status)
Set the status of an entry
void
setFlushing(boolean flushing)
Called before and after the flushcycle
void
setReadOnly(Object entity, boolean readOnly)
Set the object to read only and discard it's snapshot
String
toString()
Returns a string representation of the object.
Object
unproxy(Object maybeProxy)
Get the entity instance underlying the given proxy, throwing an exception if the proxy is uninitialized.
Object
unproxyAndReassociate(Object maybeProxy)
Possibly unproxy the given reference and reassociate it with the current session.
PersistentCollection
useUnownedCollection(CollectionKey key)
Get and remove a collection whose owner is not yet loaded, when its owner is being loaded

Method Details

addCollectionHolder

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

addEntity

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

addEntity

public void addEntity(EntityKey key,
                      Object entity)
Add a canonical mapping from entity key to entity instance

addEntity

public void addEntity(EntityUniqueKey euk,
                      Object entity)
Add an entity to the cache by unique key

addEntry

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

addInitializedCollection

public CollectionEntry addInitializedCollection(CollectionPersister persister,
                                                PersistentCollection collection,
                                                Serializable id)
            throws HibernateException
add a collection we just pulled out of the cache (does not need initializing)

addInitializedDetachedCollection

public void addInitializedDetachedCollection(CollectionPersister collectionPersister,
                                             PersistentCollection collection)
            throws HibernateException
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)

addNewCollection

public void addNewCollection(CollectionPersister persister,
                             PersistentCollection collection)
            throws HibernateException
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

addNonLazyCollection

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

addNullProperty

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

addProxy

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

addUninitializedCollection

public void addUninitializedCollection(CollectionPersister persister,
                                       PersistentCollection collection,
                                       Serializable id)
add a collection we just loaded up (still needs initializing)

addUninitializedDetachedCollection

public void addUninitializedDetachedCollection(CollectionPersister persister,
                                               PersistentCollection collection)
add a detached uninitialized collection

addUnownedCollection

public void addUnownedCollection(CollectionKey key,
                                 PersistentCollection collection)
Add a collection which has no owner loaded

afterLoad

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

afterTransactionCompletion

public void afterTransactionCompletion()
Called after transactions end

beforeLoad

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

checkUniqueness

public void checkUniqueness(EntityKey key,
                            Object object)
            throws HibernateException
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.

clear

public void clear()
Clear the state of the persistence context

containsCollection

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

containsEntity

public boolean containsEntity(EntityKey key)
Is there an entity with the given key in the persistence context

containsProxy

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

decrementCascadeLevel

public int decrementCascadeLevel()
Called after cascading

getBatchFetchQueue

public BatchFetchQueue getBatchFetchQueue()
Get the BatchFetchQueue, instantiating one if necessary.

getCachedDatabaseSnapshot

public Object[] getCachedDatabaseSnapshot(EntityKey key)

getCascadeLevel

public int getCascadeLevel()
How deep are we cascaded?

getCollection

public PersistentCollection getCollection(CollectionKey collectionKey)
Get the collection instance associated with the CollectionKey

getCollectionEntries

public Map getCollectionEntries()
Get the mapping from collection instance to collection entry

getCollectionEntry

public CollectionEntry getCollectionEntry(PersistentCollection coll)
Get the collection entry for a persistent collection

getCollectionEntryOrNull

public CollectionEntry getCollectionEntryOrNull(Object collection)
Get the collection entry for a collection passed to filter, which might be a collection wrapper, an array, or an unwrapped collection. Return null if there is no entry.

getCollectionHolder

public PersistentCollection getCollectionHolder(Object array)
Get the PersistentCollection object for an array

getCollectionOwner

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

getCollectionsByKey

public Map getCollectionsByKey()
Get the mapping from collection key to collection instance

getDatabaseSnapshot

public Object[] getDatabaseSnapshot(Serializable id,
                                    EntityPersister persister)
            throws HibernateException
Get the current state of the entity as known to the underlying database, or null if there is no corresponding row

getEntitiesByKey

public Map getEntitiesByKey()
Get the mapping from key value to entity instance

getEntity

public Object getEntity(EntityKey key)
Get the entity instance associated with the given EntityKey

getEntity

public Object getEntity(EntityUniqueKey euk)
Get an entity cached by unique key

getEntityEntries

public Map getEntityEntries()
Get the mapping from entity instance to entity entry

getEntry

public EntityEntry getEntry(Object entity)
Retreive the EntityEntry representation of the given entity.
Parameters:
entity - The entity for which to locate the EntityEntry.
Returns:
The EntityEntry for the given entity.

getIndexInOwner

public 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

getLoadContexts

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

getLoadedCollectionOwnerIdOrNull

public Serializable 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

getLoadedCollectionOwnerOrNull

public 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

getNaturalIdSnapshot

public Object[] getNaturalIdSnapshot(Serializable id,
                                     EntityPersister persister)
            throws HibernateException
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.

getNullifiableEntityKeys

public HashSet getNullifiableEntityKeys()
Retrieve the set of EntityKeys representing nullifiable references

getOwnerId

public Serializable getOwnerId(String entity,
                               String property,
                               Object childObject,
                               Map mergeMap)
Search the persistence context for an owner for the child object, given a collection role

getProxy

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

getSession

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

getSnapshot

public Serializable getSnapshot(PersistentCollection coll)
Get the snapshot of the pre-flush collection state

hasNonReadOnlyEntities

public boolean hasNonReadOnlyEntities()
Returns:
false if we know for certain that all the entities are read-only

incrementCascadeLevel

public int incrementCascadeLevel()
Called before cascading

initializeNonLazyCollections

public 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)

isEntryFor

public boolean isEntryFor(Object entity)
Is there an EntityEntry for this instance?

isFlushing

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

isPropertyNull

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

isStateless

public boolean isStateless()

narrowProxy

public Object narrowProxy(Object proxy,
                          EntityPersister persister,
                          EntityKey key,
                          Object object)
            throws HibernateException
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

public Object proxyFor(Object impl)
            throws HibernateException
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

public Object proxyFor(EntityPersister persister,
                       EntityKey key,
                       Object impl)
            throws HibernateException
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.

reassociateIfUninitializedProxy

public boolean reassociateIfUninitializedProxy(Object value)
            throws MappingException
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

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

removeCollectionHolder

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

removeEntity

public Object removeEntity(EntityKey key)
Remove an entity from the session cache, also clear up other state associated with the entity, all except for the EntityEntry

removeEntry

public EntityEntry removeEntry(Object entity)
Remove an entity entry from the session cache

removeProxy

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

replaceDelayedEntityIdentityInsertKeys

public void replaceDelayedEntityIdentityInsertKeys(EntityKey oldKey,
                                                   Serializable generatedId)

setEntryStatus

public void setEntryStatus(EntityEntry entry,
                           Status status)
Set the status of an entry

setFlushing

public void setFlushing(boolean flushing)
Called before and after the flushcycle

setReadOnly

public void setReadOnly(Object entity,
                        boolean readOnly)
Set the object to read only and discard it's snapshot

toString

public String toString()
Returns a string representation of the object.
Returns:
a string representation of the object.

unproxy

public Object unproxy(Object maybeProxy)
            throws HibernateException
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

public Object unproxyAndReassociate(Object maybeProxy)
            throws HibernateException
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.

useUnownedCollection

public PersistentCollection useUnownedCollection(CollectionKey key)
Get and remove a collection whose owner is not yet loaded, when its owner is being loaded