Class MemoryCache

java.lang.Object
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

    Fields
    Modifier and Type
    Field
    Description
    static final long
    EIGHT_HOUR
    Useful constant for cache expiry time of eight hours (in milliseconds)
    static final long
    FIVE_MIN
    Useful constant for cache expiry time of five minutes (in milliseconds)
    static final long
    FIVE_SEC
    Useful constant of five seconds (in milliseconds)
    static final long
    FIVE_SECOND
    Useful constant of five seconds (in milliseconds)
    static final long
    FOUR_HOUR
    Useful constant for cache expiry time of four hours (in milliseconds)
    static final long
    ONE_HOUR
    Useful constant for cache expiry time of one hour (in milliseconds)
    static final long
    ONE_MIN
    Useful constant for cache expiry time of 1 minute (in milliseconds)
    static final long
    ONE_SEC
    Useful constant of 1 second (in milliseconds)
    static final long
    ONE_SECOND
    Useful constant of 1 second (in milliseconds)
    static final long
    TEN_MIN
    Useful constant for cache expiry time of ten minutes (in milliseconds)
    static final long
    TEN_SEC
    Useful constant of ten seconds (in milliseconds)
    static final long
    TEN_SECOND
    Useful constant of ten seconds (in milliseconds)
    static final long
    THIRTY_MIN
    Useful constant for cache expiry time of thirty minutes (in milliseconds)
    static final long
    THIRTY_SEC
    Useful constant of 30 seconds (in milliseconds)
    static final long
    THIRTY_SECOND
    Useful constant of 30 seconds (in milliseconds)
    static final long
    TWO_HOUR
    Useful constant for cache expiry time of two hours (in milliseconds)
    static final long
    TWO_MIN
    Useful constant for cache expiry time of 2 minutes (in milliseconds)

  • Constructor Summary

    Constructors
    Constructor
    Description
    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

    Modifier and Type
    Method
    Description
    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 Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

  • Constructor Details

    • 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 Details

    • 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 invalid input: '<'key,item> 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)