fc.util.cache
Class MemoryCache

java.lang.Object
  extended by fc.util.cache.MemoryCache
All Implemented Interfaces:
Cache

public final class MemoryCache
extends Object
implements Cache

Memory resident cache of objects. Allows to set expire times for contained objects after which those expired objects are removed. By default, references to expired objects are not retained in the cache, such that those object may be garbage collected as needed by the garbage collector (if those objects becomes unreachable from the rest of the program).

The size of this cache is unbounded. To use a bounded cache, use the BoundedCache class.

Expired items are reaped via a background high priority thread that sleeps for intervals between expired item checks. After every reap operation, the reaper thread sleeps for 120 seconds (by default). This implies that the minimum expire time for any item will be 120 seconds. This sleep time can be changed via the setReapInterval(long) method.

ThreadSafety: This class is thread safe and can be used by multiple threads concurrently.

Version:
1.0 12/29/2001

Field Summary
static long EIGHT_HOUR
          Useful constant for cache expiry time of eight hours (in milliseconds)
static long FIVE_MIN
          Useful constant for cache expiry time of five minutes (in milliseconds)
static long FIVE_SEC
          Useful constant of five seconds (in milliseconds)
static long FIVE_SECOND
          Useful constant of five seconds (in milliseconds)
static long FOUR_HOUR
          Useful constant for cache expiry time of four hours (in milliseconds)
static long ONE_HOUR
          Useful constant for cache expiry time of one hour (in milliseconds)
static long ONE_MIN
          Useful constant for cache expiry time of 1 minute (in milliseconds)
static long ONE_SEC
          Useful constant of 1 second (in milliseconds)
static long ONE_SECOND
          Useful constant of 1 second (in milliseconds)
static long TEN_MIN
          Useful constant for cache expiry time of ten minutes (in milliseconds)
static long TEN_SEC
          Useful constant of ten seconds (in milliseconds)
static long TEN_SECOND
          Useful constant of ten seconds (in milliseconds)
static long THIRTY_MIN
          Useful constant for cache expiry time of thirty minutes (in milliseconds)
static long THIRTY_SEC
          Useful constant of 30 seconds (in milliseconds)
static long THIRTY_SECOND
          Useful constant of 30 seconds (in milliseconds)
static long TWO_HOUR
          Useful constant for cache expiry time of two hours (in milliseconds)
static long TWO_MIN
          Useful constant for cache expiry time of 2 minutes (in milliseconds)
 
Constructor Summary
MemoryCache()
          Creates a memory cache with a system-assigned logger and name and a default ttl of 30 minutes.
MemoryCache(Log log, String name, long default_ttl_millis)
          Instantiates this class with the specified name and logger.
 
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.
 long expireTimeLeft(Object key)
           
 void extend(Object key, long renewTime)
          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.
static void main(String[] args)
           
 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.
 void setReapInterval(long interval)
          Sets the minimum time between expired item checks.
 void setReapThreadPriority(int priority)
          Sets the cache reaper thread priority.
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ONE_SEC

public static final long ONE_SEC
Useful constant of 1 second (in milliseconds)

See Also:
Constant Field Values

ONE_SECOND

public static final long ONE_SECOND
Useful constant of 1 second (in milliseconds)

See Also:
Constant Field Values

FIVE_SEC

public static final long FIVE_SEC
Useful constant of five seconds (in milliseconds)

See Also:
Constant Field Values

FIVE_SECOND

public static final long FIVE_SECOND
Useful constant of five seconds (in milliseconds)

See Also:
Constant Field Values

TEN_SEC

public static final long TEN_SEC
Useful constant of ten seconds (in milliseconds)

See Also:
Constant Field Values

TEN_SECOND

public static final long TEN_SECOND
Useful constant of ten seconds (in milliseconds)

See Also:
Constant Field Values

THIRTY_SEC

public static final long THIRTY_SEC
Useful constant of 30 seconds (in milliseconds)

See Also:
Constant Field Values

THIRTY_SECOND

public static final long THIRTY_SECOND
Useful constant of 30 seconds (in milliseconds)

See Also:
Constant Field Values

ONE_MIN

public static final long ONE_MIN
Useful constant for cache expiry time of 1 minute (in milliseconds)

See Also:
Constant Field Values

TWO_MIN

public static final long TWO_MIN
Useful constant for cache expiry time of 2 minutes (in milliseconds)

See Also:
Constant Field Values

FIVE_MIN

public static final long FIVE_MIN
Useful constant for cache expiry time of five minutes (in milliseconds)

See Also:
Constant Field Values

TEN_MIN

public static final long TEN_MIN
Useful constant for cache expiry time of ten minutes (in milliseconds)

See Also:
Constant Field Values

THIRTY_MIN

public static final long THIRTY_MIN
Useful constant for cache expiry time of thirty minutes (in milliseconds)

See Also:
Constant Field Values

ONE_HOUR

public static final long ONE_HOUR
Useful constant for cache expiry time of one hour (in milliseconds)

See Also:
Constant Field Values

TWO_HOUR

public static final long TWO_HOUR
Useful constant for cache expiry time of two hours (in milliseconds)

See Also:
Constant Field Values

FOUR_HOUR

public static final long FOUR_HOUR
Useful constant for cache expiry time of four hours (in milliseconds)

See Also:
Constant Field Values

EIGHT_HOUR

public static final long EIGHT_HOUR
Useful constant for cache expiry time of eight hours (in milliseconds)

See Also:
Constant Field Values
Constructor Detail

MemoryCache

public MemoryCache(Log log,
                   String name,
                   long default_ttl_millis)
Instantiates this class with the specified name and logger.

Parameters:
name - String denoting the name for this object
logger - a reference to a Log
default_ttl - the default time to live for objects in the cache (in milliseconds) (objects may appear to live for greater than the ttl if the the reaper interval time is greater than this value). Also note, that this is the default time and that the put method allows a different ttl for each individual object.

MemoryCache

public MemoryCache()
Creates a memory cache with a system-assigned logger and name and a default ttl of 30 minutes.

Method Detail

setReapInterval

public void setReapInterval(long interval)
Sets the minimum time between expired item checks.


setReapThreadPriority

public void setReapThreadPriority(int priority)
Sets the cache reaper thread priority. By default the reaper runs at MAX_PRIORITY - 1 but if there are a lot of low priority caches, setting this to a lower priority could be useful.


containsKey

public boolean containsKey(Object key)
Description copied from interface: Cache
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.

Specified by:
containsKey in interface Cache
Parameters:
key - typically a String but can be any object

get

public Object get(Object key)
Description copied from interface: Cache
Returns the cached item specified by the key. If no item is found for that key or if the item has expired, returns null.

Specified by:
get in interface Cache
Parameters:
key - typically a String but can be any object

getAll

public Map getAll()
Description copied from interface: Cache
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.

Specified by:
getAll in interface Cache

getTimeLeft

public long getTimeLeft(Object key)
Description copied from interface: Cache
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.

Specified by:
getTimeLeft in interface Cache
Parameters:
key - the key with which to find the object under consideration.

put

public Object put(Object key,
                  Object val,
                  long expiry)
Description copied from interface: Cache
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).

Specified by:
put in interface Cache
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

public Object put(Object key,
                  Object item)
Description copied from interface: Cache
Convenience method that puts an object into the cache that expires in the default TTL. The default TTL can be get/set by the Cache.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).

Specified by:
put in interface Cache

expireTimeLeft

public long expireTimeLeft(Object key)

expire

public void expire(Object key)
Description copied from interface: Cache
Expires immediately the object specified by the key. Overrides any previous setting for that object's expire time.

Specified by:
expire in interface Cache
Parameters:
key - the key with which to find the object under consideration.

extend

public void extend(Object key,
                   long renewTime)
Description copied from interface: Cache
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.

Specified by:
extend in interface Cache
Parameters:
key - the key with which to find the object under consideration.
renewTime - exntension time in milliseconds, valid values are >= 0 and -1

close

public 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.

Note:, it is a good idea to close the cache once it's not needed, because it releases resources, including any internal threads spawned and used by this implementation.

Specified by:
close in interface Cache

isClosed

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

Specified by:
isClosed in interface Cache

setDefaultTTL

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

Specified by:
setDefaultTTL in interface Cache

getDefaultTTL

public long getDefaultTTL()
Gets the default TTL in milliseconds.

Specified by:
getDefaultTTL in interface Cache

clear

public void clear()
Description copied from interface: Cache
Empties the entire cache by expiring and removing all objects.

Specified by:
clear in interface Cache

toString

public String toString()
Overrides:
toString in class Object

main

public static void main(String[] args)