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

## 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

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.Float` | `getFloat(java.lang.String sTokenKey)`
`java.lang.Integer` | `getInteger(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 string value 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 boolean value to be retrieved
  Returns:
    Boolean or null if no value was found cached with given token
  Throws:
    `java.lang.ClassCastException`
    `java.rmi.RemoteException`

### getFloat

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

  Parameters:
    `sTokenKey` - Token of float value to be retrieved
  Returns:
    Float or null if no value was found cached with given token
  Throws:
    `java.lang.ClassCastException`
    `java.rmi.RemoteException`
  Since:
    4.0

### getInteger

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

  Parameters:
    `sTokenKey` - Token of integer value to be retrieved
  Returns:
    Integer or null if no value was found cached with given token
  Throws:
    `java.lang.ClassCastException`
    `java.rmi.RemoteException`
  Since:
    5.0

### 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
    `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.

### 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

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