com.bigdata.util.concurrent

Class CanonicalFactory<KEY,VAL,STATE>

java.lang.Object

com.bigdata.util.concurrent.CanonicalFactory<KEY,VAL,STATE>

Type Parameters:

KEY -

VAL -

STATE -

public abstract class CanonicalFactory<KEY,VAL,STATE>
extends Object

A pattern for a canonicalizing factory based on a map with weak values.

Author:

thompsonbry

Constructor Summary

Constructors

Constructor and Description
CanonicalFactory(int queueCapacity)

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clear all entries from the cache.
Iterator<Map.Entry<KEY,WeakReference<VAL>>>	entryIterator() An iterator that visits the entries in the map.
VAL	getInstance(KEY key, STATE state) Canonical factory pattern.
protected abstract VAL	newInstance(KEY key, STATE state) Create an instance which will be associated with the key in the CanonicalFactory.
void	remove(KEY key) Remove an entry from the cache.

Methods inherited from class java.lang.Object

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

Constructor Detail

CanonicalFactory

public CanonicalFactory(int queueCapacity)

Parameters:

queueCapacity - The capacity of the backing hard reference queue. This places a lower bound on the #of instances which will be retained by the factory.

Method Detail

getInstance

public VAL getInstance(KEY key,
              STATE state)

Canonical factory pattern.

Parameters:

key - The key.

state - Additional state from the caller which will be passed through to newInstance(Object, Object) when creating a new instance (optional).

Returns:

The instance paired with that key.

Throws:

IllegalArgumentException - if the key is null.

remove

public void remove(KEY key)

Remove an entry from the cache.

Note: It is sometimes necessary to clear a cache entry. For example, if a persistent resource is destroyed it may be necessary to discard the cache entry to avoid inappropriate carry over via the cache if the resource is then recreated.

Parameters:

key - The key for the entry.

Throws:

IllegalArgumentException - if the key is null.

newInstance

protected abstract VAL newInstance(KEY key,
              STATE state)

Create an instance which will be associated with the key in the CanonicalFactory.

Parameters:

key - The key.

state - Additional state used to initialize the new instance (optional).

Returns:

The new instance to be paired with that key.

clear

public void clear()

Clear all entries from the cache.

entryIterator

public Iterator<Map.Entry<KEY,WeakReference<VAL>>> entryIterator()

An iterator that visits the entries in the map. You must test the weak reference for each entry in order to determine whether its value has been cleared as of the moment that you request that value. The entries visited by the iterator are not "touched" so the use of the iterator will not cause them to be retained any longer than they otherwise would have been retained.