Package org.alfresco.repo.cache.lookup

Class EntityLookupCache<K extends Serializable,V,VK extends Serializable>

java.lang.Object
org.alfresco.repo.cache.lookup.EntityLookupCache<K,V,VK>
public class EntityLookupCache<K extends Serializable,V,VK extends Serializable> extends Object
A cache for two-way lookups of database entities. These are characterized by having a unique key (perhaps a database ID) and a separate unique key that identifies the object. If no cache is given, then all calls are passed through to the backing DAO.

The keys must have good equals and hashCode implementations and must respect the case-sensitivity of the use-case.

All keys will be unique to the given cache region, allowing the cache to be shared between instances of this class.

Generics:

  • K: The database unique identifier.
  • V: The value stored against K.
  • VK: The a value-derived key that will be used as a cache key when caching K for lookups by V. This can be the value itself if it is itself a good key.
Since:
3.2
Author:
Derek Hulley

  • Constructor Details

    • EntityLookupCache

      public EntityLookupCache(EntityLookupCache.EntityLookupCallbackDAO<K,V,VK> entityLookup)
      Construct the lookup cache without any cache. All calls are passed directly to the underlying DAO entity lookup.
      Parameters:
      entityLookup - the instance that is able to find and persist entities

    • EntityLookupCache

      public EntityLookupCache(SimpleCache cache, EntityLookupCache.EntityLookupCallbackDAO<K,V,VK> entityLookup)
      Construct the lookup cache, using the default cache region.
      Parameters:
      cache - the cache that will back the two-way lookups
      entityLookup - the instance that is able to find and persist entities

    • EntityLookupCache

      public EntityLookupCache(SimpleCache cache, String cacheRegion, EntityLookupCache.EntityLookupCallbackDAO<K,V,VK> entityLookup)
      Construct the lookup cache, using the given cache region.

      All keys will be unique to the given cache region, allowing the cache to be shared between instances of this class.

      Parameters:
      cache - the cache that will back the two-way lookups; null to have no backing in a cache.
      cacheRegion - the region within the cache to use.
      entityLookup - the instance that is able to find and persist entities

  • Method Details

    • getByKey

      public Pair<K,V> getByKey(K key)
      Find the entity associated with the given key. The entity callback will be used if necessary.

      It is up to the client code to decide if a null return value indicates a concurrency violation or not; the former would normally result in a concurrency-related exception such as ConcurrencyFailureException.

      Parameters:
      key - The entity key, which may be valid or invalid (null not allowed)
      Returns:
      Returns the key-value pair or null if the key doesn't reference an entity

    • getByValue

      public Pair<K,V> getByValue(V value)
      Find the entity associated with the given value. The entity callback will be used if no entry exists in the cache.

      It is up to the client code to decide if a null return value indicates a concurrency violation or not; the former would normally result in a concurrency-related exception such as ConcurrencyFailureException.

      Parameters:
      value - The entity value, which may be valid or invalid (null is allowed)
      Returns:
      Returns the key-value pair or null if the value doesn't reference an entity

    • createOrGetByValue

      public Pair<K,V> createOrGetByValue(V value, ControlDAO controlDAO)
      Attempt to create the entity and, failing that, look it up.
      This method takes the opposite approach to getOrCreateByValue(Object), which assumes the entity's existence: in this case the entity is assumed to NOT exist. The EntityLookupCache.EntityLookupCallbackDAO.createValue(Object) and EntityLookupCache.EntityLookupCallbackDAO.findByValue(Object) will be used if necessary.

      Use this method when the data involved is seldom reused.

      Parameters:
      value - The entity value (null is allowed)
      controlDAO - an essential DAO required in order to ensure a transactionally-safe attempt at data creation
      Returns:
      Returns the key-value pair (new or existing and never null)

    • getOrCreateByValue

      public Pair<K,V> getOrCreateByValue(V value)
      Find the entity associated with the given value and create it if it doesn't exist. The EntityLookupCache.EntityLookupCallbackDAO.findByValue(Object) and EntityLookupCache.EntityLookupCallbackDAO.createValue(Object) will be used if necessary.
      Parameters:
      value - The entity value (null is allowed)
      Returns:
      Returns the key-value pair (new or existing and never null)

    • updateValue

      public int updateValue(K key, V value)
      Update the entity associated with the given key. The EntityLookupCache.EntityLookupCallbackDAO.updateValue(Serializable, Object) callback will be used if necessary.

      It is up to the client code to decide if a 0 return value indicates a concurrency violation or not; usually the former will generate ConcurrencyFailureException or something recognised by the RetryingTransactionHelper.

      Parameters:
      key - The entity key, which may be valid or invalid (null not allowed)
      value - The new entity value (may be null)
      Returns:
      Returns the row update count.

    • getCachedEntityByValue

      public Pair<K,V> getCachedEntityByValue(V value)
      Find the entity associated with the given value if its cached
      Parameters:
      value - The entity value (null is not allowed)
      Returns:
      Returns the key-value pair (existing or null)

    • getKey

      public K getKey(VK valueKey)
      Cache-only operation: Get the key for a given value key (note: not 'value' but 'value key').
      Parameters:
      valueKey - The entity value key, which must be valid (null not allowed)
      Returns:
      The entity key (may be null)

    • getValue

      public V getValue(K key)
      Cache-only operation: Get the value for a given key
      Parameters:
      key - The entity key, which may be valid or invalid (null not allowed)
      Returns:
      The entity value (may be null)

    • setValue

      public void setValue(K key, V value)
      Cache-only operation: Update the cache's value
      Parameters:
      key - The entity key, which may be valid or invalid (null not allowed)
      value - The new entity value (may be null)

    • deleteByKey

      public int deleteByKey(K key)
      Delete the entity associated with the given key. The EntityLookupCache.EntityLookupCallbackDAO.deleteByKey(Serializable) callback will be used if necessary.

      It is up to the client code to decide if a 0 return value indicates a concurrency violation or not; usually the former will generate ConcurrencyFailureException or something recognised by the RetryingTransactionHelper.

      Parameters:
      key - the entity key, which may be valid or invalid (null not allowed)
      Returns:
      Returns the row deletion count

    • deleteByValue

      public int deleteByValue(V value)
      Delete the entity having the given value.. The EntityLookupCache.EntityLookupCallbackDAO.deleteByValue(Object) callback will be used if necessary.

      It is up to the client code to decide if a 0 return value indicates a concurrency violation or not; usually the former will generate ConcurrencyFailureException or something recognised by the RetryingTransactionHelper.

      Parameters:
      value - the entity value, which may be valid or invalid (null allowed)
      Returns:
      Returns the row deletion count

    • removeByKey

      public void removeByKey(K key)
      Cache-only operation: Remove all cache values associated with the given key.

    • removeByValue

      public void removeByValue(V value)
      Cache-only operation: Remove all cache values associated with the given value
      Parameters:
      value - The entity value (null is allowed)

    • clear

      public void clear()
      Cache-only operation: Remove all cache entries

      NOTE: This operation removes ALL entries for ALL cache regions.