jconch.cache
Class CacheMap<KEY_T,VAL_T>

java.lang.Object
  jconch.cache.CacheMap<KEY_T,VAL_T>

Type Parameters:

KEY_T - The type of the keys in the map, and the arguments for the transformer.

VAL_T - The type of the values in the map, and the return values from the transformer.

All Implemented Interfaces:

Map<KEY_T,VAL_T>

public class CacheMap<KEY_T,VAL_T>
extends Object
implements Map<KEY_T,VAL_T>

A map that provides cached look-ups in a thread-safe manner. Specifically, it is a thread-safe lazy map built on a memory-sensitive cache: objects are created on demand through calls to get(Object) and the like based on an implementation which is passed in. The map can conceptually be treated as a wrapper around Transformer or a Map of all possible inputs onto all possible outputs.

WARNING: This Map violates the general Map contract in a few ways.
First, its behavior is similar to a WeakHashMap, in that the methods may behave as if a seperate thread is silently removing entries. Because of this, it is not guarantied that calls to put(Object, Object) and the like will be honored beyond the life of the "put-ed" object. All of the methods reflect the state of the cache at the moment the method is called, and they cannot be guarantied to be consistant, even in a single threaded environment.
Second, the hashCode() and equals(Object) methods are based off of the definition of the cache operation, not the current contents. This prevents those methods from being sensitive to the state of the cache, but also deviates from Map.equals(Object) and Map.hashCode().

Author:

Robert Fischer

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

CacheMap(Transformer converter)
Constructs a new instance of the cache map.

CacheMap(Transformer converter, SyncLogEqLock<KEY_T> lockFactory)
Constructs a new instance of the cache map.

Method Summary

Transformer	asTransformer() Provides access to this object as a Transformer.
void	clear() Clears the cache.
boolean	containsKey(Object key) Determines whether the value for the current key is in cache.
boolean	containsValue(Object value) Whether the value is in the cache.
Set<Map.Entry<KEY_T,VAL_T>>	entrySet() Provides the set of cached values.
boolean	equals(Object obj) Determines equality based on cached operation definition.
VAL_T	get(Object objKey) Gets the value for the given object.
Transformer	getTransformer() Provides the underlying cache operation.
int	hashCode() Provides the hash code based on the cached operation definition.
boolean	isEmpty() Determines if there is anything in the cache.
Set<KEY_T>	keySet() The set of keys currently loaded into the cache.
VAL_T	put(KEY_T key, VAL_T value) Sets key to map to value in this map.
void	putAll(Map<? extends KEY_T,? extends VAL_T> t) Copies all of the giving mappings into the cache.
VAL_T	remove(Object objKey) Removes an object from the cache.
int	size() Provides the size of the cache at the moment.
Collection<VAL_T>	values() Provides the values which have been generated at the moment.

Methods inherited from class java.lang.Object

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

Constructor Detail

CacheMap

public CacheMap(Transformer converter)

Constructs a new instance of the cache map.

Parameters:

converter - The transformer that implements the caching behavior.

Throws:

org.apache.commons.lang.NullArgumentException - If the argument is null.

CacheMap

public CacheMap(Transformer converter,
                SyncLogEqLock<KEY_T> lockFactory)

Constructs a new instance of the cache map.

Parameters:

converter - The transformer that implements the caching behavior.

lockFactory - The source to be used for locking behaviors.

Throws:

org.apache.commons.lang.NullArgumentException - If either argument is null.

Method Detail

containsKey

public boolean containsKey(Object key)

Determines whether the value for the current key is in cache.

Specified by:

containsKey in interface Map<KEY_T,VAL_T>

Parameters:

key - The object to check, may be null

Returns:

Whether the object is in the cache at the moment

containsValue

public boolean containsValue(Object value)

Whether the value is in the cache.

Specified by:

containsValue in interface Map<KEY_T,VAL_T>

entrySet

public Set<Map.Entry<KEY_T,VAL_T>> entrySet()

Provides the set of cached values.

Specified by:

entrySet in interface Map<KEY_T,VAL_T>

get

public VAL_T get(Object objKey)

Gets the value for the given object.

Specified by:

get in interface Map<KEY_T,VAL_T>

Parameters:

objKey - The key to look up. May be null.

Returns:

The return value of the transformation.

Throws:

ClassCastException - If the object is not of KEY_T, or the underlying look-up returns a type that is not VAL_T.

isEmpty

public boolean isEmpty()

Determines if there is anything in the cache.

Specified by:

isEmpty in interface Map<KEY_T,VAL_T>

Returns:

If the cache is empty.

keySet

public Set<KEY_T> keySet()

The set of keys currently loaded into the cache.

Specified by:

keySet in interface Map<KEY_T,VAL_T>

put

public VAL_T put(KEY_T key,
                 VAL_T value)

Sets key to map to value in this map. It will remain in the map as long as key is not garbage collected.

Specified by:

put in interface Map<KEY_T,VAL_T>

Parameters:

key - The key with which the specified value is to be associated.

value - The value to be associated with the specified key; may not be null.

Throws:

NullPointerException - If value is null.

putAll

public void putAll(Map<? extends KEY_T,? extends VAL_T> t)

Copies all of the giving mappings into the cache. For each entry in the provided map, the general contract from put(Object, Object) holds true. If the map passed in contains null, the cache will be left in an indeterminant state.

Specified by:

putAll in interface Map<KEY_T,VAL_T>

Parameters:

t - The mapping to inject into the cache

Throws:

NullPointerException - If t is null, or a value in t is null.

remove

public VAL_T remove(Object objKey)

Removes an object from the cache. It may be recreated at a later time.

Specified by:

remove in interface Map<KEY_T,VAL_T>

size

public int size()

Provides the size of the cache at the moment.

Specified by:

size in interface Map<KEY_T,VAL_T>

values

public Collection<VAL_T> values()

Provides the values which have been generated at the moment.

Specified by:

values in interface Map<KEY_T,VAL_T>

hashCode

public int hashCode()

Provides the hash code based on the cached operation definition. See the warning in the class documentation.

Specified by:

hashCode in interface Map<KEY_T,VAL_T>

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Determines equality based on cached operation definition. See the warning in the class documentation.

Specified by:

equals in interface Map<KEY_T,VAL_T>

Overrides:

equals in class Object

asTransformer

public Transformer asTransformer()

Provides access to this object as a Transformer. The transformer delegates to the get(Object) method call, which (in turn) delegates to the cache operation.

Returns:

The get(Object) implementation as its own object.

getTransformer

public Transformer getTransformer()

Provides the underlying cache operation.

Returns:

The cache operation.

clear

public void clear()

Clears the cache. If the map is in an indeterminant state, this places the map back into a determinant state.

Specified by:

clear in interface Map<KEY_T,VAL_T>