org.dasein.util
Class ConcurrentCache<K,V>

java.lang.Object
  org.dasein.util.ConcurrentCache<K,V>

Type Parameters:

K - the type for key values stored in the cache

V - the type of objects stored in the cache

All Implemented Interfaces:

ConcurrentMap<K,V>, Map<K,V>

public class ConcurrentCache<K,V>
extends Object
implements ConcurrentMap<K,V>

Caches objects that implement the CachedItem interface and manages their life cycle. The point of a cache is to act as an automated loader of objects from some persistent repository on-demand, cache them in memory, and then release them after they are no longer needed. An application can always rely on the cache to access the most up-to-date copy of an object and provide shared references to that object.

Last modified: $Date: 2006/08/15 03:29:28 $

Version:

$Revision: 1.4 $

Author:

George Reese

Nested Class Summary

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

Map.Entry<K,V>

Constructor Summary

ConcurrentCache()

Method Summary

void	clear() Clears out all elements of the cache and starts fresh.
boolean	containsKey(Object key) This method will verify both that the key exists and the value is currently value for the cache.
boolean	containsValue(Object val) Verifies that the specified value is in the cache.
Set<Map.Entry<K,V>>	entrySet() Returns a set of entries in this cache.
V	get(Object key) Retrieves the item associated with the specified key if it is currently valid for the cache.
V	getOrLoad(K key, CacheLoader<V> loader) Retrieves the value for the specified key.
boolean	isEmpty()
Set<K>	keySet()
V	put(K key, V val) Places the specified value into the cache.
void	putAll(Map<? extends K,? extends V> map) Places all elements in the specified map into this cache.
V	putIfAbsent(K key, V val) Conditionally associates the specified value with the specified key if no value currently exists for the key.
V	remove(Object key) Removes the specified object from the cache.
boolean	remove(Object key, Object val) Removes the specified key only if the current value equals the specified value.
V	replace(K key, V val) Replaces the specified key only if it has some current value.
boolean	replace(K key, V ov, V nv) Replaces the current value of the specified key with the proposed new value only if the current value matches the specified old value.
int	size()
String	toString()
Collection<V>	values()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

ConcurrentCache

public ConcurrentCache()

Method Detail

clear

public void clear()

Clears out all elements of the cache and starts fresh.

Specified by:

clear in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

This method will verify both that the key exists and the value is currently value for the cache.

Specified by:

containsKey in interface Map<K,V>

Parameters:

key - the key to test for existence

Returns:

true if the cache has a value with the specified key

containsValue

public boolean containsValue(Object val)

Verifies that the specified value is in the cache.

Specified by:

containsValue in interface Map<K,V>

Parameters:

val - the desired value

Returns:

true if it is in the cache and value

entrySet

public Set<Map.Entry<K,V>> entrySet()

Returns a set of entries in this cache.

Specified by:

entrySet in interface Map<K,V>

Returns:

cache entries

get

public V get(Object key)

Retrieves the item associated with the specified key if it is currently valid for the cache.

Specified by:

get in interface Map<K,V>

Parameters:

key - the key whose item is being sought

Returns:

the current value for that key, if any

getOrLoad

public V getOrLoad(K key,
                   CacheLoader<V> loader)

Retrieves the value for the specified key. If no value is present, this method will attempt to load a value and place it into the cache. This method appears atomic in accordance with the contract of a @{link ConcurrentMap}, but any required loading will actually occur outside of a synchronous block, thus allowing for other operations on the cache while a load is in process. In the rare instance that two loads occur simultaneously, the result of the first completed load will be stored in the cache and the second will be discarded. As a result, the return value of both calls will be the item loaded from the first load to complete.

Parameters:

key - the key being sought

loader - a loader to load a new value if a value is missing

Returns:

the value matching the specified key or null if no object exists in the system matching the desired key

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

Returns:

true of the cache is empty

put

public V put(K key,
             V val)

Places the specified value into the cache.

Specified by:

put in interface Map<K,V>

Parameters:

key - the key for the item being placed into the cache

val - the item to be cached

Returns:

the resulting value stored in the cache

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

Returns:

all of the keys in the cache

putAll

public void putAll(Map<? extends K,? extends V> map)

Places all elements in the specified map into this cache.

Specified by:

putAll in interface Map<K,V>

Parameters:

map - the map to store in this cache.

putIfAbsent

public V putIfAbsent(K key,
                     V val)

Conditionally associates the specified value with the specified key if no value currently exists for the key. The actual value stored with the key is returned.

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Parameters:

key - the key for which a value is to be stored

val - the proposed new value

Returns:

the actual value stored with key, whether the old or the new

remove

public V remove(Object key)

Removes the specified object from the cache.

Specified by:

remove in interface Map<K,V>

Parameters:

key - the key to be removed from the cache

Returns:

the previous value or null if nothing was in there in the first place

remove

public boolean remove(Object key,
                      Object val)

Removes the specified key only if the current value equals the specified value. If the value does not match the current value, the removal will not occur.

Specified by:

remove in interface ConcurrentMap<K,V>

Parameters:

key - the key to be removed

val - the value that must be matched by the current value for this key

replace

public V replace(K key,
                 V val)

Replaces the specified key only if it has some current value.

Specified by:

replace in interface ConcurrentMap<K,V>

Parameters:

key - the key to replace

val - the new value

Returns:

whatever is stored in the cache for the key when the operation completes

replace

public boolean replace(K key,
                       V ov,
                       V nv)

Replaces the current value of the specified key with the proposed new value only if the current value matches the specified old value.

Specified by:

replace in interface ConcurrentMap<K,V>

Parameters:

key - the key whose value should be replaced

ov - the old value that should match the current value in the cache

nv - the new value to put in the cache

Returns:

true if the value was replaced

size

public int size()

Specified by:

size in interface Map<K,V>

Returns:

the number of elements currently in the cache

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

Returns:

all of the values in the cache

toString

public String toString()

Overrides:

toString in class Object