org.dasein.util
Class ConcurrentMultiCache<T>

java.lang.Object
  org.dasein.util.ConcurrentMultiCache<T>

Type Parameters:

T - the type for objects being stored in instances of the cache

public class ConcurrentMultiCache<T>
extends Object

A concurrent multi-cache caches objects along multiple unique keys. You provide the list of unique keys and then this object will manage the concurrent access of multiple threads into the cache.

This class is backed up by multiple @{link ConcurrentCache} instances (one for each unique key) and thus behaves in accordance with the rules for that object. If, for example, you wanted to create a memory cache of employees:

public class EmployeeFactory {
private ConcurrentMultiCache<Employee> cache = new ConcurrentMultiCache<Employee>(Employee.class, "employeeId", "email");

public Employee getEmployeeById(Number id) {
return cache.find("employeeId", id, getIdLoader(id));
}

public Employee getEmployeeByEmail(String email) {
return cache.find("email", email, getEmailLoader(email));
}
}

In the above example, the getIdLoader() and getEmailLoader() methods would be methods you would create to return an instance of CacheLoader that would load the desired employee from the database based on the employee ID or email address, respectively.

Last modified: $Date: 2006/08/31 18:46:17 $

Version:

$Revision: 1.11 $

Author:

George Reese

Constructor Summary

ConcurrentMultiCache(Class<T> cls, Collection<String> attrs)
Constructs a concurrent multi-cache that caches for unique keys specified by the attributes.

ConcurrentMultiCache(Class<T> cls, String... attrs)
Constructs a concurrent multi-cache that caches for unique keys specified by the attributes.

ConcurrentMultiCache(String... attrs)
Constructs a concurrent multi-cache that caches for unique keys specified by the attributes.

Method Summary

T	cache(T item) Places the specified item in the cache.
T	find(Map<String,Object> vals) Finds the object in the cache matching the values in the specified value map.
T	find(Object val) Finds the object from the cache with the specified unique identifier value for the default unique identifier attribute.
T	find(Object val, CacheLoader<T> loader) Calls find(String,Object,CacheLoader) using the only unique identifier attribute as passed to this cache's constructor.
T	find(String key, Object val) Returns the object identified by the specified key/value pair if it is currently in memory in the cache.
T	find(String key, Object val, CacheLoader<T> loader) Seeks the item from the cache that is identified by the specified key having the specified value.
T	find(String key, Object val, CacheLoader<T> loader, Object... args) Seeks the item from the cache that is identified by the specified key having the specified value.
HashMap<String,Object>	getKeys(T item) Provides the values for all of the unique identifiers managed by the cache.
Class<T>	getTarget()
void	release(T item) Releases the specified item from the cache.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

ConcurrentMultiCache

public ConcurrentMultiCache(Class<T> cls,
                            Collection<String> attrs)

Constructs a concurrent multi-cache that caches for unique keys specified by the attributes. This constructor allows for automated loading into the cache.

Parameters:

cls - the class object for objects stored in this cache

attrs - the unique keys that this cache will cache objects on

ConcurrentMultiCache

public ConcurrentMultiCache(String... attrs)

Constructs a concurrent multi-cache that caches for unique keys specified by the attributes.

Parameters:

attrs - the unique keys that this cache will cache objects on

ConcurrentMultiCache

public ConcurrentMultiCache(Class<T> cls,
                            String... attrs)

Constructs a concurrent multi-cache that caches for unique keys specified by the attributes. This constructor allows for automated loading into the cache.

Parameters:

cls - the class object for objects stored in this cache

attrs - the unique keys that this cache will cache objects on

Method Detail

cache

public T cache(T item)

Places the specified item in the cache. It will not replace an existing item in the cache. Instead, if an item already exists in the cache, it will make sure that item is cached across all identifiers and then return the cached item.

Parameters:

item - the item to be cached

Returns:

whatever item is in the cache after this operation

find

public T find(Object val)

Finds the object from the cache with the specified unique identifier value for the default unique identifier attribute. This method will throw an exception if there is more than one unique identifier associated with this cache.

Parameters:

val - the value matching the desired object from the cache

Returns:

the matching object from the cache

Throws:

CacheManagementException - this multi-cache supports multiple unique IDs

find

public T find(Map<String,Object> vals)

Finds the object in the cache matching the values in the specified value map. If a matching argument is not in the cache, this method will instantiate an instance of the object and assign the mapping values to that instantiated object. In order for this to work, the keys in this mapping must have the same names as the attributes for the instantiated object

Parameters:

vals - the mapping that includes the attribute/value pairs

Returns:

an object matching those values in the cache

find

public T find(String key,
              Object val)

Returns the object identified by the specified key/value pair if it is currently in memory in the cache. Just because this value returns null does not mean the object does not exist. Instead, it may be that it is simply not cached in memory.

Parameters:

key - they unique identifier attribute on which you are searching

val - the value of the unique identifier on which you are searching

Returns:

the matching object from the cache

find

public T find(Object val,
              CacheLoader<T> loader)

Calls find(String,Object,CacheLoader) using the only unique identifier attribute as passed to this cache's constructor. If more than one unique identifier attribute was passed, this method will throw an exception

Parameters:

val - the value of the unique key being sought

loader - the loader to load new instances from the persistent store

Returns:

a matching object, if any

Throws:

CacheManagementException - this cache supports multiple unique identifiers

find

public T find(String key,
              Object val,
              CacheLoader<T> loader)

Seeks the item from the cache that is identified by the specified key having the specified value. If no match is found, the specified loader will be called to place an item in the cache. You may pass in null for the loader. If you do, only an object in active memory will be returned.

Parameters:

key - the name of the unique identifier attribute whose value you have

val - the value of the unique identifier that identifiers the desired item

loader - a loader to load the desired object from the persistence store if it is not in memory

Returns:

the object that matches the specified key/value

find

public T find(String key,
              Object val,
              CacheLoader<T> loader,
              Object... args)

Seeks the item from the cache that is identified by the specified key having the specified value. If no match is found, the specified loader will be called with the specified arguments in order to place an instantiated item into the cache.

Parameters:

key - the name of the unique identifier attribute whose value you have

val - the value of the unique identifier that identifiers the desired item

loader - a loader to load the desired object from the persistence store if it is not in memory

args - any arguments to pass to the loader

Returns:

the object that matches the specified key/value

getKeys

public HashMap<String,Object> getKeys(T item)

Provides the values for all of the unique identifiers managed by the cache.

Parameters:

item - the item whose key values are being sought

Returns:

a mapping of key names to item values

getTarget

public Class<T> getTarget()

release

public void release(T item)

Releases the specified item from the cache. If it is still in the persistent store, it will be retrieved back into the cache on next query. Otherwise, subsequent attempts to search for it in the cache will result in null.

Parameters:

item - the item to be released from the cache.

toString

public String toString()

Overrides:

toString in class Object