MemoryCache (MollyPages.org Foundation API)

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 and Description
`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

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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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 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)
```

Class MemoryCache

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ONE_SEC

ONE_SECOND

FIVE_SEC

FIVE_SECOND

TEN_SEC

TEN_SECOND

THIRTY_SEC

THIRTY_SECOND

ONE_MIN

TWO_MIN

FIVE_MIN

TEN_MIN

THIRTY_MIN

ONE_HOUR

TWO_HOUR

FOUR_HOUR

EIGHT_HOUR

Constructor Detail

MemoryCache

MemoryCache

Method Detail

setReapInterval

setReapThreadPriority

containsKey

get

getAll

getTimeLeft

put

put

expireTimeLeft

expire

extend

close

isClosed

setDefaultTTL

getDefaultTTL

clear

toString

main