com.knowgate.cache
Class DistributedCachePeer

java.lang.Object
  com.knowgate.cache.DistributedCachePeer

public final class DistributedCachePeer

extends java.lang.Object

Distributed Cache Local Peer

Each distributed cache peer holds its own local copy of cached data.

On the simplest scenenario there is only one client cache peer witch stores data localy for faster access and reduce network bandwitch consumption.

As data is kept localy at each peer, when more than one client peer concurrently access the same data, a cache coordinator becomes necessary.

The cache coordinator is an EJB that must be installed at an application server such as JBoss or BEA Weblogic. See cache.DistributedCacheCoordinatorBean for more information about the cache coordinator.

Distributed Cache Tokens and Policies

A cache peer is essentially a named set of objects. Each object name is called a "cache token". Cache Token associate a String (the object name) with the actual cached object.

Token have an usage count and a last usage date, each time a token is requested its usage count and last usage dates are updated at the cache peer.

The cache peer the applies a customizable Policy for discarding objects as cache becomes full.

Currently only a Least Recently Used Cache Policy is provided.

By default the cache has a maximum of 400 objects slots.

There is no checking of memory consumption for the cache peer, it is the programmer's responsability not to cache objects that are too large.

It is also the programmer's task to remove tokens from the cache peer when the cached data has been changed.

Comunnication between client cache peers and the cache coordinator

The cache coordinator is a single object instance that coordinates data cached by multiple cache peers, at a given time a cache peer may change data that is already cache at another peer. When doing so the last usage date for the token of cached data will be updated and the cache coordinator will be notified of this last usage change.

Each cache peer holds its own copy of data, and the cache coordinator keeps a record of all last usage timestamp for every object at every cache peer. In this way, cached data is not be shared among peers, but it is kept synchronized by discarding all tokens witch timestamp at the peer is older than the one at the cache coordinator.

UML

Version:

1.1

Constructor Summary

DistributedCachePeer()
Create a local cache peer.

Method Summary

void	expire(java.lang.String sTokenKey) Removes an Object from the cache and notify other cache peers that the objects with the given token should no longer be considered valid.
void	expireAll() Remove all objects from local cache and expire then and cache coordinator.
java.lang.Object	get(java.lang.String sTokenKey) Get an object from the cache peer.
java.lang.Boolean	getBoolean(java.lang.String sTokenKey)
DBSubset	getDBSubset(java.lang.String sTokenKey)
java.lang.String	getString(java.lang.String sTokenKey)
java.util.Set	keySet() Return keys for entries in cache
void	put(java.lang.String sTokenKey, java.lang.Object oObj) Puts an Object into local cache.
void	putDBSubset(java.lang.String sTableName, java.lang.String sTokenKey, DBSubset oDBSS) Puts a DBSubset into local cache.
int	size() Number of entries in cache

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DistributedCachePeer

public DistributedCachePeer()
                     throws java.lang.InstantiationException,
                            java.rmi.RemoteException

Create a local cache peer.

The cache peer may be initialized to work in single-peer mode or in multi-peer mode with a cache coordinator.

Initializacion properties for connecting with the cache coordinator when working in multi-peer mode are passed in appserver.cnf properties file. The appserver.cnf file is read using the singleton Environment object at com.knowgate.misc package.

An example of a configuration file for JBoss may be as follows:

#DistributedCachePeer JBoss configuration file

#set this entry to "disabled" is working in single-peer mode
threetiers=enabled

java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.provider.url=jnp://127.1.0.0:1099/
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
jnp.socketFactory=org.jnp.interfaces.TimedSocketFactory

An example of a configuration file for Tomcat may be as follows:

#DistributedCachePeer Tomcat configuration file

#set this entry to "disabled" is working in single-peer mode
threetiers=enabled

java.naming.factory.initial=
java.naming.provider.url=http://www.remotehost.com:1099/cache/server.jsp
java.naming.factory.url.pkgs=
jnp.socketFactory=

Throws:

java.lang.InstantiationException

java.rmi.RemoteException

See Also:

Environment

Method Detail

get

public java.lang.Object get(java.lang.String sTokenKey)
                     throws java.rmi.RemoteException,
                            java.lang.NullPointerException

Get an object from the cache peer.

Parameters:

sTokenKey - Token of object to be retrieved

Returns:

Reference to the requested object or null if object is not present at the local cache or it was modified by another cache peer.

Throws:

java.rmi.RemoteException

java.lang.NullPointerException

getDBSubset

public DBSubset getDBSubset(java.lang.String sTokenKey)
                     throws java.rmi.RemoteException,
                            java.lang.ClassCastException

Returns:

Same as DistributedCachePeer.get() but cast returned object to a DBSubset.

Throws:

java.lang.ClassCastException

java.rmi.RemoteException

getString

public java.lang.String getString(java.lang.String sTokenKey)
                           throws java.rmi.RemoteException,
                                  java.lang.ClassCastException

Parameters:

sTokenKey - Token of object to be retrieved

Returns:

Same as DistributedCachePeer.get() but cast returned object to a String.

Throws:

java.lang.ClassCastException

java.rmi.RemoteException

getBoolean

public java.lang.Boolean getBoolean(java.lang.String sTokenKey)
                             throws java.rmi.RemoteException,
                                    java.lang.ClassCastException

Parameters:

sTokenKey - Token of object to be retrieved

Throws:

java.lang.ClassCastException

java.rmi.RemoteException

keySet

public java.util.Set keySet()

Return keys for entries in cache

Returns:

Set of keys (Strings)

put

public void put(java.lang.String sTokenKey,
                java.lang.Object oObj)
         throws java.lang.IllegalStateException,
                java.lang.IllegalArgumentException,
                java.rmi.RemoteException

Puts an Object into local cache.

Parameters:

sTokenKey - Token for object

oObj - Object to be stored.

Throws:

java.rmi.RemoteException

java.lang.IllegalArgumentException - If either sTokenKey or oObj is null.

java.lang.IllegalStateException - If object with given token is already present at local cache.

putDBSubset

public void putDBSubset(java.lang.String sTableName,
                        java.lang.String sTokenKey,
                        DBSubset oDBSS)
                 throws java.rmi.RemoteException

Puts a DBSubset into local cache.

Parameters:

sTokenKey - Token for object

Throws:

java.rmi.RemoteException

java.lang.IllegalArgumentException - If either sTokenKey or oObj is null.

java.lang.IllegalStateException - If object with given token is already present at local cache.

expire

public void expire(java.lang.String sTokenKey)
            throws java.lang.IllegalArgumentException,
                   java.rmi.RemoteException

Removes an Object from the cache and notify other cache peers that the objects with the given token should no longer be considered valid.

If Object with given token was not present at cache no error is raised.

Parameters:

sTokenKey - Token of object to be removed from local cache.

Throws:

java.rmi.RemoteException

java.lang.IllegalArgumentException - If sTkeney is null.

java.lang.IllegalStateException - If local cache is empty.

expireAll

public void expireAll()
               throws java.rmi.RemoteException

Remove all objects from local cache and expire then and cache coordinator.

Throws:

java.rmi.RemoteException

size

public int size()

Number of entries in cache