org.sape.carbon.services.cache.total
Class AbstractTotalCache

java.lang.Object
  |
  +--org.sape.carbon.services.cache.total.AbstractTotalCache

All Implemented Interfaces:

Cache, FunctionalInterface, Map, Schedulable, Startable, Suspendable

Direct Known Subclasses:

ReadOnlyCache, WritableCache

public abstract class AbstractTotalCache

extends Object

implements Cache, Startable, Suspendable

This is the base class for caches of data that load all of their contents into memory. The methods implemented here fulfill the requirements of the Cache interfact with the exception of refreshAll. It also implements the Startable and Suspendable interfaces. Refresh and configuration functionality are left up to extending classes.

Copyright 2002 Sapient

Since:

carbon 1.0

Version:

$Revision: 1.7 $($Author: dvoet $ / $Date: 2003/05/05 21:21:08 $)

Author:

Douglas Voet, July 2002

Constructor Summary

AbstractTotalCache()

Method Summary

void	clear() Removes all mappings from this cache.
boolean	containsKey(Object key) For a given key value, return a boolean indicating if the cache contains a value for the key.
boolean	containsValue(Object value) Returns true if this cache maps one or more keys to the specified value.
Set	entrySet() Returns a set view of the mappings contained in this cache.
Object	get(Object key) For a given key value, return the object associated with the key value from the cache.
protected abstract Map	getCacheMap() Returns a referench to the Map that contains all the cached data.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
Set	keySet() Returns the keys of the cache.
Object	put(Object key, Object value) Put the Object value into the cache referenced by the Object key
void	putAll(Map t) Copies all of the mappings from the specified map to this cache.
abstract void	refreshAll() Refresh the contents of the cache.
Object	remove(Object key) Removes the mapping for this key from this cache.
void	resume() Resume the component.
void	runScheduledTask() This execution should flush the cache of the current entries and refill it from the dataloader with new entries.
int	size() Returns the number of key-value mappings in this map.
void	start() Start the component.
void	stop() Stop the component.
void	suspend() Suspend the component.
Collection	values() Returns a collection view of the values contained in this cache.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

AbstractTotalCache

public AbstractTotalCache()

Method Detail

refreshAll

public abstract void refreshAll()
                         throws CacheLoadException

Refresh the contents of the cache. First, initialize a holding cache. Then load the holding cache with new data from the data loader. Finally, activate the holding cache.

Specified by:

refreshAll in interface Cache

Throws:

CacheLoadException - when its data loader has failed to load data

clear

public void clear()

Removes all mappings from this cache.

Specified by:

clear in interface Map

containsKey

public boolean containsKey(Object key)

For a given key value, return a boolean indicating if the cache contains a value for the key.

Specified by:

containsKey in interface Map

Parameters:

key - key for the desired cache entry

Returns:

true if the cache contains a mapping for the specified key

containsValue

public boolean containsValue(Object value)

Returns true if this cache maps one or more keys to the specified value. More formally, returns true if and only if this cache contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will require time linear in the cache size.

Specified by:

containsValue in interface Map

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 a set view of the mappings contained in this cache. Each element in the returned set is a Map.Entry. The set is backed by the cache, so changes to the map are reflected in the set, and vice-versa. If the cache is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the cache, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:

entrySet in interface Map

Returns:

the set of mappings in this cache

get

public Object get(Object key)

For a given key value, return the object associated with the key value from the cache. If the value is not found in the cache, or the key is associated with the value null, a null reference is returned. The only way to tell for certain if the cache contains the key is to use the containsKey() method.

Specified by:

get in interface Map

Parameters:

key - key for the desired cache entry

Returns:

Object

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface Map

Returns:

true if this map contains no key-value mappings

keySet

public Set keySet()

Returns the keys of the cache.

Specified by:

keySet in interface Map

Returns:

Set The set of all keys in the cache.

put

public Object put(Object key,
                  Object value)

Put the Object value into the cache referenced by the Object key

Specified by:

put in interface Map

Parameters:

key - key for the value to add to this cache

value - value to add for the given key

Returns:

the old value stored at the given key

putAll

public void putAll(Map t)

Copies all of the mappings from the specified map to this cache. These mappings will replace any mappings that this cache had for any of the keys currently in the specified cache.

Specified by:

putAll in interface Map

Parameters:

t - the map to place all values of into this cache

remove

public Object remove(Object key)

Removes the mapping for this key from this cache.

Specified by:

remove in interface Map

Parameters:

key - the key to remove from the cache

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.

Specified by:

size in interface Map

Returns:

the number of key-value mappings in this map.

values

public Collection values()

Returns a collection view of the values contained in this cache. The collection is backed by the cache, so changes to the cache are reflected in the collection, and vice-versa.

Specified by:

values in interface Map

Returns:

a collection view of the values contained in this cache

start

public void start()
           throws CacheLoadException

Description copied from interface: Startable

Start the component. On return, the container will begin fowarding requests to the component. This may be an opportunity to dispatch worker threads.

Specified by:

start in interface Startable

CacheLoadException

See Also:

Startable.start()

stop

public void stop()

Description copied from interface: Startable

Stop the component. Prior to entry, the container will cease forwarding requests for service to the component. This is an opportunity to cleanly complete or abort any outstanding work. For example, a set of worker threads could be killed off, or a queue set to drain.

Specified by:

stop in interface Startable

See Also:

Startable.stop()

resume

public void resume()
            throws CacheLoadException

Description copied from interface: Suspendable

Resume the component. This implies "picking-up where you left off". On return of this method, the container will resume forwarding service requests to the component.

Specified by:

resume in interface Suspendable

CacheLoadException

See Also:

Suspendable.resume()

suspend

public void suspend()

Description copied from interface: Suspendable

Suspend the component. This is an opportunity to 'pause' any ongoing work". Prior to calling this method, the container will block requests for service to the component.

Specified by:

suspend in interface Suspendable

See Also:

Suspendable.suspend()

runScheduledTask

public void runScheduledTask()
                      throws CacheLoadException

This execution should flush the cache of the current entries and refill it from the dataloader with new entries.

Specified by:

runScheduledTask in interface Schedulable

Throws:

CacheLoadException - when their is a failure to load the values from the dataloader.

See Also:

Schedulable.runScheduledTask()

getCacheMap

protected abstract Map getCacheMap()

Returns a referench to the Map that contains all the cached data. This is used by the Map interface methods of this class.

Returns:

Map containing the cached data