gov.nist.nlpir.irf.util
Class HashingCache

java.lang.Object
  |
  +--gov.nist.nlpir.irf.util.HashingCache

public class HashingCache

extends java.lang.Object

This cache associates a value to a key, a bit like a hashtable does. When a couple is stored, the value may then be retrieved using the key. But this operation may not succeed in case a couple has been stored with a key having the same hashcode as the first one (collision case). This cache allows values of two different status to be stored: those which are considered dirty, and those which aren't. This way, the client may store a persistent object in the cache, even if this one needs to be written. If the cache destroys this object because of a collision, it will return it as the return value of the destroying method so that the client can then do what's necessary. In the case an object is destroyed but the key associated to the new value is the same as the one for the disappearing object (regarding equals(), the method returns nothing, as this is considered an update "in memory" that doesn't need to be reported to the disk. This feature may be deferred to the client in a later release.

Version:

$Revision: 1.2 $

Author:

This software was produced by NIST, an agency of the U.S. government, and by statute is not subject to copyright in the United States. Recipients of this software assume all responsibilities associated with its operation, modification and maintenance.

Field Summary

private boolean[]	dirty For every couple (keys[i], values[i]), must it be returned when it's removed from the cache because of a collision?
private java.lang.Object[]	keys Array keeping track of the stored keys.
private int	size Current size of cache, ie of each of its arrays.
private java.lang.Object[]	values Array containing the values.

Constructor Summary

HashingCache(int maxEntries)
Builds a new cache with the given size.

Method Summary

java.lang.Object[]	add(java.lang.Object key, java.lang.Object value) Adds an object (key-value pair) to the queue.
java.lang.Object	find(java.lang.Object key) Find the most recently added value with the given key
java.lang.Object[]	getDirtyValues()
private java.lang.Object[]	internPut(int range, java.lang.Object key, java.lang.Object value, boolean willBeDirty) Common part to put() and add(), this method seeks the right place in the two tables.
void	present() Present the contents of the cache, in the form: d key1 <=> value1 for couples that are marked dirty, key2 <=> value2 for the others.
java.lang.Object[]	put(java.lang.Object key, java.lang.Object value) Same as add with no dirty bit.
java.lang.Object[]	setMaxEntries(int newMaxEntries) This method allows to dynamically change the size of the cache.

Methods inherited from class java.lang.Object

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

Field Detail

keys

private java.lang.Object[] keys

Array keeping track of the stored keys.

values

private java.lang.Object[] values

Array containing the values.

dirty

private boolean[] dirty

For every couple (keys[i], values[i]), must it be returned when it's removed from the cache because of a collision?

size

private int size

Current size of cache, ie of each of its arrays.

Constructor Detail

HashingCache

public HashingCache(int maxEntries)

Builds a new cache with the given size.

Method Detail

setMaxEntries

public java.lang.Object[] setMaxEntries(int newMaxEntries)

This method allows to dynamically change the size of the cache. It returns the objects that were marked as dirty when they were put in the cache. The format of the returned array is the same as the one from getDirtyValues() .

See Also:

getDirtyValues()

add

public final java.lang.Object[] add(java.lang.Object key,
                                    java.lang.Object value)

Adds an object (key-value pair) to the queue. This is considered a new object in the table, i.e. it should be written before leaving the cache. For this, it will be returned with its key by the add() or put() method that will delocate it.

Parameters:

key - of object to be added

value - of object to be added

Returns:

If a collision occured, an array of two objects containing the removed key and the removed object in [0] and [1]. This only if this couple was marked dirty, ie put by add(), and its key is different from the new one given.
Otherwise, null.

put

public final java.lang.Object[] put(java.lang.Object key,
                                    java.lang.Object value)

Same as add with no dirty bit.

Returns:

If a collision occured, an array of two objects containing the removed key and the removed object in [0] and [1]. This only if this couple was marked dirty, ie put by add(), and its key is different from the new one given.
Otherwise, null.

internPut

private final java.lang.Object[] internPut(int range,
                                           java.lang.Object key,
                                           java.lang.Object value,
                                           boolean willBeDirty)

Common part to put() and add(), this method seeks the right place in the two tables. If an object is already present, AND it is marked dirty (it was introduced here with add() and not put() , AND THE KEY IS DIFFERENT OF THE NEW ONE, then it is returned by this method: the client should save the value if he wants to keep track of it.

find

public final java.lang.Object find(java.lang.Object key)

Find the most recently added value with the given key

Parameters:

key - search key of object sought

Returns:

the most recent value with the given key or null if none found

getDirtyValues

public java.lang.Object[] getDirtyValues()

Returns:

an array of couples of values that are marked dirty. Each Object of even indice is the key associated in the table to the value that is just after it in the array.

present

public void present()

Present the contents of the cache, in the form:
d key1 <=> value1 for couples that are marked dirty,
key2 <=> value2 for the others.