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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	EntityLookupCache.EntityLookupCallbackDAO<K1 extends Serializable,V1,VK1 extends Serializable> Interface to support lookups of the entities using keys and values.
static class	EntityLookupCache.EntityLookupCallbackDAOAdaptor<K2 extends Serializable,V2,VK2 extends Serializable> Adaptor for implementations that support immutable entities.

Constructor Summary

Constructors

Constructor and Description
EntityLookupCache(EntityLookupCache.EntityLookupCallbackDAO<K,V,VK> entityLookup) Construct the lookup cache without any cache.
EntityLookupCache(org.alfresco.repo.cache.SimpleCache cache, EntityLookupCache.EntityLookupCallbackDAO<K,V,VK> entityLookup) Construct the lookup cache, using the default cache region.
EntityLookupCache(org.alfresco.repo.cache.SimpleCache cache, String cacheRegion, EntityLookupCache.EntityLookupCallbackDAO<K,V,VK> entityLookup) Construct the lookup cache, using the given cache region.

Method Summary

Modifier and Type	Method and Description
void	clear() Cache-only operation: Remove all cache entries NOTE: This operation removes ALL entries for ALL cache regions.
org.alfresco.util.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.
int	deleteByKey(K key) Delete the entity associated with the given key.
int	deleteByValue(V value) Delete the entity having the given value..
org.alfresco.util.Pair<K,V>	getByKey(K key) Find the entity associated with the given key.
org.alfresco.util.Pair<K,V>	getByValue(V value) Find the entity associated with the given value.
K	getKey(VK valueKey) Cache-only operation: Get the key for a given value key (note: not 'value' but 'value key').
org.alfresco.util.Pair<K,V>	getOrCreateByValue(V value) Find the entity associated with the given value and create it if it doesn't exist.
V	getValue(K key) Cache-only operation: Get the value for a given key
void	removeByKey(K key) Cache-only operation: Remove all cache values associated with the given key.
void	removeByValue(V value) Cache-only operation: Remove all cache values associated with the given value
void	setValue(K key, V value) Cache-only operation: Update the cache's value
int	updateValue(K key, V value) Update the entity associated with the given key.

Methods inherited from class java.lang.Object

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

Constructor Detail

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(org.alfresco.repo.cache.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(org.alfresco.repo.cache.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 Detail

getByKey

public org.alfresco.util.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 org.alfresco.util.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 org.alfresco.util.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 org.alfresco.util.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.

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.