wt.cache
Class CacheManager

java.lang.Object
  java.rmi.server.RemoteObject
      java.rmi.server.RemoteServer
          wt.util.RMIServer
              wt.cache.CacheManager

All Implemented Interfaces:

Serializable, Remote, Unreferenced, wt.cache.CacheServer

public class CacheManager
extends wt.util.RMIServer
implements wt.cache.CacheServer, Unreferenced

A multi-level cache manager service. This is an abstract parent class for specialized object caches. A cache is a fixed size collection of most recently used objects identified by a unique identifier.

This class manages the maintenance and synchronization of multi-level caches where multiple cache objects (usually in separate VMs) have a master/slave relationship. Updates to a cache are pushed synchronously to the master cache which asynchronously notifies other slave caches that an entry has been updated.

To be effective, updates to cached objects must notify the cache so that master/slave caches may receive corresponding updates. It is the responsibility of the application to make this happen.

When a new entry is put into the cache, the entire object is sent to the master cache. When an update call is made, the master is sent only the update. If the master has aged out it's cache entry, it will attempt to retrieve the full object from the slave.

The follow example is a simple cache of a objects used similarly to how a static Hashtable of object references would be used.

 public class FooManager
 {
    // Foo cache
    private static FooCache fooCache = null;

    // Get/create Foo cache (unsynchronized)
    private static FooCache getFooCache ()
    {
       if (fooCache == null)
           createFooCache();
       return fooCache;
    }

    // Create Foo cache (synchronized)
    private static synchronized void createFooCache ()
    {
       if (fooCache == null)
       {
          try
          {
             fooCache = new FooCache();
          }
          catch (RemoteException e)
          {
             // Fatal - throw as method server exception
             throw new MethodServerException("Unable to create foo cache", e);
          }
       }
    }

    public Foo getFoo (Object foo_key)
    {
       FooCache foo_cache = getFooCache();
       Foo foo = (Foo)foo_cache.get(foo_key);
       if (foo == null)
       {
          // Get or create foo object
          foo = ...

          // Add to foo cache
          foo_cache.put(foo_key, foo);
       }
       return foo;
    }

    public void updateFoo (Foo foo, ...)
    {
       // Do update
       Foo new_foo = ...

       // Update foo cache (required even if new_foo is current cache entry)
       Object foo_key = ...
       getFooCache().put(foo_key, new_foo);
    }
 }

 public class FooCache extends CacheManager
 {
    public FooCache ()
       throws RemoteException
    {
       super();
    }
 }
 

Supported API: true
Extendable: true

See Also:

Serialized Form

Field Summary

Fields inherited from class java.rmi.server.RemoteObject

ref

Constructor Summary

CacheManager()
Construct a cache manager.

CacheManager(String name, int size, wt.cache.RemoteCacheServer master)
Contruct a cache manager.

Method Summary

Object	get(Object key) Get cache entry with given key.
String	getDefaultName() Get desired name of this cache.
int	getDefaultSize() Get desired size of this cache.
void	put(Object key, Object value) Put a cache entry with given key.
protected void	putEntry(Object key, Object value) Protected method which allows subclasses of CacheManager to take some action when a new entry is being put into the local cache.
void	remove(Object key) Remove an entry from the cache.
protected void	removeEntry(Object key) Protected method which allows subclasses of CacheManager to take some action when a entry is being removed from the local cache.
void	reset() Reset local cache after master reconnect.
void	update(Object cache_key, Object update_key, Object update_value) Notify master and slave caches of a partial update to a large cache entry.
protected Object	updateEntry(Object current_value, Object update_key, Object update_value) Perform a partial update to a large cached object.

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CacheManager

public CacheManager()
             throws RemoteException

Construct a cache manager. The cache name is obtained by calling the getDefaultName method. The cache size if obtained by calling the getDefaultSize method.

The master cache is assumed to be in the default (local) server manager using the fully qualified class name as a service name. If the wt.cache.master.codebase property is set, this local master cache will itself be subordinate to a cache on the identified system. On the master host, the wt.cache.master.codebase should not be set, or if set, it should be identical to the wt.server.codebase property. If a non-master and master share an identical wt.server.codebase URLs, a second property, wt.cache.master.hostname, can be used to uniquely identify the master host.

Supported API: true

Throws:

RemoteException

CacheManager

public CacheManager(String name,
                    int size,
                    wt.cache.RemoteCacheServer master)
             throws RemoteException

Contruct a cache manager. This constructor is available for subclasses that don't rely on the default no-arg constructor.

Supported API: true

Parameters:

name - cache name used in debug tracing

size - maximum number of entries in the cache

master - RemoteCacheServer used to call master cache (null = no master)

Throws:

RemoteException

Method Detail

getDefaultName

public String getDefaultName()

Get desired name of this cache. This method returns the last element of the fully qualified class name. Subclasses can override this method to control cache name in some other way.

Supported API: true

getDefaultSize

public int getDefaultSize()

Get desired size of this cache. This method attemps to find a size property called wt.cache.size.CacheName where cacheName is the name of this cache. Subclasses can override this method to control cache size in some other way. If no property is found, the default size is 100.

Supported API: true

reset

public void reset()
           throws RemoteException

Reset local cache after master reconnect. Called after recovery from communication failure when a connection to a new master has been established. The current cache contents are cleared and the local cache is registered as a slave of the new master.

NOTE: This may be called as a result of calling other cache updating operations since that is when the disconnect and reconnect may take place. When this happens, this method is called before the other methods return.

Supported API: true

Throws:

RemoteException

get

public Object get(Object key)

Get cache entry with given key. If not in local cache, the master cache is checked.

Supported API: true

Parameters:

key - the key object

Returns:

the corresponding cached object or null if not in cache

put

public void put(Object key,
                Object value)

Put a cache entry with given key. The entry will also be put in the master cache, and any slave caches will have their corresponding entry removed.

Supported API: true

Parameters:

key - the key object

value - the value object

putEntry

protected void putEntry(Object key,
                        Object value)

Protected method which allows subclasses of CacheManager to take some action when a new entry is being put into the local cache. This method is invoked to put the entry in the local cache as a result of a local put call or a call forwarded from a slave cache or when a local get call downloads the entry from a master cache. If this cache has a master cache, the put call will already be forwarded to the master before this method is invoked. Slave caches will be notified to remove their entries after this method returns. This method must not cause a recursive put call.

Supported API: true

Parameters:

key - the key object

value - the value object

update

public void update(Object cache_key,
                   Object update_key,
                   Object update_value)

Notify master and slave caches of a partial update to a large cache entry. The existing master cache object will be updated with a call to updateEntry. Any slave caches will have their corresponding entry removed. Subclasses should override updateEntry to implement partial updates for large objects.

The caller is expected to have already updated the local cache entry before this method is called.

Supported API: true

Parameters:

cache_key - the key for the cache entry

update_key - the key for what is being updated in the entry

update_value - the updated value

updateEntry

protected Object updateEntry(Object current_value,
                             Object update_key,
                             Object update_value)

Perform a partial update to a large cached object. Subclasses should override. This implementation assumes update_value is the new cache value. This method is called after a update method is performed in a slave cache. It must not cause a recursive update call.

Supported API: true

Parameters:

cache_key - the key for the cache entry

update_key - the key for what is being updated in the entry

update_value - the updated value

remove

public void remove(Object key)

Remove an entry from the cache. The entry is also removed from the master cache and any slave caches. This is similar to put.(key, null) but it does not result in a null entry taking up space in the cache.

Supported API: true

Parameters:

key - the key object (null = clear entire cache)

removeEntry

protected void removeEntry(Object key)

Protected method which allows subclasses of CacheManager to take some action when a entry is being removed from the local cache. This method is invoked to remove the entry in the local cache as a result of a local remove call or a call forwarded from a master cache. If this cache has a master cache, the remove call will already be forwarded to the master before this method is invoked. Slave caches will be notified to remove their entries after this method returns. This method must not cause a recursive remove call.

This method is not called when entries are being removed by the overflow or reset methods.

Supported API: true

Parameters:

key - the key object (null = clear entire cache)