## org.hibernate.cache.access
Interface CollectionRegionAccessStrategy

All Known Implementing Classes:
  CollectionAccessStrategyAdapter

    public interface CollectionRegionAccessStrategy

Contract for managing transactional and concurrent access to cached collection data. For cached collection data, all modification actions actually just invalidate the entry(s). The call sequence here is: `lockItem(java.lang.Object, java.lang.Object)` -> `remove(java.lang.Object)` -> `unlockItem(java.lang.Object, org.hibernate.cache.access.SoftLock)`

There is another usage pattern that is used to invalidate entries after performing "bulk" HQL/SQL operations: `lockRegion()` -> `removeAll()` -> `unlockRegion(org.hibernate.cache.access.SoftLock)`

Author:
  Gavin King, Steve Ebersole

Method Summary
`void` `evict(Object key)` Forcibly evict an item from the cache immediately without regard for transaction isolation.
`void` `evictAll()` Forcibly evict all items from the cache immediately without regard for transaction isolation.
`Object` `get(Object key, long txTimestamp)` Attempt to retrieve an object from the cache.
`CollectionRegion` `getRegion()` Get the wrapped collection cache region
`SoftLock` `lockItem(Object key, Object version)` We are going to attempt to update/delete the keyed object.
`SoftLock` `lockRegion()` Lock the entire region
`boolean` `putFromLoad(Object key, Object value, long txTimestamp, Object version)` Attempt to cache an object, after loading from the database.
`boolean` `putFromLoad(Object key, Object value, long txTimestamp, Object version, boolean minimalPutOverride)` Attempt to cache an object, after loading from the database, explicitly specifying the minimalPut behavior.
`void` `remove(Object key)` Called after an item has become stale (before the transaction completes).
`void` `removeAll()` Called to evict data from the entire region
`void` `unlockItem(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` `unlockRegion(SoftLock lock)` Called after we have finished the attempted invalidation of the entire region

Method Detail

### getRegion

    CollectionRegion getRegion()

  Get the wrapped collection cache region

  Returns:
    The underlying region

### get

    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.

  Parameters:
    `key` - The key of the item to be retrieved.
    `txTimestamp` - a timestamp prior to the transaction start time
  Returns:
    the cached object or `null`
  Throws:
    `CacheException` - Propogated from underlying `Region`

### putFromLoad

    boolean putFromLoad(Object key,
                        Object value,
                        long txTimestamp,
                        Object version)
                        throws CacheException

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

  Parameters:
    `key` - The item key
    `value` - The item
    `txTimestamp` - a timestamp prior to the transaction start time
    `version` - the item version number
  Returns:
    `true` if the object was successfully cached
  Throws:
    `CacheException` - Propogated from underlying `Region`

### putFromLoad

    boolean putFromLoad(Object key,
                        Object value,
                        long txTimestamp,
                        Object version,
                        boolean minimalPutOverride)
                        throws CacheException

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

  Parameters:
    `key` - The item key
    `value` - The item
    `txTimestamp` - a timestamp prior to the transaction start time
    `version` - the item version number
    `minimalPutOverride` - Explicit minimalPut flag
  Returns:
    `true` if the object was successfully cached
  Throws:
    `CacheException` - Propogated from underlying `Region`

### lockItem

    SoftLock lockItem(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.

  Parameters:
    `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` - Propogated from underlying `Region`

### lockRegion

    SoftLock lockRegion()
                        throws CacheException

  Lock the entire region

  Returns:
    A representation of our lock on the item; or null.
  Throws:
    `CacheException` - Propogated from underlying `Region`

### unlockItem

    void unlockItem(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.

  Parameters:
    `key` - The item key
    `lock` - The lock previously obtained from `lockItem(java.lang.Object, java.lang.Object)`
  Throws:
    `CacheException` - Propogated from underlying `Region`

### unlockRegion

    void unlockRegion(SoftLock lock)
                      throws CacheException

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

  Parameters:
    `lock` - The lock previously obtained from `lockRegion()`
  Throws:
    `CacheException` - Propogated from underlying `Region`

### remove

    void remove(Object key)
                throws CacheException

  Called after an item has become stale (before the transaction completes). This method is used by "synchronous" concurrency strategies.

  Parameters:
    `key` - The key of the item to remove
  Throws:
    `CacheException` - Propogated from underlying `Region`

### removeAll

    void removeAll()
                   throws CacheException

  Called to evict data from the entire region

  Throws:
    `CacheException` - Propogated from underlying `Region`

### evict

    void evict(Object key)
               throws CacheException

  Forcibly evict an item from the cache immediately without regard for transaction isolation.

  Parameters:
    `key` - The key of the item to remove
  Throws:
    `CacheException` - Propogated from underlying `Region`

### evictAll

    void evictAll()
                  throws CacheException

  Forcibly evict all items from the cache immediately without regard for transaction isolation.

  Throws:
    `CacheException` - Propogated from underlying `Region`

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