org.hibernate.cache.jbc.access
Class PutFromLoadValidator

java.lang.Object
  org.hibernate.cache.jbc.access.PutFromLoadValidator

public class PutFromLoadValidator
extends Object

Encapsulates logic to allow a TransactionalAccessDelegate to determine whether a TransactionalAccessDelegate#putFromLoad(Object, Object, long, Object, boolean) call should be allowed to update the cache. A putFromLoad has the potential to store stale data, since the data may have been removed from the database and the cache between the time when the data was read from the database and the actual call to putFromLoad.

The expected usage of this class by a thread that read the cache and did not find data is:

1. Call {@link #registerPendingPut(Object)}
2. Read the database
3. Call {@link #acquirePutFromLoadLock(Object)}
4. if above returns false, the thread should not cache the data; only if above returns true, put data in the cache and...
5. then call {@link #releasePutFromLoadLock(Object)}

The expected usage by a thread that is taking an action such that any pending putFromLoad may have stale data and should not cache it is to either call

• {@link #invalidateKey(Object)} (for a single key invalidation)
• or {@link #invalidateRegion()} (for a general invalidation all pending puts)

This class also supports the concept of "naked puts", which are calls to {@link #acquirePutFromLoadLock(Object)} without a preceding {@link #registerPendingPut(Object)} call.

Version:

$Revision: $

Author:

Brian Stansberry

Field Summary

static long

NAKED_PUT_INVALIDATION_PERIOD Period in ms after a removal during which a call to acquirePutFromLoadLock(Object) that hasn't been pre-registered (aka a "naked put") will return false.

Constructor Summary

	PutFromLoadValidator(TransactionManager transactionManager) Creates a new PutFromLoadValidator.
protected	PutFromLoadValidator(TransactionManager transactionManager, long nakedPutInvalidationPeriod, long pendingPutOveragePeriod, long pendingPutRecentPeriod, long maxPendingPutDelay) Constructor variant for use by unit tests; allows control of various timeouts by the test.

Method Summary

boolean	acquirePutFromLoadLock(Object key) Acquire a lock giving the calling thread the right to put data in the cache for the given key.
protected int	getOveragePendingPutQueueLength() Only for use by unit tests; may be removed at any time
protected int	getPendingPutQueueLength() Only for use by unit tests; may be removed at any time
protected int	getRemovalQueueLength() Only for use by unit tests; may be removed at any time
boolean	invalidateKey(Object key) Invalidates any previously registered pending puts ensuring a subsequent call to acquirePutFromLoadLock(Object) will return false.
boolean	invalidateRegion() Invalidates all previously registered pending puts ensuring a subsequent call to acquirePutFromLoadLock(Object) will return false.
void	registerPendingPut(Object key) Notifies this validator that it is expected that a database read followed by a subsequent acquirePutFromLoadLock(Object) call will occur.
void	releasePutFromLoadLock(Object key) Releases the lock previously obtained by a call to acquirePutFromLoadLock(Object) that returned true.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NAKED_PUT_INVALIDATION_PERIOD

public static final long NAKED_PUT_INVALIDATION_PERIOD

Period in ms after a removal during which a call to acquirePutFromLoadLock(Object) that hasn't been pre-registered (aka a "naked put") will return false.

See Also:

Constant Field Values

Constructor Detail

PutFromLoadValidator

public PutFromLoadValidator(TransactionManager transactionManager)

Creates a new PutFromLoadValidator.

Parameters:

transactionManager - transaction manager to use to associate changes with a transaction; may be null

PutFromLoadValidator

protected PutFromLoadValidator(TransactionManager transactionManager,
                               long nakedPutInvalidationPeriod,
                               long pendingPutOveragePeriod,
                               long pendingPutRecentPeriod,
                               long maxPendingPutDelay)

Constructor variant for use by unit tests; allows control of various timeouts by the test.

Method Detail

acquirePutFromLoadLock

public boolean acquirePutFromLoadLock(Object key)

Acquire a lock giving the calling thread the right to put data in the cache for the given key.

NOTE: A call to this method that returns true should always be matched with a call to releasePutFromLoadLock(Object).

Parameters:

key - the key

Returns:

true if the lock is acquired and the cache put can proceed; false if the data should not be cached

releasePutFromLoadLock

public void releasePutFromLoadLock(Object key)

Releases the lock previously obtained by a call to acquirePutFromLoadLock(Object) that returned true.

Parameters:

key - the key

invalidateKey

public boolean invalidateKey(Object key)

Invalidates any previously registered pending puts ensuring a subsequent call to acquirePutFromLoadLock(Object) will return false.

This method will block until any concurrent thread that has acquired the putFromLoad lock for the given key has released the lock. This allows the caller to be certain the putFromLoad will not execute after this method returns, possibly caching stale data.

Parameters:

key - key identifying data whose pending puts should be invalidated

Returns:

true if the invalidation was successful; false if a problem occured (which the caller should treat as an exception condition)

invalidateRegion

public boolean invalidateRegion()

Invalidates all previously registered pending puts ensuring a subsequent call to acquirePutFromLoadLock(Object) will return false.

This method will block until any concurrent thread that has acquired the putFromLoad lock for the any key has released the lock. This allows the caller to be certain the putFromLoad will not execute after this method returns, possibly caching stale data.

Returns:

true if the invalidation was successful; false if a problem occured (which the caller should treat as an exception condition)

registerPendingPut

public void registerPendingPut(Object key)

Notifies this validator that it is expected that a database read followed by a subsequent acquirePutFromLoadLock(Object) call will occur. The intent is this method would be called following a cache miss wherein it is expected that a database read plus cache put will occur. Calling this method allows the validator to treat the subsequent acquirePutFromLoadLock as if the database read occurred when this method was invoked. This allows the validator to compare the timestamp of this call against the timestamp of subsequent removal notifications. A put that occurs without this call preceding it is "naked"; i.e the validator must assume the put is not valid if any relevant removal has occurred within NAKED_PUT_INVALIDATION_PERIOD milliseconds.

Parameters:

key - key that will be used for subsequent cache put

getPendingPutQueueLength

protected int getPendingPutQueueLength()

Only for use by unit tests; may be removed at any time

getOveragePendingPutQueueLength

protected int getOveragePendingPutQueueLength()

Only for use by unit tests; may be removed at any time

getRemovalQueueLength

protected int getRemovalQueueLength()

Only for use by unit tests; may be removed at any time