net.sourceforge.rcache
Interface Cache<K,V>

Type Parameters:

K - the type of keys maintained by this cache

V - the type of cached values

All Known Implementing Classes:

BaseCache, CacheProfiler, MruGuard, SoftCache, WeakCache

public interface Cache<K,V>

Memory-Sensitive Cache.

Cache implementations will probably be implemented as Maps and so, this interface is maintained "compatible" with Map. However, in most situations, the Map interface is more complex than needed.

This interface offers a simpler option, more oriented to the actual goals of a Cache.

Author:

Rodrigo Ruiz

Nested Class Summary

static class

Cache.Operation The operations defined in the Cache interface.

Field Summary

static int	DEFAULT_CONCURRENCY_LEVEL Default concurrency level.
static int	DEFAULT_INITIAL_CAPACITY Default cache initial capacity.
static float	DEFAULT_LOAD_FACTOR Default cache load factor.

Method Summary

void	clear() Removes all entries from this cache.
V	get(java.lang.Object key) Returns the value to which this cache maps the specified key.
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.

Field Detail

DEFAULT_INITIAL_CAPACITY

static final int DEFAULT_INITIAL_CAPACITY

Default cache initial capacity.

See Also:

Constant Field Values

DEFAULT_LOAD_FACTOR

static final float DEFAULT_LOAD_FACTOR

Default cache load factor.

See Also:

Constant Field Values

DEFAULT_CONCURRENCY_LEVEL

static final int DEFAULT_CONCURRENCY_LEVEL

Default concurrency level. Appropriate for multiple readers and a single writer.

See Also:

Constant Field Values

Method Detail

get

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.

Parameters:

key - key whose associated value is to be returned.

Returns:

the value to which this cache associates the specified key.

put

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.

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

Throws:

java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this cache.

java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.

remove

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.

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)

clear

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.