com.persistit.encoding

Class ObjectCache

java.lang.Object

com.persistit.encoding.ObjectCache

public class ObjectCache
extends Object

A simple cache for deserialized objects. This cache is loosely patterned after WeakHashMap, except that an entry is eligible to be removed when the value associated with a key is softly referenced, not the key.

Note: although many of the methods of this class take an argument of type Key, the map is actually stored using immutable KeyState objects. Therefore if you modify the state of a Key after using it in a call to put(com.persistit.Key, java.lang.Object), the mapping will remain intact. A new KeyState object is created only when a new member is being added to the cache. Looking up, removing or replacing a value by key does not require construction of a new KeyState because Key and KeyState implement compatible equals and hashCode methods.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_INITIAL_SIZE Initial size of the backing hash table.
static Object	NULL Constant used to indicate the value associated with a particular Key is known to be null rather than unknown.

Constructor Summary

Constructors

Constructor and Description
ObjectCache()

Method Summary

Modifier and Type	Method and Description
void	clean() Remove all dead entries from this cache.
void	clear() Remove all entries from this cache.
Object	get(Key key) Return the Object value associated with the key if it is present in the cache; otherwise null.
Object	getWithNull(Key key) Return the Object value associated with the key if it is present in the cache; otherwise null.
boolean	isCached(Key key) Indicates whether there is a value associated with the key.
Object	put(Key key, Object value) Inserts a key/value pair in the cache and returns the formerly cached value, if there is one.
Object	remove(Key key) Remove the entry for the specified key, if present, and return its former value.

Methods inherited from class java.lang.Object

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

Field Detail

NULL

public static final Object NULL

Constant used to indicate the value associated with a particular Key is known to be null rather than unknown.

DEFAULT_INITIAL_SIZE

public static final int DEFAULT_INITIAL_SIZE

Initial size of the backing hash table.

See Also:

Constant Field Values

Constructor Detail

ObjectCache

public ObjectCache()

Method Detail

clear

public void clear()

Remove all entries from this cache.

clean

public void clean()

Remove all dead entries from this cache. A dead reference is one for which the referent value of the SoftReference has been removed by the garbage collector.

put

public Object put(Key key,
                  Object value)

Inserts a key/value pair in the cache and returns the formerly cached value, if there is one. The object used to identify the value in the cache is a KeyState constructed from the the supplied Key. Key and KeyState implement compatible equals and hashCode methods so that they can be used interchangeably to access values in maps.

The value is held within a SoftReference. This means that as soon as no other object holds a strong reference to the value, the garbage collector is permitted to remove it and to set the referent of the SoftReference to null. Therefore an application may put a value into this cache and then at some later time receive null from the get method.

This method handles null values in a special way. The code

 objectCache.put(key, null)
 

stores the constant NULL to represent the knowledge that the value associated with key is null, rather than unknown. The get(com.persistit.Key) method returns null regardless of whether the value in the cache is NULL or is not present. Applications should use the isCached(com.persistit.Key) method to determine whether the value is affirmatively null. Alternatively, applications may use the getWithNull(com.persistit.Key) method and then test the result for equality with NULL as a distinct value.

Parameters:

key - The Key used to identify the value. When storing a new key, this method constructs and stores an immutable KeyState from the Key so that the mapping remains valid even if the Key subsequently changes.

value - An Object that is to be associated with key. The value may be any class, and it may be null.

Returns:

The former value.

get

public Object get(Key key)

Return the Object value associated with the key if it is present in the cache; otherwise null. This method does not differentiate between a stored null value and a value missing from the cache. Applications should use the isCached(com.persistit.Key) method or getWithNull(com.persistit.Key) to determine whether the there is a value associated with the key.

Parameters:

key - The key to which the value is associated.

Returns:

The value, or null if there is none.

getWithNull

public Object getWithNull(Key key)

Return the Object value associated with the key if it is present in the cache; otherwise null. This method differentiates between between a stored null value and a value missing from the cache. In the former case, this method returns NULL. Applications can test the result as follows:

 Object o = cache.getWithNull(key);
 if (o == null) ... //not cached
 else if (o == ObjectCache.NULL) .. // value is known to be null
 else ... // o represents a cached object
 

Parameters:

key - The key to which the value is associated.

Returns:

The value, NULL if the value associated with the key is known to be null, or null if the there is no cached value for this key.

isCached

public boolean isCached(Key key)

Indicates whether there is a value associated with the key.

Parameters:

key -

Returns:

true if the cache contains a representation of the value associated with the key; otherwise false

remove

public Object remove(Key key)

Remove the entry for the specified key, if present, and return its former value.

Parameters:

key - The Key

Returns:

The value formerly associated in the cache with the supplied key. The behavior is the same as getWithNull(com.persistit.Key); that is, the returned value value is an object, NULL or null.