org.hackystat.utilities.uricache
Class UriCache

java.lang.Object
  extended by org.hackystat.utilities.uricache.UriCache

public class UriCache
extends java.lang.Object

Provides a wrapper around Apache JCS (Java Caching System) to facilitate Hackystat caching. This wrapper provides the following:

Here's an example usage, where we create a separate cache for each user to hold their sensor data instances as part of the dailyprojectdata service.
 SensorBaseClient client = new SensorBaseClient(user, host);
 UriCache cache = new UriCache(user.getEmail(), "dailyprojectdata");
   :
 SensorData data = (SensorData)cache.get(uriString);
 if (data == null) {
   // Cache doesn't have it, so retrieve from SensorBase and cache locally for next time.
   data = client.getSensorData(uriString);
   cache.put(uriString, data);
 }
 
The cache files are in the directory ~/.hackystat/dailyprojectdata/uricache. Instances expire from the cache after one day, by default. The maximum number of in-memory instances is 10,000, by default.

Author:
Philip Johnson

Constructor Summary
UriCache(java.lang.String cacheName, java.lang.String subDir)
          Creates a new UriCache instance with the specified name.
UriCache(java.lang.String cacheName, java.lang.String subDir, java.lang.Double maxLifeDays, java.lang.Long capacity)
          Creates a new UriCache with the specified parameters.
 
Method Summary
 void clear()
          Removes everything in the default cache, but not any of the group caches.
 void clearAll()
          Clears the default as well as all group caches.
 void clearGroup(java.lang.String group)
          Removes everything in the specified group.
static void dispose(java.lang.String cacheName)
          Shuts down the specified cache, and removes it from the list of active caches so it can be created again.
 java.lang.Object get(java.io.Serializable key)
          Returns the object associated with key from the cache, or null if not found.
 java.lang.Object getFromGroup(java.io.Serializable key, java.lang.String group)
          Implements group-based retrieval of cache elements.
 java.util.Set<java.io.Serializable> getGroupKeys(java.lang.String group)
          Returns the set of cache keys associated with this group.
 int getGroupSize(java.lang.String group)
          Returns the current number of elements in this cache group.
 java.util.Set<java.io.Serializable> getKeys()
          Returns the set of keys associated with this cache.
 void put(java.io.Serializable key, java.io.Serializable value)
          Adds the key-value pair to this cache.
 void put(java.io.Serializable key, java.io.Serializable value, double maxLifeHours)
          Adds the key-value pair to this cache with an explicit expiration time.
 void putInGroup(java.io.Serializable key, java.lang.String group, java.io.Serializable value)
          Implements group-based addition of cache elements.
 void remove(java.io.Serializable key)
          Ensures that the key-value pair associated with key is no longer in this cache.
 void removeFromGroup(java.io.Serializable key, java.lang.String group)
          Implements group-based removal of cache elements.
 void setLoggingLevel(java.lang.String level)
          Sets the logging level for this logger to level.
 int size()
          Returns the current number of elements in this cache.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

UriCache

public UriCache(java.lang.String cacheName,
                java.lang.String subDir)
Creates a new UriCache instance with the specified name. Good for services who want to create a single cache for themselves, such as "dailyprojectdata". If the cache with this name has been previously created, then this instance will become an alias to the previously existing cache.

Parameters:
cacheName - The name of this cache.
subDir - the .hackystat subdirectory in which the uricache directory holding the backing store will be created.

UriCache

public UriCache(java.lang.String cacheName,
                java.lang.String subDir,
                java.lang.Double maxLifeDays,
                java.lang.Long capacity)
Creates a new UriCache with the specified parameters. If a cache with this name already exists, then this instance will be an alias to that cache and its original configuration will remain unchanged.

Parameters:
cacheName - The name of this UriCache, which will be used as the JCS "region" and also define the subdirectory in which the index files will live.
subDir - the .hackystat subdirectory in which the uricache directory holding the backing store will be created.
maxLifeDays - The maximum number of days after which items expire from the cache.
capacity - The maximum number of instances to hold in the cache.
Method Detail

put

public void put(java.io.Serializable key,
                java.io.Serializable value)
Adds the key-value pair to this cache. Entry will expire from cache after the default maxLife (currently 24 hours). Logs a message if the cache throws an exception.

Parameters:
key - The key, typically a UriString.
value - The value, typically the object returned from the Hackystat service.

put

public void put(java.io.Serializable key,
                java.io.Serializable value,
                double maxLifeHours)
Adds the key-value pair to this cache with an explicit expiration time.

Parameters:
key - The key, typically a UriString.
value - The value, typically the object returned from the Hackystat service.
maxLifeHours - The number of hours before this item will expire from cache.

get

public java.lang.Object get(java.io.Serializable key)
Returns the object associated with key from the cache, or null if not found.

Parameters:
key - The key whose associated value is to be retrieved.
Returns:
The value, or null if not found.

remove

public void remove(java.io.Serializable key)
Ensures that the key-value pair associated with key is no longer in this cache. Logs a message if the cache throws an exception.

Parameters:
key - The key to be removed.

clear

public void clear()
Removes everything in the default cache, but not any of the group caches.


clearAll

public void clearAll()
Clears the default as well as all group caches.


getKeys

public java.util.Set<java.io.Serializable> getKeys()
Returns the set of keys associated with this cache.

Returns:
The set containing the keys for this cache.

size

public int size()
Returns the current number of elements in this cache.

Returns:
The current size of this cache.

dispose

public static void dispose(java.lang.String cacheName)
Shuts down the specified cache, and removes it from the list of active caches so it can be created again.

Parameters:
cacheName - The name of the cache to dispose of.

putInGroup

public void putInGroup(java.io.Serializable key,
                       java.lang.String group,
                       java.io.Serializable value)
Implements group-based addition of cache elements.

Parameters:
key - The key.
group - The group.
value - The value.

getFromGroup

public java.lang.Object getFromGroup(java.io.Serializable key,
                                     java.lang.String group)
Implements group-based retrieval of cache elements.

Parameters:
key - The key.
group - The group.
Returns:
The element associated with key in the group, or null.

removeFromGroup

public void removeFromGroup(java.io.Serializable key,
                            java.lang.String group)
Implements group-based removal of cache elements.

Parameters:
key - The key whose value is to be removed.
group - The group.

getGroupKeys

public java.util.Set<java.io.Serializable> getGroupKeys(java.lang.String group)
Returns the set of cache keys associated with this group.

Parameters:
group - The group.
Returns:
The set of cache keys for this group.

getGroupSize

public int getGroupSize(java.lang.String group)
Returns the current number of elements in this cache group.

Parameters:
group - The name of the group.
Returns:
The current size of this cache.

clearGroup

public void clearGroup(java.lang.String group)
Removes everything in the specified group.

Parameters:
group - The group name.

setLoggingLevel

public void setLoggingLevel(java.lang.String level)
Sets the logging level for this logger to level.

Parameters:
level - A string indicating the level, such as "FINE", "INFO", "ALL", etc.