Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## echopointng.util.collections
Class ExpiryCache

    java.lang.Object
      echopointng.util.collections.ExpiryCache

All Implemented Interfaces:
  java.util.Map

Direct Known Subclasses:
  TimerExpiryCache

    public class ExpiryCache

extends java.lang.Object
implements java.util.Map

`ExpiryCache` implements a `Map` cache contains objects that "expire".

By default, soft references are used to the cached data so that they can be reclaimed in low memory conditions regardless of whether they have expired or not.

The time-to-live and access-timeout is used to decide when an object has expired and needs to be removed from the cache.

Time-to-live is simple. Once the specified period elapses, the object is removed from the cache, regardless of how many times its been accessed.

Access-timeout is a little more complicated. Each time the object is taken from the cache, its lastAccessTime is tracked. If the access-timeout has expired (since its last access) then the object is taken from the cache.

If both the time-to-live and access-timeout is -1, then the object will never expire from the cache.

The objVersion value, which can be specified at put time, can be later retrieved along with the object. This allows for application level versioning of objects against when they put in the cache. For example if you cached the contents of a File read, you might want to store the File.lastModified() in the objVersion number. Later when you want the cached contents, you could check the put time objVersion number against the current File.lastModified(). So even though the cached content has not expired, the underlying content has and hence should be re-read.

Under the cover this class uses a ConcurrentReaderHashMap and hence is thread safe for writes to the cache.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map
`java.util.Map.Entry<K,V>`

Field Summary
`static long` | `DEFAULT_ACCESS_TIMEOUT` the default cache access time out 5 minutes
`static long` | `DEFAULT_TIME_TO_LIVE` the default cache time-to-live is 10 minutes

Constructor Summary
`ExpiryCache()` Constructs a default `ExpiryCache` that uses `SoftReference`s
`ExpiryCache(long timeToLive, long accessTimeout)` Constructs a `ExpiryCache` that uses `SoftReference`s
`ExpiryCache(long timeToLive, long accessTimeout, boolean softReferences)` Constructs a `ExpiryCache` with all the parameters

Method Summary
`void` | `clear()`
`boolean` | `containsKey(java.lang.Object key)`
`boolean` | `containsValue(java.lang.Object value)` This operation is not supported on ExpiryCache.
`java.util.Set` | `entrySet()` This operation is not supported on ExpiryCache.
`java.lang.Object` | `get(java.lang.Object key)` Retrieves an object from the cache.
`java.lang.Object` | `get(java.lang.Object key, long objVersion)` Retrieves an object from the cache.
`boolean` | `hasExpired(java.lang.Object key, long when)` Called to see if a cache entry has expired or not at a given point in time.
`int` | `howManyTimesAccessed(java.lang.Object key)` Returns the number of times the object was accessed under a given key
`boolean` | `isEmpty()` Note this may return false when in fact all objects in the cache have expired.
`boolean` | `isSoftReferences()` Returns true if `SoftReference`s are used to cached data
`java.util.Set` | `keySet()` Returns a Set of all the keys in the cache.
`protected void` | `onExpiredObject(java.lang.Object key)` Called when an object has been detected as expired or versioned out of existence.
`java.lang.Object` | `put(java.lang.Object key, java.lang.Object objToCache)` Places an object into the cache.
`java.lang.Object` | `put(java.lang.Object key, java.lang.Object objToCache, long objVersion)` Places an object into the cache.
`java.lang.Object` | `put(java.lang.Object key, java.lang.Object objToCache, long timeToLive, long accessTimeout)` Places an object into the cache with the specified 'time-to-live' and a 'access time out' value.
`java.lang.Object` | `put(java.lang.Object key, java.lang.Object objToCache, long timeToLive, long accessTimeout, long objVersion)` Places an object into the cache with the specified 'time-to-live' and a 'access time out' value as well as a version number.
`void` | `putAll(java.util.Map t)`
`java.lang.Object` | `remove(java.lang.Object key)`
`void` | `setAccessTimeout(long milliSecs)` Sets the default access timeout for a cache entry
`void` | `setSoftReferences(boolean newValue)` Sets whether `SoftReference`s are used to hold cache entries.
`void` | `setTimeToLive(long milliSecs)` Sets the default 'time-to-live' for a cache entry
`int` | `size()` Note this may return a size larger than the number of non expired objects.
`java.util.Collection` | `values()` This operation is not supported on ExpiryCache.
`long` | `whenCached(java.lang.Object key)` Returns the time when the object was cached under a given key
`long` | `whenLastAccessed(java.lang.Object key)` Returns the time when the object was last accessed under a given key
`long` | `whenVersion(java.lang.Object key)` Returns the version number that was provided when the object was placed in the 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`

Field Detail

### DEFAULT_TIME_TO_LIVE

    public static final long DEFAULT_TIME_TO_LIVE

  the default cache time-to-live is 10 minutes

  See Also:
    Constant Field Values

### DEFAULT_ACCESS_TIMEOUT

    public static final long DEFAULT_ACCESS_TIMEOUT

  the default cache access time out 5 minutes

  See Also:
    Constant Field Values

Constructor Detail

### ExpiryCache

    public ExpiryCache()

  Constructs a default `ExpiryCache` that uses `SoftReference`s

### ExpiryCache

    public ExpiryCache(long timeToLive,
                       long accessTimeout)

  Constructs a `ExpiryCache` that uses `SoftReference`s

  Parameters:
    `timeToLive` - - the default time-to-live for a cache entry
    `accessTimeout` - - the default access timeout for a cache entry

### ExpiryCache

    public ExpiryCache(long timeToLive,
                       long accessTimeout,
                       boolean softReferences)

  Constructs a `ExpiryCache` with all the parameters

  Parameters:
    `timeToLive` - - the default time-to-live for a cache entry
    `accessTimeout` - - the default access timeout for a cache entry
    `softReferences` - - whether `SoftReference`s are used to cached data

Method Detail

### setTimeToLive

    public void setTimeToLive(long milliSecs)

  Sets the default 'time-to-live' for a cache entry

  Parameters:
    `milliSecs` - - 'time-to-live' for a cache entry

### setAccessTimeout

    public void setAccessTimeout(long milliSecs)

  Sets the default access timeout for a cache entry

  Parameters:
    `milliSecs` - - access timeout for a cache entry

### whenCached

    public long whenCached(java.lang.Object key)

  Returns the time when the object was cached under a given key

  Parameters:
    `key` - - the key to the cached object
  Returns:
    the time when the object was cached under a given key

### whenLastAccessed

    public long whenLastAccessed(java.lang.Object key)

  Returns the time when the object was last accessed under a given key

  Parameters:
    `key` - - the key to the cached object
  Returns:
    the time when the object was last accessed under a given key

### whenVersion

    public long whenVersion(java.lang.Object key)

  Returns the version number that was provided when the object was placed in the cache.

  Parameters:
    `key` - - the key to the cached object
  Returns:
    the version number that was provided when the object was placed in the cache or -1 if it was not provided at cache put.

### howManyTimesAccessed

    public int howManyTimesAccessed(java.lang.Object key)

  Returns the number of times the object was accessed under a given key

  Parameters:
    `key` - - the key to the cached object
  Returns:
    the number of times the object was accessed under a given key

### isSoftReferences

    public boolean isSoftReferences()

  Returns true if `SoftReference`s are used to cached data

  Returns:
    true if `SoftReference`s are used to cached data

### setSoftReferences

    public void setSoftReferences(boolean newValue)

  Sets whether `SoftReference`s are used to hold cache entries.

  Parameters:
    `newValue` - - the new value of the flag

### clear

    public void clear()

  Specified by:
    `clear` in interface `java.util.Map`
  See Also:
    `Map.clear()`

### containsKey

    public boolean containsKey(java.lang.Object key)

  Specified by:
    `containsKey` in interface `java.util.Map`
  See Also:
    `Map.containsKey(java.lang.Object)`

### remove

    public java.lang.Object remove(java.lang.Object key)

  Specified by:
    `remove` in interface `java.util.Map`
  See Also:
    `Map.remove(java.lang.Object)`

### size

    public int size()

  Note this may return a size larger than the number of non expired objects. A traversal of cached objects is NOT done here to work out a correct size value.

  Specified by:
    `size` in interface `java.util.Map`
  See Also:
    `Map.size()`

### isEmpty

    public boolean isEmpty()

  Note this may return false when in fact all objects in the cache have expired. A traversal of cached objects is NOT done here to work out if it is empty.

  Specified by:
    `isEmpty` in interface `java.util.Map`
  See Also:
    `Map.isEmpty()`

### putAll

    public void putAll(java.util.Map t)

  Specified by:
    `putAll` in interface `java.util.Map`
  See Also:
    `Map.putAll(java.util.Map)`

### keySet

    public java.util.Set keySet()

  Returns a Set of all the keys in the cache. It may contain keys to objects that have expired so be careful when using this.

  Specified by:
    `keySet` in interface `java.util.Map`
  Returns:
    a Set of all the keys in the cache

### entrySet

    public java.util.Set entrySet()

  This operation is not supported on ExpiryCache.

  Specified by:
    `entrySet` in interface `java.util.Map`
  Throws:
    `java.lang.UnsupportedOperationException`

### values

    public java.util.Collection values()

  This operation is not supported on ExpiryCache.

  Specified by:
    `values` in interface `java.util.Map`
  Throws:
    `java.lang.UnsupportedOperationException`

### containsValue

    public boolean containsValue(java.lang.Object value)

  This operation is not supported on ExpiryCache.

  Specified by:
    `containsValue` in interface `java.util.Map`
  Throws:
    `java.lang.UnsupportedOperationException`

### put

    public java.lang.Object put(java.lang.Object key,
                                java.lang.Object objToCache)

  Places an object into the cache. The object will have a caches default 'time-to-live' and a caches default 'access time out' value.

  Specified by:
    `put` in interface `java.util.Map`
  Parameters:
    `key` - - the key of the cached object
    `objToCache` - - the object to cache
  Returns:
    - the old object at this cache key

### put

    public java.lang.Object put(java.lang.Object key,
                                java.lang.Object objToCache,
                                long objVersion)

  Places an object into the cache. The object will have a caches default 'time-to-live' and a caches default 'access time out' value.

  Parameters:
    `key` - - the key of the cached object
    `objToCache` - - the object to cache
    `objVersion` - - the version of the object at the time it is put
  Returns:
    - the old object at this cache key

### put

    public java.lang.Object put(java.lang.Object key,
                                java.lang.Object objToCache,
                                long timeToLive,
                                long accessTimeout)

  Places an object into the cache with the specified 'time-to-live' and a 'access time out' value.

  Parameters:
    `key` - - the key of the cached object
    `objToCache` - - the object to cache
    `timeToLive` - - the time-to-live on the object or -1 to live for ever
    `accessTimeout` - - the accessTimeout on the object or -1 to never time out
  Returns:
    - the old object at this cache key

### put

    public java.lang.Object put(java.lang.Object key,
                                java.lang.Object objToCache,
                                long timeToLive,
                                long accessTimeout,
                                long objVersion)

  Places an object into the cache with the specified 'time-to-live' and a 'access time out' value as well as a version number.

  Parameters:
    `key` - - the key of the cached object
    `objToCache` - - the object to cache
    `timeToLive` - - the time-to-live on the object or -1 to live for ever
    `accessTimeout` - - the accessTimeout on the object or -1 to never time out
    `objVersion` - - a version number that can be used later
  Returns:
    - the old object at this cache key

### get

    public java.lang.Object get(java.lang.Object key)

  Retrieves an object from the cache. If the object has expired, then it will return null

  Specified by:
    `get` in interface `java.util.Map`
  Parameters:
    `key` - - the key to the cached object
  Returns:
    the object for the key or null

### get

    public java.lang.Object get(java.lang.Object key,
                                long objVersion)

  Retrieves an object from the cache. If the object has expired or its recorded put version is less then the objVersion, then it will return null.

  Parameters:
    `key` - - the key to the cached object
    `objVersion` - - the object version number to compare against
  Returns:
    the object for the key or null

### onExpiredObject

    protected void onExpiredObject(java.lang.Object key)

  Called when an object has been detected as expired or versioned out of existence.

  Parameters:
    `key` - - the key to the object

### hasExpired

    public boolean hasExpired(java.lang.Object key,
                              long when)

  Called to see if a cache entry has expired or not at a given point in time.

  Parameters:
    `key` - - the key to the cached object
    `when` - - the time to do the comparision against
  Returns:
    true if the object has expired in the cache or cant be found in the cache.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD