com.arsdigita.caching
Class CacheTable

java.lang.Object
  extended bycom.arsdigita.caching.CacheTable

public class CacheTable
extends Object

Implements simple caching, where storage is limited in both size and age. In case of overflow, the least recently used item is evicted. There can be any number of CacheTable instances throughout the system, however each must have a unique tag. This tag is later used by CacheServlet to synchronize cache between multiple web servers.

Version:
$Revision: #22 $ $DateTime: 2004/05/10 07:13:45 $
Author:
Artak Avetyan, Matthew Booth, Sebastian Skracic

Nested Class Summary
static interface CacheTable.Browser
           
static interface CacheTable.TimestampedEntry
           
 
Field Summary
static CacheTable.Browser BROWSER
          For debugging only.
 
Constructor Summary
CacheTable(String id)
          Creates cache storage tagged with the passed in identificator.
CacheTable(String id, int defSize, int defAge)
          Creates cache storage tagged with the passed in identificator.
 
Method Summary
 Object get(BigDecimal key)
           Retrieves the object stored in cache.
 Object get(String key)
           Retrieves the object stored in cache.
 long getCurrentSize()
          Returns the actual number of items in cache.
 int getMaxAge()
           Returns the maximum cache item age (in seconds).
 void put(BigDecimal key, Object value)
          A convenience wrapper around put(String, Object).
 void put(String key, Object value)
           Puts object in a cache storage.
 void remove(BigDecimal key)
           Removes the object from cache.
 void remove(String key)
           Removes the object from cache.
static void remove(String id, BigDecimal key)
           Static method which removes object from cache.
static void remove(String id, String key)
           Static method which removes object from cache.
 void removeAll()
           
 void setMaxAge(int age)
           Sets the maximum cache item age (in seconds).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BROWSER

public static final CacheTable.Browser BROWSER
For debugging only.

Constructor Detail

CacheTable

public CacheTable(String id)

Creates cache storage tagged with the passed in identificator. This tag must be unique in the sense that no other cache table loaded by this CacheTable's class loader may have the same id.

One of the purposes of the id is to serve as a unique identifier for specifying the configurable parameters of this cache table in system configuration files.

The configurable parameters are waf.caching.[id].max_size and waf.caching.[id].max_age.

Parameters:
id - Unique identifier for the new storage area
Throws:
NullPointerException - if id is null

CacheTable

public CacheTable(String id,
                  int defSize,
                  int defAge)

Creates cache storage tagged with the passed in identificator. This tag must be unique in the sense that no other cache table loaded by this CacheTable's class loader may have the same id.

One of the purposes of the id is to serve as a unique identifier for specifying the configurable parameters of this cache table in system configuration files.

The configurable parameters are waf.caching.[id].max_size and waf.caching.[id].max_age.

Parameters:
id - Unique identifier for the new storage area
Throws:
NullPointerException - if id is null
Method Detail

getMaxAge

public int getMaxAge()

Returns the maximum cache item age (in seconds).


setMaxAge

public void setMaxAge(int age)

Sets the maximum cache item age (in seconds).

Parameters:
age - desired maximum cache size in seconds

getCurrentSize

public long getCurrentSize()
Returns the actual number of items in cache.


put

public void put(BigDecimal key,
                Object value)
A convenience wrapper around put(String, Object).

Parameters:
key - BigDecimal serving as a key for cache lookup
value - Object we're storing in cache

put

public void put(String key,
                Object value)

Puts object in a cache storage. Object must be identified with a unique key.

Implementation note: Any put operation on the CacheTable invokes the remove(String) method which will invalidate that cache entry (if exists) on other nodes. Had the implementation failed to do so, the following scenario might have caused cache incoherence.

To prevent this situation from happening, any insertion must first be preceded by a removal of the affected entry from all peer nodes.

As a performance optimization, we try to be clever and prevent valid objects from being flushed out unnecessarily from peer nodes in the above scenario. This is accomplished by including in the "remove" message the hash code of the object that may need removal from peer nodes. If the hash code sent by node X matches the hash code of the object mapped to the same key on node Y, then the cache entry maintained by Y need not be updated.

Note that for this method to work, any cached object O must hash to the same value regardless of the node on which the hash code is computed. The contract of Object.hashCode() method makes no such guarantees. It is unreasonable to expect that hash codes of the "same object" (for some reasonable definition of "sameness") are always identical across different JVMs. Even if you are running the same JVM version on each of the participating nodes, hash codes of the "same object" are not guaranteed to be identical (although in practice, they often are). As a trivial illustration, consider the following example.

 public final class QuuxEnum {
     public final static QuuxEnum QUUX1 = new QuuxEnum();
     public final static QuuxEnum QUUX2 = new QuuxEnum();
 }
 

The hash code of QuuxEnum.QUUX1 is virtually guaranteed to be different across peer nodes.

Despite its seeming hokeyness, this approach works reasonably well in practice.

Parameters:
key - String serving as a key for cache lookup
value - Object we're storing in cache

removeAll

public void removeAll()

remove

public void remove(String key)

Removes the object from cache. Actually a wrapper for remove(String,String).

Parameters:
key - key of the object we're removing from cache

remove

public void remove(BigDecimal key)

Removes the object from cache. Actually a wrapper for remove(String,String).

Parameters:
key - key of the object we're removing from cache

remove

public static void remove(String id,
                          BigDecimal key)

Static method which removes object from cache. It is necessary for implementing the coherent caching, since it allows "outsiders" to invalidate (purge) certain objects from cache.

Parameters:
id - Unique identificator of cache storage
key - (BigDecimal) key of the object we're removing from cache

remove

public static void remove(String id,
                          String key)

Static method which removes object from cache. It is necessary for implementing the coherent caching, since it allows "outsiders" to invalidate (purge) certain objects from cache.

Parameters:
id - Unique identificator of cache storage
key - key of the object we're removing from cache

get

public Object get(BigDecimal key)

Retrieves the object stored in cache. If no object by the passed key can be found in cache (maybe because it's expired or it's been explicitly removed), null is returned.

Parameters:
key - key of the object we're retrieving from cache
Returns:
Object stored in cache under key key

get

public Object get(String key)

Retrieves the object stored in cache. If no object by the passed key can be found in cache (maybe because it's expired or it's been explicitly removed), null is returned.

Parameters:
key - key of the object we're retrieving from cache
Returns:
Object stored in cache under key key


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC