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:

java.util.Map<KEY_T,VAL_T>

Direct Known Subclasses:

ObjectCacheMap

public class CacheMap<KEY_T,VAL_T>
extends java.lang.Object
implements java.util.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

java.util.Map.Entry<K,V>

Constructor Summary

CacheMap(Transformer5<KEY_T,VAL_T> converter)
Constructs a new instance of the cache map, which uses its own internal set of locks (see CacheMap(Transformer5, SyncLogEqLock)).

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

Method Summary

Transformer5<KEY_T,VAL_T>	asTransformer() Provides access to this object as a Transformer.
void	clear() Clears the cache.
boolean	containsKey(java.lang.Object key) Determines whether the value for the current key is in cache.
boolean	containsValue(java.lang.Object value) Whether the value is in the cache.
java.util.Set<java.util.Map.Entry<KEY_T,VAL_T>>	entrySet() Provides the set of cached values.
boolean	equals(java.lang.Object obj) Determines equality based on cached operation definition.
VAL_T	get(java.lang.Object objKey) Gets the value for the given object.
Transformer5<KEY_T,VAL_T>	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.
java.util.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(java.util.Map<? extends KEY_T,? extends VAL_T> t) Copies all of the giving mappings into the cache.
VAL_T	remove(java.lang.Object objKey) Removes an object from the cache.
int	size() Provides the size of the cache at the moment.
java.util.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(Transformer5<KEY_T,VAL_T> converter)

Constructs a new instance of the cache map, which uses its own internal set of locks (see CacheMap(Transformer5, SyncLogEqLock)).

Parameters:

converter - The transformer that implements the caching behavior.

Throws:

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

CacheMap

public CacheMap(Transformer5<KEY_T,VAL_T> 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(java.lang.Object key)

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

Specified by:

containsKey in interface java.util.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(java.lang.Object value)

Whether the value is in the cache.

Specified by:

containsValue in interface java.util.Map<KEY_T,VAL_T>

entrySet

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

Provides the set of cached values.

Specified by:

entrySet in interface java.util.Map<KEY_T,VAL_T>

get

public VAL_T get(java.lang.Object objKey)

Gets the value for the given object.

Specified by:

get in interface java.util.Map<KEY_T,VAL_T>

Parameters:

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

Returns:

The return value of the transformation.

Throws:

java.lang.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 java.util.Map<KEY_T,VAL_T>

Returns:

If the cache is empty.

keySet

public java.util.Set<KEY_T> keySet()

The set of keys currently loaded into the cache.

Specified by:

keySet in interface java.util.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 java.util.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 be null.

putAll

public void putAll(java.util.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.

Specified by:

putAll in interface java.util.Map<KEY_T,VAL_T>

Parameters:

t - The mapping to inject into the cache

Throws:

java.lang.NullPointerException - If t is null.

remove

public VAL_T remove(java.lang.Object objKey)

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

Specified by:

remove in interface java.util.Map<KEY_T,VAL_T>

size

public int size()

Provides the size of the cache at the moment.

Specified by:

size in interface java.util.Map<KEY_T,VAL_T>

values

public java.util.Collection<VAL_T> values()

Provides the values which have been generated at the moment.

Specified by:

values in interface java.util.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 java.util.Map<KEY_T,VAL_T>

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

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

Specified by:

equals in interface java.util.Map<KEY_T,VAL_T>

Overrides:

equals in class java.lang.Object

asTransformer

public Transformer5<KEY_T,VAL_T> 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 Transformer5<KEY_T,VAL_T> 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 java.util.Map<KEY_T,VAL_T>