net.sourceforge.rcache
Class BaseCache<K,V>

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by net.sourceforge.rcache.BaseCache<K,V>
Type Parameters:
K - the type of keys maintained by this cache
V - the type of cached values
All Implemented Interfaces:
java.util.Map<K,V>, Cache<K,V>
Direct Known Subclasses:
SoftCache, WeakCache

public abstract class BaseCache<K,V>
extends java.util.AbstractMap<K,V>
implements Cache<K,V>

Memory-Sensitive Cache base implementation.

Thread-safety of this class will depend on the selected implementation for the internal map. If the convenience constructors are used, resulting instances will be thread-safe, unless a concurrency level of -1 (or less) is specified.

Author:
Rodrigo Ruiz

Nested Class Summary
 
Nested classes/interfaces inherited from class java.util.AbstractMap
java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>
 
Nested classes/interfaces inherited from interface net.sourceforge.rcache.Cache
Cache.Operation
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry<K,V>
 
Field Summary
 
Fields inherited from interface net.sourceforge.rcache.Cache
DEFAULT_CONCURRENCY_LEVEL, DEFAULT_INITIAL_CAPACITY, DEFAULT_LOAD_FACTOR
 
Constructor Summary
BaseCache(int initCapacity, float loadFactor, int concurrencyLevel)
          Creates an instance with custom capacity and concurrency level.
BaseCache(java.util.Map<K,KeyedReference<K,V>> map)
          Advanced constructor.
 
Method Summary
 void clear()
          Removes all entries from this cache.
protected abstract  KeyedReference<K,V> createRef(K key, V value, java.lang.ref.ReferenceQueue<V> rqueue)
          Factory method for creating a new reference instance.
 java.util.Set<java.util.Map.Entry<K,V>> entrySet()
          
 boolean equals(java.lang.Object obj)
           Cache instances are always different by nature, even if they contain exactly the same entries.
 V get(java.lang.Object key)
          Returns the value to which this cache maps the specified key.
 int hashCode()
           The superclass implementation of this method relies on the entrySet() method, which always throws an exception.
protected  void purge()
          Removes keys for References that have been enqueued.
 V put(K key, V value)
          Associates the specified value with the specified key in this cache, but only if no value is associated yet.
 V remove(java.lang.Object key)
          Removes the entry for this key from this cache if present.
 int size()
          
 java.util.Collection<V> values()
          
 
Methods inherited from class java.util.AbstractMap
clone, containsKey, containsValue, isEmpty, keySet, putAll, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

BaseCache

public BaseCache(int initCapacity,
                 float loadFactor,
                 int concurrencyLevel)

Creates an instance with custom capacity and concurrency level.

The concurrency level is used as a hint to select the internal Map implementation:

Parameters:
initCapacity - The map initial capacity
loadFactor - The map load factor
concurrencyLevel - The concurrency level.

BaseCache

public BaseCache(java.util.Map<K,KeyedReference<K,V>> map)

Advanced constructor.

With this constructor, the programmer can specify the Map to be used to hold the values. Useful for those cases in which the default implementations do not have the correct performance profile.

Parameters:
map - The map to use internally
Method Detail

get

public final V get(java.lang.Object key)

Returns the value to which this cache maps the specified key. Returns null if the cache contains no entry for this key. A return value of null does not necessarily indicate that the cache contains no entry for the key; it's also possible that the cache explicitly maps the key to null

.

Although this method should use K for the key type, it is left as Object to keep this interface compatible with Map.

Specified by:
get in interface java.util.Map<K,V>
Specified by:
get in interface Cache<K,V>
Overrides:
get in class java.util.AbstractMap<K,V>
Parameters:
key - key whose associated value is to be returned.
Returns:
the value to which this cache associates the specified key.

put

public final V put(K key,
                   V value)

Associates the specified value with the specified key in this cache, but only if no value is associated yet. If the cache previously contained an entry for this key, the old value is returned, but not replaced.

This method is equivalent to the putIfAbsent from the ConcurrentMap class, as it is more appropriate for a cache than the original one from Map.

Specified by:
put in interface java.util.Map<K,V>
Specified by:
put in interface Cache<K,V>
Overrides:
put in class java.util.AbstractMap<K,V>
Parameters:
key - key with which the specified value is to be associated.
value - value to be associated with the specified key.
Returns:
the value associated with specified key. If the key was already associated with a value, the old value is returned. Otherwise, value is returned

remove

public final V remove(java.lang.Object key)

Removes the entry for this key from this cache if present.

Although this method should use K for the key type, it is left as Object to keep this interface compatible with Map.

Specified by:
remove in interface java.util.Map<K,V>
Specified by:
remove in interface Cache<K,V>
Overrides:
remove in class java.util.AbstractMap<K,V>
Parameters:
key - key whose entry is to be removed from the cache.
Returns:
previous value associated with specified key, or null if there was no entry for key. (A null return can also indicate that the cache previously associated null with the specified key)

size

public final int size()

Specified by:
size in interface java.util.Map<K,V>
Overrides:
size in class java.util.AbstractMap<K,V>

clear

public final void clear()

Removes all entries from this cache.

This method must be handled very carefully, as it will break the assumption of unique instances for cached factories.

Specified by:
clear in interface java.util.Map<K,V>
Specified by:
clear in interface Cache<K,V>
Overrides:
clear in class java.util.AbstractMap<K,V>

entrySet

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

Specified by:
entrySet in interface java.util.Map<K,V>
Specified by:
entrySet in class java.util.AbstractMap<K,V>

values

public final java.util.Collection<V> values()

Specified by:
values in interface java.util.Map<K,V>
Overrides:
values in class java.util.AbstractMap<K,V>

hashCode

public final int hashCode()

The superclass implementation of this method relies on the entrySet() method, which always throws an exception. This re-implementation removes the issue.

Specified by:
hashCode in interface java.util.Map<K,V>
Overrides:
hashCode in class java.util.AbstractMap<K,V>

equals

public final boolean equals(java.lang.Object obj)

Cache instances are always different by nature, even if they contain exactly the same entries.

Specified by:
equals in interface java.util.Map<K,V>
Overrides:
equals in class java.util.AbstractMap<K,V>

createRef

protected abstract KeyedReference<K,V> createRef(K key,
                                                 V value,
                                                 java.lang.ref.ReferenceQueue<V> rqueue)
Factory method for creating a new reference instance.

Parameters:
key - The key
value - The value
rqueue - A reference queue
Returns:
A reference instance containing the key and value

purge

protected final void purge()

Removes keys for References that have been enqueued.

This method is not public because applications should never need to manually purge the cache. However, it is left protected to allow invocation from tests.

This method is synchronised because ReferenceQueue is not thread-safe.



© 2007-2009 Rodrigo Ruiz
This site is hosted by