org.hibernate.cache
Interface CacheConcurrencyStrategy
- NonstrictReadWriteCache, ReadOnlyCache, ReadWriteCache, TransactionalCache
public interface CacheConcurrencyStrategy
Implementors manage transactional access to cached data. Transactions
pass in a timestamp indicating transaction start time. Two different
implementation patterns are provided for.
- A transaction-aware cache implementation might be wrapped by a
"synchronous" concurrency strategy, where updates to the cache are written
to the cache inside the transaction.
- A non transaction-aware cache would be wrapped by an "asynchronous"
concurrency strategy, where items are merely "soft locked" during the
transaction and then updated during the "after transaction completion"
phase; the soft lock is not an actual lock on the database row -
only upon the cached representation of the item.
In terms of entity caches, the expected call sequences are:
- DELETES :
lock(Object,Object)
-> evict(Object)
-> release(Object,SoftLock)
- UPDATES :
lock(Object,Object)
-> update(Object,Object,Object,Object)
-> afterUpdate(Object,Object,Object,SoftLock)
- INSERTS :
insert(Object,Object,Object)
-> afterInsert(Object,Object,Object)
In terms of collection caches, all modification actions actually just
invalidate the entry(s). The call sequence here is:
lock(Object,Object)
->
evict(Object)
->
release(Object,SoftLock)
Note that, for an asynchronous cache, cache invalidation must be a two
step process (lock->release, or lock-afterUpdate), since this is the only
way to guarantee consistency with the database for a nontransactional cache
implementation. For a synchronous cache, cache invalidation is a single
step process (evict, or update). Hence, this interface defines a three
step process, to cater for both models.
Note that query result caching does not go through a concurrency strategy; they
are managed directly against the underlying
cache regions
.
boolean | afterInsert(Object key, Object value, Object version) - Called after an item has been inserted (after the transaction completes),
instead of calling release().
|
boolean | afterUpdate(Object key, Object value, Object version, SoftLock lock) - Called after an item has been updated (after the transaction completes),
instead of calling release().
|
void | clear() - Evict all items from the cache immediately.
|
void | destroy() - Clean up all resources.
|
void | evict(Object key) - Called after an item has become stale (before the transaction completes).
|
Object | get(Object key, long txTimestamp) - Attempt to retrieve an object from the cache.
|
Cache | getCache() - Get the wrapped cache implementation
|
String | getRegionName() - Get the cache region name
|
boolean | insert(Object key, Object value, Object currentVersion) - Called after an item has been inserted (before the transaction completes),
instead of calling evict().
|
SoftLock | lock(Object key, Object version) - We are going to attempt to update/delete the keyed object.
|
boolean | put(Object key, Object value, long txTimestamp, Object version, Comparator versionComparator, boolean minimalPut) - Attempt to cache an object, after loading from the database.
|
void | release(Object key, SoftLock lock) - Called when we have finished the attempted update/delete (which may or
may not have been successful), after transaction completion.
|
void | remove(Object key) - Evict an item from the cache immediately (without regard for transaction
isolation).
|
void | setCache(Cache cache) - Set the underlying cache implementation.
|
boolean | update(Object key, Object value, Object currentVersion, Object previousVersion) - Called after an item has been updated (before the transaction completes),
instead of calling evict().
|
afterInsert
public boolean afterInsert(Object key,
Object value,
Object version)
throws CacheException
Called after an item has been inserted (after the transaction completes),
instead of calling release().
This method is used by "asynchronous" concurrency strategies.
afterUpdate
public boolean afterUpdate(Object key,
Object value,
Object version,
SoftLock lock)
throws CacheException
Called after an item has been updated (after the transaction completes),
instead of calling release().
This method is used by "asynchronous" concurrency strategies.
clear
public void clear()
throws CacheException
Evict all items from the cache immediately.
destroy
public void destroy()
Clean up all resources.
evict
public void evict(Object key)
throws CacheException
Called after an item has become stale (before the transaction completes).
This method is used by "synchronous" concurrency strategies.
get
public Object get(Object key,
long txTimestamp)
throws CacheException
Attempt to retrieve an object from the cache. Mainly used in attempting
to resolve entities/collections from the second level cache.
key
- txTimestamp
- a timestamp prior to the transaction start time
- the cached object or null
getCache
public Cache getCache()
Get the wrapped cache implementation
getRegionName
public String getRegionName()
Get the cache region name
insert
public boolean insert(Object key,
Object value,
Object currentVersion)
throws CacheException
Called after an item has been inserted (before the transaction completes),
instead of calling evict().
This method is used by "synchronous" concurrency strategies.
lock
public SoftLock lock(Object key,
Object version)
throws CacheException
We are going to attempt to update/delete the keyed object. This
method is used by "asynchronous" concurrency strategies.
The returned object must be passed back to release(), to release the
lock. Concurrency strategies which do not support client-visible
locks may silently return null.
put
public boolean put(Object key,
Object value,
long txTimestamp,
Object version,
Comparator versionComparator,
boolean minimalPut)
throws CacheException
Attempt to cache an object, after loading from the database.
key
- value
- txTimestamp
- a timestamp prior to the transaction start timeversion
- the item version numberversionComparator
- a comparator used to compare version numbersminimalPut
- indicates that the cache should avoid a put is the item is already cached
- true if the object was successfully cached
release
public void release(Object key,
SoftLock lock)
throws CacheException
Called when we have finished the attempted update/delete (which may or
may not have been successful), after transaction completion.
This method is used by "asynchronous" concurrency strategies.
remove
public void remove(Object key)
throws CacheException
Evict an item from the cache immediately (without regard for transaction
isolation).
setCache
public void setCache(Cache cache)
Set the underlying cache implementation.
update
public boolean update(Object key,
Object value,
Object currentVersion,
Object previousVersion)
throws CacheException
Called after an item has been updated (before the transaction completes),
instead of calling evict().
This method is used by "synchronous" concurrency strategies.