## org.hibernate.cache.infinispan.access
Class PutFromLoadValidator

    java.lang.Object
      org.hibernate.cache.infinispan.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 `registerPendingPut(Object)`
2. Read the database
3. Call `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 `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

- `invalidateKey(Object)` (for a single key invalidation)
- or `invalidateRegion()` (for a general invalidation all pending puts)

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

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. will return false.

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

Copyright © 2001-2012 Red Hat, Inc. All Rights Reserved.