com.go.trove.util
Class Depot

java.lang.Object
  |
  +--com.go.trove.util.Depot

public class Depot

extends java.lang.Object

Depot implements a simple and efficient caching strategy. It is thread-safe, and it allows requests of different objects to occur concurrently. Depot is best suited as a front-end for accessing objects from a remote device, like a database. If the remote device is not responding, the Depot will continue to serve invalidated objects so that the requester may continue as normal.

Depot is designed as a cache in front of an object factory. Objects may be invalidated, but they are not explicitly removed from the cache until a replacement has been provided by the factory. The factory is invoked from another thread, allowing for the requester to timeout and use an invalidated object. When the factory eventually finishes, its object will be cached.

By allowing for eventual completion of the factory, Depot enables applications to dynamically adjust to the varying performance and reliability of remote data providers.

Depot will never return an object or null that did not originate from the factory. When retrieving an object that wasn't found cached, a call to the factory will block until it is finished.

Objects may be invalided from the Depot automatically. This approach is based on a fixed time expiration and is somewhat inflexible. An ideal invalidation strategy requires asynchronous notification from the actual data providers.

Version:

14 , 01/07/09

Author:

Brian S O'Neill, Travis Greer

See Also:

MultiKey

Inner Class Summary

static interface	Depot.Factory Implement this interface in order for Depot to retrieve objects when needed, often in a thread other than the requester's.
static interface	Depot.Filter
static interface	Depot.Perishable Values returned from the Factories may implement this interface if they manually handle expiration.
static interface	Depot.PerishablesFactory A special kind of Factory that creates objects that are considered invalid after a specific amount of time has elapsed.

Constructor Summary

Depot(Depot.Factory factory, int cacheSize, TransactionQueue tq, long timeout)

Depot(Depot.Factory factory, java.util.Map validCache, java.util.Map invalidCache, TransactionQueue tq, long timeout)

Method Summary

void	clear() Completely removes all items from the Depot's caches.
java.lang.Object	get(Depot.Factory factory, java.lang.Object key) Retrieve an object from the Depot.
java.lang.Object	get(Depot.Factory factory, java.lang.Object key, long timeout) Retrieve an object from the Depot.
java.lang.Object	get(java.lang.Object key) Retrieve an object from the Depot.
java.lang.Object	get(java.lang.Object key, long timeout) Retrieve an object from the Depot.
void	invalidate(java.lang.Object key) Invalidate the object referenced by the given key, if it is already cached in this Depot.
void	invalidateAll() Invalidates all the objects in the Depot.
void	invalidateAll(Depot.Filter filter) Invalidates objects in the Depot, using a filter.
int	invalidSize() Returns the number of invalid objects in the Depot.
boolean	isEmpty()
void	put(java.lang.Object key, java.lang.Object value) Put a value into the Depot, bypassing the factory.
java.lang.Object	remove(java.lang.Object key) Completely removes an item from the Depot's caches.
void	removeAll(Depot.Filter filter) Completely removes all the items from the Depot that the given filter accepts.
int	size() Returns the total number objects in the Depot.
int	validSize() Returns the number of valid objects in the Depot.

Methods inherited from class java.lang.Object

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

Constructor Detail

Depot

public Depot(Depot.Factory factory,
             java.util.Map validCache,
             java.util.Map invalidCache,
             TransactionQueue tq,
             long timeout)

Parameters:

factory - Default factory from which objects are obtained

validCache - Map to use for caching valid objects

invalidCache - Map to use for caching invalid objects

tq - TransactionQueue for scheduling factory invocations.

timeout - Default timeout (in milliseconds) to apply to "get" method.

Depot

public Depot(Depot.Factory factory,
             int cacheSize,
             TransactionQueue tq,
             long timeout)

Parameters:

factory - Default factory from which objects are obtained

cacheSize - Number of items guaranteed to be in cache, if negative, cache is completely disabled.

tq - TransactionQueue for scheduling factory invocations.

timeout - Default timeout (in milliseconds) to apply to "get" method.

Method Detail

size

public int size()

Returns the total number objects in the Depot.

isEmpty

public boolean isEmpty()

validSize

public int validSize()

Returns the number of valid objects in the Depot.

invalidSize

public int invalidSize()

Returns the number of invalid objects in the Depot.

get

public java.lang.Object get(java.lang.Object key)

Retrieve an object from the Depot. If the requested object is in the cache of valid objects, it is returned immediately. If the object is found in the cache of invalid objects, then it will be returned only if the factory cannot create a replacement in a timely manner. If the requested object is not in any cache at all, the factory is called to create the object, and the calling thread will block until the factory has finished.

Parameters:

key - key of object to retrieve

get

public java.lang.Object get(java.lang.Object key,
                            long timeout)

Retrieve an object from the Depot. If the requested object is in the cache of valid objects, it is returned immediately. If the object is found in the cache of invalid objects, then it will be returned only if the factory cannot create a replacement in a timely manner. If the requested object is not in any cache at all, the factory is called to create the object, and the calling thread will block until the factory has finished.

Parameters:

key - key of object to retrieve

timeout - max time (in milliseconds) to wait for an invalid value to be replaced from the factory, if negative, wait forever. Ignored if no cached value exists at all.

get

public java.lang.Object get(Depot.Factory factory,
                            java.lang.Object key)

Retrieve an object from the Depot. If the requested object is in the cache of valid objects, it is returned immediately. If the object is found in the cache of invalid objects, then it will be returned only if the factory cannot create a replacement in a timely manner. If the requested object is not in any cache at all, the factory is called to create the object, and the calling thread will block until the factory has finished.

Parameters:

factory - factory to use to retrieve object if not cached

key - key of object to retrieve

get

public java.lang.Object get(Depot.Factory factory,
                            java.lang.Object key,
                            long timeout)

Retrieve an object from the Depot. If the requested object is in the cache of valid objects, it is returned immediately. If the object is found in the cache of invalid objects, then it will be returned only if the factory cannot create a replacement in a timely manner. If the requested object is not in any cache at all, the factory is called to create the object, and the calling thread will block until the factory has finished.

Parameters:

factory - factory to use to retrieve object if not cached

key - key of object to retrieve

timeout - max time (in milliseconds) to wait for an invalid value to be replaced from the factory, if negative, wait forever. Ignored if no cached value exists at all.

invalidate

public void invalidate(java.lang.Object key)

Invalidate the object referenced by the given key, if it is already cached in this Depot. Invalidated objects are not removed from the Depot until a replacement object has been successfully created from the factory.

Parameters:

key - key of object to invalidate

invalidateAll

public void invalidateAll(Depot.Filter filter)

Invalidates objects in the Depot, using a filter. Each key that the filter accepts is invalidated.

invalidateAll

public void invalidateAll()

Invalidates all the objects in the Depot.

put

public void put(java.lang.Object key,
                java.lang.Object value)

Put a value into the Depot, bypassing the factory. Invalidating an object and relying on the factory to produce a new value is generally preferred. This method will notify any threads waiting on a factory to produce a value, but it will not disrupt the behavior of the factory.

Parameters:

key - key with which to associate the value.

value - value to be associated with key.

remove

public java.lang.Object remove(java.lang.Object key)

Completely removes an item from the Depot's caches. Invalidating an object is preferred, and remove should be called only if the object should absolutely never be used again.

removeAll

public void removeAll(Depot.Filter filter)

Completely removes all the items from the Depot that the given filter accepts.

clear

public void clear()

Completely removes all items from the Depot's caches. Invalidating all the objects is preferred, and clear should be called only if all the cached objects should absolutely never be used again.