wt.admin.cache
Class AdminDomainCache

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

All Implemented Interfaces:

CacheServer, Remote, Serializable, Unreferenced

public final class AdminDomainCache

extends CacheManager

Provides methods to access cached domains, domain names, and domain paths.

It is important to remember to perform any necessary access checks on objects retrieved from this cache as none of the methods in this class do so. It is also important to call isStale before invoking any methods of this class. If the cache is stale then any objects returned from the cache may be invalid until the current transaction completes.

AdminDomainCache is a subclass of CacheManager in order to communicate updates to cached data between multiple method servers. It does not store its cached data in the CacheManager cache.

Supported API: false

Extendable: false

See Also:

Serialized Form

Nested Class Summary

private static class	AdminDomainCache.CacheUpdaterContainer Helper class for calling the methods of CacheUpdater on all the contained instances of CacheUpdater.
static class	AdminDomainCache.Server Defines the remote method that is invoked by main in order to report the current contents of this cache.

Field Summary

private AdminDomainCache.CacheUpdaterContainer	caches
private static AdminDomainCache	domainCache
(package private) DomainHierarchy	domainHierarchy
private static Object	IS_STALE Constant used as the key into the MethodContext where a boolean flag is set that indicates that the AdminDomainCache contains stale data for the duration of the current transaction.
private static Object	lock

Fields inherited from class wt.cache.CacheManager

MASTER

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

AdminDomainCache()
Do not directly invoke this constructor! Use getAdminDomainCache instead.

Method Summary

private void	clearStaleFlag() Clears a boolean flag in the MethodContext that indicates that the AdminDomainCache contains stale data for the current transaction
static AdminDomainCache	getAdminDomainCache() Accessor method to obtain the single instance of the AdminDomainCache
Vector	getAncestorDomains(ObjectIdentifier oid) Gets the ObjectIdentifiers of the ancestor domains for the given domain.
ObjectIdentifier	getChildDomain(ObjectIdentifier parent_oid, String child_name, WTContainerRef child_container_ref) Gets the ObjectIdentifier of a named domain given the ObjectIdentifier of its parent domain.
int	getDefaultSize() Overrides CacheManager.getDefaultSize to return 0 since no objects will be put into the wt.util.Cache object contained in CacheManager
Vector	getDescendentDomains(ObjectIdentifier oid) Gets the ObjectIdentifiers of the descendent domains for the given domain.
AdministrativeDomain	getDomain(ObjectIdentifier oid) Gets the AdministrativeDomain with the given ObjectIdentifier.
AdministrativeDomain	getDomain(String path, WTContainerRef containerRef) Gets the AdministrativeDomain with the given path relative to the given container.
String	getDomainName(ObjectIdentifier domain) Gets the name of the AdministrativeDomain with the given ObjectIdentifier.
ObjectIdentifier	getDomainOID(String path, WTContainerRef containerRef) Gets the ObjectIdentifier of the domain specified by path which resides in the specified container
ObjectIdentifier	getParentDomain(ObjectIdentifier child_oid) Gets the ObjectIdentifier of a parent domain given the ObjectIdentifier of a child domain.
String	getPathOfDomain(AdministrativeDomain domain) Gets the path of the domain.
private void	initialize() Initializes the attributes of this class
boolean	isStale() Indicates if the contents of the AdminDomainCache have been changed at some point during the current transaction.
static void	main(String[] args) Reports the current contents of this cache.
void	putEntry(Object key, Object value) Overrides CacheManager.putEntry to do nothing so that entries are not added to the wt.util.Cache object contained in CacheManager
private void	registerEventListeners() Defines and registers event listeners used to update the AdminDomainCache in response to persistent changes to cached data.
protected void	removeEntry(Object a_msg) Decodes an UpdateMessage and then invokes the correct method on each CacheUpdater, passing in the arguments to the method
void	report(File file) Creates a report that shows the contents of the AdminDomainCache.
void	reset() Reinitializes the AdminDomainCache in the event that communication between CacheManagers was interrupted for some reason in which case UpdateMessages may have been lost, invalidating the cache contents.
private void	setStaleFlag() Sets a boolean flag in the MethodContext that indicates that the AdminDomainCache contains stale data for the current transaction
private static void	signalRemoteCaches(UpdateMessage msg) Signals all other instances of this AdminDomainCache (running in other method servers typically) of an update to the cache

Methods inherited from class wt.cache.CacheManager

checkAccess, get, getDefaultName, getEntry, isCacheHost, overflow, ping, put, putEntry, reference, registerSlave, remove, remove, removeEntry, unreferenced, update, updateEntry, updateEntry

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

caches

private AdminDomainCache.CacheUpdaterContainer caches

domainCache

private static AdminDomainCache domainCache

lock

private static Object lock

IS_STALE

private static final Object IS_STALE

Constant used as the key into the MethodContext where a boolean flag is set that indicates that the AdminDomainCache contains stale data for the duration of the current transaction.

domainHierarchy

DomainHierarchy domainHierarchy

Constructor Detail

AdminDomainCache

public AdminDomainCache()
                 throws RemoteException

Do not directly invoke this constructor! Use getAdminDomainCache instead. The constructor is public so that the ServerManager can create an instance of this class for use as the master cache.

However, since the master cache is only being used to signal slave caches, we don't want to construct the internal cache object (DomainHierarchy) in the master cache as it is a waste of time and memory.

Method Detail

getAdminDomainCache

public static AdminDomainCache getAdminDomainCache()
                                            throws RemoteException,
                                                   WTException

Accessor method to obtain the single instance of the AdminDomainCache

Returns:

the single instance of AdminDomainCache

Throws:

RemoteException - if an error occurs registering this cache with a remote server

WTException - if a low level error occurs

getParentDomain

public ObjectIdentifier getParentDomain(ObjectIdentifier child_oid)
                                 throws WTException

Gets the ObjectIdentifier of a parent domain given the ObjectIdentifier of a child domain.

Parameters:

child_oid - an ObjectIdentifier for a child domain

Returns:

the ObjectIdentifier of the child's parent domain

Throws:

WTException - if a low level error occurs

getChildDomain

public ObjectIdentifier getChildDomain(ObjectIdentifier parent_oid,
                                       String child_name,
                                       WTContainerRef child_container_ref)
                                throws WTException

Gets the ObjectIdentifier of a named domain given the ObjectIdentifier of its parent domain.

Parameters:

parent_oid - the ObjectIdentifier of the parent domain

child_name - the name of the child domain

child_container_ref - the reference for the container the child domain resides in

Returns:

the ObjectIdentifier of the child domain; returns null if the domain does not exist

Throws:

WTException - if a low level error occurs

getAncestorDomains

public Vector getAncestorDomains(ObjectIdentifier oid)
                          throws WTException

Gets the ObjectIdentifiers of the ancestor domains for the given domain.

Parameters:

oid - the ObjectIdentifier of the domain

Returns:

the ObjectIdentifiers of the ancestor domains for the given domain

Throws:

WTException - if a low level error occurs

getDescendentDomains

public Vector getDescendentDomains(ObjectIdentifier oid)
                            throws WTException

Gets the ObjectIdentifiers of the descendent domains for the given domain.

Parameters:

oid - the ObjectIdentifier of the domain

Returns:

the ObjectIdentifiers of the descendent domains for the given domain

Throws:

WTException - if a low level error occurs

getDomainOID

public ObjectIdentifier getDomainOID(String path,
                                     WTContainerRef containerRef)
                              throws WTException

Gets the ObjectIdentifier of the domain specified by path which resides in the specified container

Parameters:

path - the path of the domain

containerRef - reference to the container where domain resides

Returns:

the ObjectIdentifiers of the domain

Throws:

WTException - if a low level error occurs

getPathOfDomain

public String getPathOfDomain(AdministrativeDomain domain)
                       throws WTException

Gets the path of the domain.

Parameters:

domain - AdministrativeDomain object

Returns:

the path of the domain

Throws:

WTException - if a low level error occurs

getDomain

public AdministrativeDomain getDomain(ObjectIdentifier oid)
                               throws WTException

Gets the AdministrativeDomain with the given ObjectIdentifier.

Parameters:

oid - an ObjectIdentifier for a AdministrativeDomain

Returns:

the AdministrativeDomain object, else null if the AdministrativeDomain doesn't exist

Throws:

WTException - if a low level error occurs

getDomain

public AdministrativeDomain getDomain(String path,
                                      WTContainerRef containerRef)
                               throws WTException

Gets the AdministrativeDomain with the given path relative to the given container.

Parameters:

path - a path for an AdministrativeDomain

containerRef - the container reference for the Container the path is relative to.

Returns:

the AdministrativeDomain object, else null if the AdministrativeDomain doesn't exist

Throws:

WTException - if a low level error occurs

getDomainName

public String getDomainName(ObjectIdentifier domain)
                     throws WTException,
                            ObjectNoLongerExistsException

Gets the name of the AdministrativeDomain with the given ObjectIdentifier.

Parameters:

domain - an ObjectIdentifier for a domain

Returns:

the domain's name

Throws:

ObjectNoLongerExistsException - if the requested domain is not found in the database

WTException - if a low level error occurs

putEntry

public void putEntry(Object key,
                     Object value)

Overrides CacheManager.putEntry to do nothing so that entries are not added to the wt.util.Cache object contained in CacheManager

Overrides:

putEntry in class CacheManager

Parameters:

key - the key object

value - the value object

getDefaultSize

public int getDefaultSize()

Overrides CacheManager.getDefaultSize to return 0 since no objects will be put into the wt.util.Cache object contained in CacheManager

Overrides:

getDefaultSize in class CacheManager

Returns:

int 0

reset

public void reset()
           throws RemoteException

Reinitializes the AdminDomainCache in the event that communication between CacheManagers was interrupted for some reason in which case UpdateMessages may have been lost, invalidating the cache contents.

Overrides:

reset in class CacheManager

Throws:

RemoteException

removeEntry

protected void removeEntry(Object a_msg)

Decodes an UpdateMessage and then invokes the correct method on each CacheUpdater, passing in the arguments to the method

Overrides:

removeEntry in class CacheManager

Parameters:

a_msg - an UpdateMessage object

signalRemoteCaches

private static void signalRemoteCaches(UpdateMessage msg)

Signals all other instances of this AdminDomainCache (running in other method servers typically) of an update to the cache

Parameters:

msg - a message object that encodes what method (along with its args) to invoke on a remote cache in order to update it

isStale

public boolean isStale()

Indicates if the contents of the AdminDomainCache have been changed at some point during the current transaction. If a client implements a transaction that changes the persistent state of objects managed by this cache, before accessing objects in the cache it should call this method. If this method returns true then the cache is stale and the client must not use the cached data because it is not guaranteed to be accurate until the current transaction completes.

Returns:

true if this cache has already been updated in the current transaction, otherwise false

registerEventListeners

private void registerEventListeners()

Defines and registers event listeners used to update the AdminDomainCache in response to persistent changes to cached data. Each event listener in turn creates and registers a TransactionListener that does the actual work in the notifyCommit method.

See Also:

TransactionListener

report

public void report(File file)
            throws IOException

Creates a report that shows the contents of the AdminDomainCache. Used for debugging purposes only.

Parameters:

file - the file to save the report to

Throws:

IOException

main

public static void main(String[] args)

Reports the current contents of this cache. Used for debugging purposes only.

setStaleFlag

private void setStaleFlag()

Sets a boolean flag in the MethodContext that indicates that the AdminDomainCache contains stale data for the current transaction

clearStaleFlag

private void clearStaleFlag()

Clears a boolean flag in the MethodContext that indicates that the AdminDomainCache contains stale data for the current transaction

initialize

private void initialize()
                 throws WTException

Initializes the attributes of this class

Throws:

WTException