Interface CachedDomainDataAccess

All Known Subinterfaces:

CollectionDataAccess, EntityDataAccess, NaturalIdDataAccess

All Known Implementing Classes:

AbstractCachedDomainDataAccess, AbstractCollectionDataAccess, AbstractEntityDataAccess, AbstractNaturalIdDataAccess, AbstractReadWriteAccess, CollectionNonStrictReadWriteAccess, CollectionReadOnlyAccess, CollectionReadWriteAccess, CollectionTransactionAccess, EntityNonStrictReadWriteAccess, EntityReadOnlyAccess, EntityReadWriteAccess, EntityTransactionalAccess, NaturalIdNonStrictReadWriteAccess, NaturalIdReadOnlyAccess, NaturalIdReadWriteAccess, NaturalIdTransactionalAccess

public interface CachedDomainDataAccess

Base contract for accessing the cached data for a particular element of the domain model in a transactionally ACID manner.

API Note:

Note that the following methods are not considered "transactional" in this sense: contains(Object), lockRegion(), unlockRegion(SoftLock), evict(Object), evictAll(). The semantics of these methods come from JPA's Cache contract.

Implementation Specification:

The "non-transactional" methods noted in the @apiNote should be implemented to ignore any locking. That is, when evict(Object) is called, the item should be forcibly removed from the cache regardless of whether anything has locked it.

Method Summary

Modifier and Type	Method	Description
boolean	contains(Object key)	Determine whether this region contains data for the given key.
void	evict(Object key)	Forcibly evict an item from the cache immediately without regard for transaction isolation and/or locking.
void	evictAll()	Forcibly evict all items from the cache immediately without regard for transaction isolation.
Object	get(SharedSessionContractImplementor session, Object key)	Attempt to retrieve an object from the cache.
AccessType	getAccessType()	The type of access implemented
DomainDataRegion	getRegion()	The region containing the data being accessed
SoftLock	lockItem(SharedSessionContractImplementor session, Object key, Object version)	Notify before an attempt to update or delete the keyed object.
SoftLock	lockRegion()	Lock the entire region
boolean	putFromLoad(SharedSessionContractImplementor session, Object key, Object value, Object version)	Attempt to cache an object, after loading it from the database.
boolean	putFromLoad(SharedSessionContractImplementor session, Object key, Object value, Object version, boolean minimalPutOverride)	Attempt to cache an object, after loading from the database, explicitly specifying the minimalPut behavior.
void	remove(SharedSessionContractImplementor session, Object key)	Notify that an item has become stale, before completion of the transaction.
void	removeAll(SharedSessionContractImplementor session)	Remove all data for this accessed type.
void	unlockItem(SharedSessionContractImplementor session, Object key, SoftLock lock)	Notify that an attempt to update or delete the keyed object has completed, with or without success, after transaction completion.
void	unlockRegion(SoftLock lock)	Called after we have finished the attempted invalidation of the entire region

Method Details

getRegion

@Nonnull
DomainDataRegion getRegion()

The region containing the data being accessed

getAccessType

@Nonnull
AccessType getAccessType()

The type of access implemented

get

@Nullable
Object get(@Nonnull
 SharedSessionContractImplementor session,
 @Nonnull
 Object key)

Attempt to retrieve an object from the cache. Usually used when attempting to resolve an entity or collection from the second-level cache.

Parameters:

session - Current session.

key - The key of the item to be retrieved.

Returns:

the cached data or null

Throws:

CacheException - Propagated from underlying cache provider

putFromLoad

boolean putFromLoad(@Nonnull
 SharedSessionContractImplementor session,
 @Nonnull
 Object key,
 @Nonnull
 Object value,
 @Nullable
 Object version)

Attempt to cache an object, after loading it from the database.

Parameters:

session - Current session.

key - The item key

value - The item

version - the item version number

Returns:

true if the object was successfully cached

Throws:

CacheException - Propagated from underlying cache provider

putFromLoad

boolean putFromLoad(@Nonnull
 SharedSessionContractImplementor session,
 @Nonnull
 Object key,
 @Nonnull
 Object value,
 @Nullable
 Object version,
 boolean minimalPutOverride)

Attempt to cache an object, after loading from the database, explicitly specifying the minimalPut behavior.

Parameters:

session - Current session.

key - The item key

value - The item

version - the item version number

minimalPutOverride - Explicit minimalPut flag

Returns:

true if the object was successfully cached

Throws:

CacheException - Propagated from underlying cache provider

lockItem

@Nullable
SoftLock lockItem(@Nonnull
 SharedSessionContractImplementor session,
 @Nonnull
 Object key,
 @Nullable
 Object version)

Notify before an attempt to update or delete the keyed object. This operation is used by "asynchronous" concurrency strategies.

The returned object must be passed back to unlockItem(SharedSessionContractImplementor, Object, SoftLock), to release the lock. Concurrency strategies which do not support client-visible locks may silently return null.

Parameters:

session - Current session.

key - The key of the item to lock

version - The item's current version value

Returns:

A representation of our lock on the item; or null.

Throws:

CacheException - Propagated from underlying cache provider

unlockItem

void unlockItem(@Nonnull
 SharedSessionContractImplementor session,
 @Nonnull
 Object key,
 @Nullable
 SoftLock lock)

Notify that an attempt to update or delete the keyed object has completed, with or without success, after transaction completion. This operation is used by "asynchronous" concurrency strategies.

Parameters:

session - Current session.

key - The item key

lock - The lock previously obtained from lockItem(SharedSessionContractImplementor, Object, Object)

Throws:

CacheException - Propagated from underlying cache provider

remove

void remove(@Nonnull
 SharedSessionContractImplementor session,
 @Nonnull
 Object key)

Notify that an item has become stale, before completion of the transaction. This operation is used by "synchronous" concurrency strategies.

Parameters:

session - Current session.

key - The key of the item to remove

Throws:

CacheException - Propagated from underlying cache provider

removeAll

void removeAll(@Nonnull
 SharedSessionContractImplementor session)

Remove all data for this accessed type.

Throws:

CacheException - Propagated from underlying cache provider

contains

boolean contains(@Nonnull
 Object key)

Determine whether this region contains data for the given key.

The semantic here is whether the cache contains data visible for the current call context. This should be viewed as a "best effort", meaning blocking should be avoided if possible.

Parameters:

key - The cache key

Returns:

True if the underlying cache contains corresponding data; false otherwise.

lockRegion

@Nullable
SoftLock lockRegion()

Lock the entire region

Returns:

A representation of our lock on the item; or null.

Throws:

CacheException - Propagated from underlying cache provider

unlockRegion

void unlockRegion(@Nullable
 SoftLock lock)

Called after we have finished the attempted invalidation of the entire region

Parameters:

lock - The lock previously obtained from lockRegion()

Throws:

CacheException - Propagated from underlying cache provider

evict

void evict(@Nonnull
 Object key)

Forcibly evict an item from the cache immediately without regard for transaction isolation and/or locking. This behavior is exactly Hibernate legacy behavior, but it is also required by JPA - so we cannot remove it.

Used from JPA's Cache.evict(Class, Object), as well as the Hibernate extension Cache.evictEntityData(Class, Object) and Cache.evictEntityData(String, Object)

Parameters:

key - The key of the item to remove

Throws:

CacheException - Propagated from underlying cache provider

evictAll

void evictAll()

Forcibly evict all items from the cache immediately without regard for transaction isolation. This behavior is exactly Hibernate legacy behavior, but it is also required by JPA - so we cannot remove it.

Used from our JPA impl of Cache.evictAll() as well as the Hibernate extensions Cache.evictEntityData(Class), Cache.evictEntityData(String) and Cache.evictEntityData()

Throws:

CacheException - Propagated from underlying cache provider