wt.cache
Class CacheManager

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

All Implemented Interfaces:

CacheServer, Remote, Serializable, Unreferenced

Direct Known Subclasses:

AbstractRuleCache, AbstractTypeDefinitionCacheManager, AclCache, AdHocAclSpecCache, AdminDomainCache, AttributeCache, ClassificationCache, ClassificationDBService.ClassificationStructureCache, ClusterMonitor, ConfigCache, CriterionCache, DirectoryInfrastructureNodeCache, EmptyTableManager, FederatableServerHelper.RepositoryCache, ForumModelUpdater.NmUpdateService, FvPolicyItemCache, IBADefinitionCache, IBADefinitionDBService.DefaultViewbyPathCache, IBAModelImplementation.DefaultIBATypeCache, IndexListCache, InitialPhaseCache, LifeCycleTemplateCache, LifeCycleTemplateNameCache, LogicalIdentifiedCacheMgr, LogicalIdentifierCacheMgr, MasterCacheMonitor, Messenger, MethodInterruptor.InterruptService, NotificationListCache, PagingSessionCache, PhaseTemplateCache, PlanModelUpdater.NmUpdateService, PrefEntryCache, ProjectCache, ProjectModelUpdater.NmUpdateService, QueueCache, RecentUpdateCache, SessionCache, StandardFvService.ActiveFolderCache, StandardFvService.FvFolderCache, StandardFvService.FvMountCache, StandardFvService.HostCache, StandardInterSvrComService.SiteInfoCache, StandardWfEngineService.SynchRobotCache, TeamCache, TeamTemplateCache, UnitCache, ViewCache, WaitService.Cache, WfProcessTemplateCache, WTAuthNameCache, WTCalendarCache, WTDirKeyCache, WTPrincipalCache, WVSCache

public class CacheManager

extends RMIServer

implements 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

private ManagedCache	cache
private int	cacheHits
private static Vector	cacheHosts
private int	cacheSummaryInterval
private static boolean	DISABLED
(package private) int	id Id of this cache - assigned by master.
private boolean	inUnreferenced
private long	lastFailed
(package private) static int	MARSHAL_RETRY
private RemoteCacheServer	master
protected static boolean	MASTER
private static URL	MASTER_CODEBASE
private static String	MASTER_HOSTNAME
(package private) static int	MASTER_MONITOR_INTERVAL
(package private) String	name Name of this cache.
(package private) static int	OTHER_RETRY
private static String	previousCacheHost
private static String	previousLocalHost
private static String	RESOURCE
private static String	RMI_HOST_NAME
private boolean	skippedChanges
(package private) Vector	slaves Vector of registered slave caches.
private static boolean	USE_LOCAL_ADDRESS
private static boolean	USE_LOCAL_NAME
(package private) static boolean	VERBOSE_SERVER

Fields inherited from class wt.util.RMIServer

csf, ssf

Fields inherited from class java.rmi.server.RemoteServer

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface wt.cache.CacheServer

versionID

Constructor Summary

	CacheManager() Construct a cache manager.
private	CacheManager(boolean export)
	CacheManager(String name, int size, RemoteCacheServer master) Contruct a cache manager.

Method Summary

protected void	checkAccess() Method to check access to cache for remote calls.
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.
Object	getEntry(Object key) Remote method for getting a cache entry.
private Object	getSlaveEntry(Object key, int slave_id)
protected boolean	isCacheHost(String host) Method to check if a given host is a valid remote cache host.
private void	notifySlaves(Object key, int skip_id)
private void	notOk(RemoteException e)
private boolean	ok(boolean change)
protected void	overflow(Object key, Object value) Protected method which allows subclasses of CacheManager to take some action if so desired on a cache overflow.
void	ping() Remote method for verifying ccess.
private static void	printRemoteException(RemoteException e)
void	put(Object key, Object value) Put a cache entry with given key.
private void	put(Object key, Object value, int slave_id)
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	putEntry(Object key, Object value, int slave_id) Remote method for putting an entry in the cache.
void	reference(CacheServer self) Remote method for generating RMI DGC lease on self.
int	registerSlave(CacheServer slave) Remote method for registering a slave cache.
void	remove(Object key) Remove an entry from the cache.
protected void	remove(Object key, int slave_id) Deprecated. use 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.
void	removeEntry(Object key, int slave_id) Remote method for removing an entry from the cache.
void	reset() Reset local cache after master reconnect.
void	unreferenced() Called when we are no longer referenced remotely by master or slave caches.
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.
private void	update(Object cache_key, Object update_key, Object update_value, int slave_id)
protected Object	updateEntry(Object current_value, Object update_key, Object update_value) Perform a partial update to a large cached object.
void	updateEntry(Object cache_key, Object update_key, Object update_value, int slave_id) Remote method for updating an existing cache entry.

Methods inherited from class wt.util.RMIServer

clone, exportObject, exportObject, exportObject, getClientSocketFactory, getPort, getServerSocketFactory, getStub, isHostInList, isLocalHost, setPort, writeReplace

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

Field Detail

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

MASTER_CODEBASE

private static final URL MASTER_CODEBASE

MASTER_HOSTNAME

private static final String MASTER_HOSTNAME

MARSHAL_RETRY

static final int MARSHAL_RETRY

OTHER_RETRY

static final int OTHER_RETRY

VERBOSE_SERVER

static final boolean VERBOSE_SERVER

USE_LOCAL_ADDRESS

private static final boolean USE_LOCAL_ADDRESS

USE_LOCAL_NAME

private static final boolean USE_LOCAL_NAME

RMI_HOST_NAME

private static final String RMI_HOST_NAME

MASTER_MONITOR_INTERVAL

static final int MASTER_MONITOR_INTERVAL

DISABLED

private static final boolean DISABLED

MASTER

protected static final boolean MASTER

name

String name

Name of this cache. Package access for SlaveCache class.

id

int id

Id of this cache - assigned by master. Package access for RemoteCacheManager class.

cache

private ManagedCache cache

master

private RemoteCacheServer master

slaves

Vector slaves

Vector of registered slave caches. Package access for SlaveCache class.

inUnreferenced

private boolean inUnreferenced

lastFailed

private long lastFailed

skippedChanges

private boolean skippedChanges

cacheSummaryInterval

private int cacheSummaryInterval

cacheHits

private int cacheHits

previousCacheHost

private static String previousCacheHost

previousLocalHost

private static String previousLocalHost

cacheHosts

private static Vector cacheHosts

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

CacheManager

public CacheManager(String name,
                    int size,
                    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)

CacheManager

private CacheManager(boolean export)
              throws RemoteException

Method Detail

ok

private boolean ok(boolean change)
            throws RemoteException

Throws:

RemoteException

notOk

private void notOk(RemoteException e)

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

put

private void put(Object key,
                 Object value,
                 int slave_id)

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

update

private void update(Object cache_key,
                    Object update_key,
                    Object update_value,
                    int slave_id)

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:

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)

remove

protected void remove(Object key,
                      int slave_id)

Deprecated. use removeEntry

Should be private. Was protected prior to 3.0 release

Supported API: false

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)

registerSlave

public int registerSlave(CacheServer slave)
                  throws RemoteException

Remote method for registering a slave cache.

Supported API: false

Specified by:

registerSlave in interface CacheServer

Throws:

RemoteException

getEntry

public Object getEntry(Object key)

Remote method for getting a cache entry.

Supported API: false

Specified by:

getEntry in interface CacheServer

putEntry

public void putEntry(Object key,
                     Object value,
                     int slave_id)

Remote method for putting an entry in the cache.

Supported API: false

Specified by:

putEntry in interface CacheServer

updateEntry

public void updateEntry(Object cache_key,
                        Object update_key,
                        Object update_value,
                        int slave_id)

Remote method for updating an existing cache entry.

Supported API: false

Specified by:

updateEntry in interface CacheServer

removeEntry

public void removeEntry(Object key,
                        int slave_id)

Remote method for removing an entry from the cache.

Supported API: false

Specified by:

removeEntry in interface CacheServer

ping

public void ping()

Remote method for verifying ccess.

Supported API: false

Specified by:

ping in interface CacheServer

reference

public void reference(CacheServer self)
               throws RemoteException

Remote method for generating RMI DGC lease on self.

Supported API: false

Specified by:

reference in interface CacheServer

Throws:

RemoteException

checkAccess

protected void checkAccess()

Method to check access to cache for remote calls. This implementation assumes this thread is in an active RMI call and allows access from clients that are running on the local (server) host or hosts that are expected to have remote caches.

Supported API: false

Throws:

SecurityException - if check fails and/or access is denied

isCacheHost

protected boolean isCacheHost(String host)
                       throws IOException

Method to check if a given host is a valid remote cache host. Valid cache hosts are the remote master host identified via the wt.cache.master.codebase property or remote slave hosts identified in the wt.cache.master.slaveHosts property.

Supported API: false

Throws:

IOException

unreferenced

public void unreferenced()

Called when we are no longer referenced remotely by master or slave caches.

Supported API: false

Specified by:

unreferenced in interface Unreferenced

overflow

protected void overflow(Object key,
                        Object value)

Protected method which allows subclasses of CacheManager to take some action if so desired on a cache overflow.

notifySlaves

private void notifySlaves(Object key,
                          int skip_id)

getSlaveEntry

private Object getSlaveEntry(Object key,
                             int slave_id)

printRemoteException

private static void printRemoteException(RemoteException e)