org.codehaus.plexus.util

Class CachedMap

Implemented Interfaces:
Map

public final class CachedMap
extends java.lang.Object
implements Map

This class provides cache access to Map collections.

Instance of this class can be used as "proxy" for any collection implementing the java.util.Map interface.

Typically, CachedMap are used to accelerate access to large collections when the access to the collection is not evenly distributed (associative cache). The performance gain is about 50% for the fastest hash map collections (e.g. FastMap). For slower collections such as java.util.TreeMap, non-resizable FastMap (real-time) or database access, performance can be of several orders of magnitude.

Note: The keys used to access elements of a CachedMap do not need to be immutable as they are not stored in the cache (only keys specified by the put(Object,Object) method are). In other words, access can be performed using mutable keys as long as these keys can be compared for equality with the real map's keys (e.g. same hashCode values).

This implementation is not synchronized. Multiple threads accessing or modifying the collection must be synchronized externally.

This class is public domain (not copyrighted).

Version:
5.3, October 30, 2003
Author:
Jean-Marie Dautelle

Field Summary

private FastMap
_backingFastMap
Holds the FastMap backing this collection (null if generic backing map).
private Map
_backingMap
Holds the generic map backing this collection.
private Object[]
_keys
Holds the keys being cached.
private FastMap
_keysMap
Holds the keys of the backing map (key-to-key mapping).
private int
_mask
Holds the cache's mask (capacity - 1).
private Object[]
_values
Holds the values being cached.

Constructor Summary

CachedMap()
Creates a cached map backed by a FastMap.
CachedMap(int cacheSize)
Creates a cached map backed by a FastMap and having the specified cache size.
CachedMap(int cacheSize, Map backingMap)
Creates a cached map backed by the specified map and having the specified cache size.

Method Summary

void
clear()
Removes all mappings from this map (optional operation).
boolean
containsKey(Object key)
Indicates if this map contains a mapping for the specified key.
boolean
containsValue(Object value)
Returns true if this map maps one or more keys to the specified value.
Set
entrySet()
Returns an unmodifiable view of the mappings contained in this map.
boolean
equals(Object o)
Compares the specified object with this map for equality.
void
flush()
Flushes the key/value pairs being cached.
Object
get(Object key)
Returns the value to which this map maps the specified key.
Map
getBackingMap()
Returns the backing map.
private Object
getCacheMissed(Object key, int index)
int
getCacheSize()
Returns the actual cache size.
int
hashCode()
Returns the hash code value for this map.
boolean
isEmpty()
Returns true if this map contains no key-value mappings.
Set
keySet()
Returns an unmodifiable view of the keys contained in this map.
Object
put(Object key, Object value)
Associates the specified value with the specified key in this map.
void
putAll(Map map)
Copies all of the mappings from the specified map to this map (optional operation).
Object
remove(Object key)
Removes the mapping for this key from this map if it is present.
int
size()
Returns the number of key-value mappings in this map.
Collection
values()
Returns an unmodifiable view of the values contained in this map.

Field Details

_backingFastMap

private final FastMap _backingFastMap
Holds the FastMap backing this collection (null if generic backing map).

_backingMap

private final Map _backingMap
Holds the generic map backing this collection.

_keys

private final Object[] _keys
Holds the keys being cached.

_keysMap

private final FastMap _keysMap
Holds the keys of the backing map (key-to-key mapping). (null if FastMap backing map).

_mask

private final int _mask
Holds the cache's mask (capacity - 1).

_values

private final Object[] _values
Holds the values being cached.

Constructor Details

CachedMap

public CachedMap()
Creates a cached map backed by a FastMap. The default cache size and map capacity is set to 256 entries.

CachedMap

public CachedMap(int cacheSize)
Creates a cached map backed by a FastMap and having the specified cache size.
Parameters:
cacheSize - the cache size, the actual cache size is the first power of 2 greater or equal to cacheSize. This is also the initial capacity of the backing map.

CachedMap

public CachedMap(int cacheSize,
                 Map backingMap)
Parameters:
cacheSize - the cache size, the actual cache size is the first power of 2 greater or equal to cacheSize.
backingMap - the backing map to be "wrapped" in a cached map.

Method Details

clear

public void clear()
Removes all mappings from this map (optional operation). This method automatically flushes the cache.

containsKey

public boolean containsKey(Object key)
Indicates if this map contains a mapping for the specified key.
Parameters:
key - the key whose presence in this map is to be tested.
Returns:
true if this map contains a mapping for the specified key; false otherwise.

containsValue

public boolean containsValue(Object value)
Returns true if this map maps one or more keys to the specified value.
Parameters:
value - value whose presence in this map is to be tested.
Returns:
true if this map maps one or more keys to the specified value.

entrySet

public Set entrySet()
Returns an unmodifiable view of the mappings contained in this map. Each element in the returned set is a Map.Entry.
Returns:
an unmodifiable view of the mappings contained in this map.

equals

public boolean equals(Object o)
Compares the specified object with this map for equality. Returns true if the given object is also a map and the two Maps represent the same mappings.
Parameters:
o - object to be compared for equality with this map.
Returns:
true if the specified object is equal to this map.

flush

public void flush()
Flushes the key/value pairs being cached. This method should be called if the backing map is externally modified.

get

public Object get(Object key)
Returns the value to which this map maps the specified key. First, the cache is being checked, then if the cache does not contains the specified key, the backing map is accessed and the key/value pair is stored in the cache.
Parameters:
key - the key whose associated value is to be returned.
Returns:
the value to which this map maps the specified key, or null if the map contains no mapping for this key.

getBackingMap

public Map getBackingMap()
Returns:
the backing map.
See Also:
flush()

getCacheMissed

private Object getCacheMissed(Object key,
                              int index)

getCacheSize

public int getCacheSize()
Returns the actual cache size.
Returns:
the cache size (power of 2).

hashCode

public int hashCode()
Returns the hash code value for this map.
Returns:
the hash code value for this map.

isEmpty

public boolean isEmpty()
Returns true if this map contains no key-value mappings.
Returns:
true if this map contains no key-value mappings.

keySet

public Set keySet()
Returns an unmodifiable view of the keys contained in this map.
Returns:
an unmodifiable view of the keys contained in this map.

put

public Object put(Object key,
                  Object value)
Associates the specified value with the specified key in this map.
Parameters:
key - the key with which the specified value is to be associated.
value - the value to be associated with the specified key.
Returns:
the previous value associated with specified key, or null if there was no mapping for the key.

putAll

public void putAll(Map map)
Copies all of the mappings from the specified map to this map (optional operation). This method automatically flushes the cache.
Parameters:
map - the mappings to be stored in this map.

remove

public Object remove(Object key)
Removes the mapping for this key from this map if it is present.
Parameters:
key - key whose mapping is to be removed from the map.
Returns:
previous value associated with specified key, or null if there was no mapping for key.

size

public int size()
Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
Returns:
the number of key-value mappings in this map.

values

public Collection values()
Returns an unmodifiable view of the values contained in this map.
Returns:
an unmodifiable view of the values contained in this map.