fc.util.cache
Interface Cache

All Known Implementing Classes:
MemoryCache

public interface Cache

A data cache. This is essentially a wrapper over a collection that allows for objects to be cached for a specified amount of time and expired thereafter. Objects in the cache can expire automatically or can be removed manually.

Version:
1.0 12/29/2001

Method Summary
 void clear()
          Empties the entire cache by expiring and removing all objects.
 void close()
          Closes this cache, which makes all items in the cache unavailable.
 boolean containsKey(Object key)
          Returns true if the cache has a valid cached item specified by the key.
 void expire(Object key)
          Expires immediately the object specified by the key.
 void extend(Object key, long extendTime)
          Adds the specified amount of time to the object (to it's current time left) before that object will be expired.
 Object get(Object key)
          Returns the cached item specified by the key.
 Map getAll()
          Returns all objects in the cache.
 long getDefaultTTL()
          Gets the default TTL in milliseconds.
 long getTimeLeft(Object key)
          Returns the amount of time left (in milliseconds) before the object will be expired from the cache.
 boolean isClosed()
          Returns true if this cache has been closed, false otherwise.
 Object put(Object key, Object item)
          Convenience method that puts an object into the cache that expires in the default TTL.
 Object put(Object key, Object val, long expiry)
          Puts the specified object into the cache, mapped with the specified key.
 void setDefaultTTL(long millis)
          Sets the default TTL in milliseconds.
 

Method Detail

clear

void clear()
Empties the entire cache by expiring and removing all objects.


containsKey

boolean containsKey(Object key)
Returns true if the cache has a valid cached item specified by the key. If no item is found for that key or if the item has expired, returns false.

Parameters:
key - typically a String but can be any object

get

Object get(Object key)
Returns the cached item specified by the key. If no item is found for that key or if the item has expired, returns null.

Parameters:
key - typically a String but can be any object

getAll

Map getAll()
Returns all objects in the cache. The returned map is implementation specific but will typically contain pairs of all objects in the cache. The item might be encapsulated in another implementation-specific class.

Modification to this map will affect this cache.


put

Object put(Object key,
           Object val,
           long expiry)
Puts the specified object into the cache, mapped with the specified key. The object stays in the cache for the specified amount of time, after which it is discarded. If that key already contains a value, then that value is returned by this method (and also replaced by the new value).

Parameters:
key - key with which the specified value is to be associated.
val - value to be associated with the specified key.
expiry - time in milliseconds (from the time the object is put into the cache) before it is expired. Specify -1 for the item to never expire.

put

Object put(Object key,
           Object item)
Convenience method that puts an object into the cache that expires in the default TTL. The default TTL can be get/set by the setDefaultTTL(long) method and subclasses are free to implement a default TTL as they see fit. If that key already contains a value, then that value is returned by this method (and also replaced by the new value).


getTimeLeft

long getTimeLeft(Object key)
Returns the amount of time left (in milliseconds) before the object will be expired from the cache.

If the object specified by the key is not found in the cache, then 0 is returned.

If the object has already expired, then 0 is returned.

If the object will never expire, then -1 is returned.

Parameters:
key - the key with which to find the object under consideration.

expire

void expire(Object key)
Expires immediately the object specified by the key. Overrides any previous setting for that object's expire time.

Parameters:
key - the key with which to find the object under consideration.

extend

void extend(Object key,
            long extendTime)
Adds the specified amount of time to the object (to it's current time left) before that object will be expired. Overrides any previous setting that the object may have had, such as never expiring. Specify -1 for that object to never expire. Does not work for objects that have already expired.

Parameters:
key - the key with which to find the object under consideration.
extendTime - exntension time in milliseconds, valid values are >= 0 and -1

setDefaultTTL

void setDefaultTTL(long millis)
Sets the default TTL in milliseconds.


getDefaultTTL

long getDefaultTTL()
Gets the default TTL in milliseconds.


close

void close()
Closes this cache, which makes all items in the cache unavailable. Any items needed for later should be taken out of the cache before closing it.


isClosed

boolean isClosed()
Returns true if this cache has been closed, false otherwise.