com.ibm.able.platform
Class RMIVerifiableDirectoryProxy

java.lang.Object
  com.ibm.able.platform.RMIVerifiableDirectoryProxy

All Implemented Interfaces:

AblePlatformService, AblePlatformServiceEventGenerator, javax.agent.service.directory.AgentDirectoryService, java.io.Serializable, javax.agent.service.Service, VerifiableAgentDirectoryService

public class RMIVerifiableDirectoryProxy

extends java.lang.Object

implements VerifiableAgentDirectoryService, java.io.Serializable

An RMIVerifiableDirectoryProxy contains a reference to an RMI version of a VerifiableDirectoryService. The proxy contains methods identical to the methods in the actual service.

When a method is called on the proxy, the proxy forwards the call on to the actual service. However, the proxy: (1) traps all RemoteExceptions that might be thrown by the service (2) turns the RemoteExceptions into DirectoryFailure Exceptions and then (3) rethrows the new exception. In this way, code making use of the proxy does not have to be sensitive to RMI RemoteExceptions and can code to the common VerifiableAgentDirectoryService interface.

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.ibm.able.platform.VerifiableAgentDirectoryService

COLUMN_NAMES, COLUMN_TYPES, PUBLIC_KEY, SERVICE_PATH, SERVICE_TYPE

Constructor Summary

RMIVerifiableDirectoryProxy(RMIVerifiableDirectoryService theDelegate, java.rmi.registry.Registry theRegistry, java.lang.String theAddress)
Create a proxy over the specified RMI reference to a Verifiable Directory Service.

Method Summary

void	addAblePlatformServiceEventListener(AblePlatformServiceEventListener observer) Adds a service event listener to this service.
javax.agent.service.directory.AgentDescription	createAgentDescription()
void	deregister(javax.agent.service.directory.AgentDescription desc)
void	deregister(javax.agent.service.directory.AgentDescription desc, AbleSecureKey key) Deregister theAgentDescription from the VerifiableAgentDirectoryService.
java.util.Vector	getAblePlatformServiceEventListeners() Gets a collection of all service event listeners registered with this service event generator.
javax.agent.service.ServiceProperties	getServiceProperties() Retrieve the service properties of the underlying service.
int	getState() Returns the state of this service.
void	modify(javax.agent.service.directory.AgentDescription desc)
void	modify(javax.agent.service.directory.AgentDescription desc, AbleSecureKey key) Modify theAgentDescription in the VerifiableAgentDirectoryService.
void	register(javax.agent.service.directory.AgentDescription desc)
void	register(javax.agent.service.directory.AgentDescription desc, AbleSecureKey key) Register theAgentDescription to the VerifiableAgentDirectoryService.
void	removeAblePlatformServiceEventListener(AblePlatformServiceEventListener observer) Removes a service event listener from this service.
javax.agent.service.directory.AgentDescription[]	search(javax.agent.service.directory.AgentDescription desc)
javax.agent.service.directory.AgentDescription[]	search(javax.agent.service.directory.AgentDescription desc, int maxResults)
void	setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties) Set the service properties of the underlying service.
void	terminateService(AbleSecureKey theSecureKey) Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.
java.lang.String	toString() Retrieve a string describing (the contents of) the object.

Methods inherited from class java.lang.Object

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

Constructor Detail

RMIVerifiableDirectoryProxy

public RMIVerifiableDirectoryProxy(RMIVerifiableDirectoryService theDelegate,
                                   java.rmi.registry.Registry theRegistry,
                                   java.lang.String theAddress)

Create a proxy over the specified RMI reference to a Verifiable Directory Service.

Parameters:

theDelegate - A reference to an RMI version of a Verifiable Directory Service.

theRegistry - The RMI registry at which the above Verifiable Directory Service is registered.

theAddress - The RMI address at which the above Verifiable Directory Service is registered.

Method Detail

register

public void register(javax.agent.service.directory.AgentDescription desc,
                     AbleSecureKey key)
              throws javax.agent.service.directory.AlreadyRegisteredException,
                     javax.agent.service.directory.DirectoryFailure

Description copied from interface: VerifiableAgentDirectoryService

Register theAgentDescription to the VerifiableAgentDirectoryService.

This method should only be called when the RMIVerifiableDirectorySystem is running in a secure platform.

An agent is only allowed to register its own agent description.

If successfully registered, all registered listeners will be notified of this newly registered agent description.

Specified by:

register in interface VerifiableAgentDirectoryService

Parameters:

desc - The agent description to be registered.

key - The AbleSecureKey used to secure the communication.

Throws:

javax.agent.service.directory.AlreadyRegisteredException - If theAgentDescription is already registered.

javax.agent.service.directory.DirectoryFailure -

If the platform is not running secure.

If the agent description that is to be registered does not belong to the agent trying to register it.

deregister

public void deregister(javax.agent.service.directory.AgentDescription desc,
                       AbleSecureKey key)
                throws javax.agent.service.directory.NotRegisteredException,
                       javax.agent.service.directory.DirectoryFailure

Description copied from interface: VerifiableAgentDirectoryService

Deregister theAgentDescription from the VerifiableAgentDirectoryService.

This method should only be called when the RMIVerifiableDirectorySystem is running in a secure platform.

An agent is only allowed to deregister its own agent description.

If successfully deregistered, all registered listeners will be notified of this deregistered agent description.

Specified by:

deregister in interface VerifiableAgentDirectoryService

Parameters:

desc - The agent description to be deregistered.

key - The AbleSecureKey used to secure the communication.

Throws:

javax.agent.service.directory.DirectoryFailure -

If the platform is not running secure.

If the agent description that is to be deregistered does not belong to the agent trying to deregister it.

javax.agent.service.directory.NotRegisteredException - If theAgentDescription is not currently registered.

modify

public void modify(javax.agent.service.directory.AgentDescription desc,
                   AbleSecureKey key)
            throws javax.agent.service.directory.NotRegisteredException,
                   javax.agent.service.directory.DirectoryFailure

Description copied from interface: VerifiableAgentDirectoryService

Modify theAgentDescription in the VerifiableAgentDirectoryService.

This method should only be called when the RMIVerifiableDirectorySystem is running in a secure platform.

An agent is only allowed to modify its own agent description.

If successfully modified, all registered listeners will be notified of this changed agent description.

Specified by:

modify in interface VerifiableAgentDirectoryService

Parameters:

desc - The agent description to be modified.

key - The AbleSecureKey used to secure the communication.

Throws:

javax.agent.service.directory.DirectoryFailure -

If the platform is not running secure.

If the agent description that is to be modified does not belong to the agent trying to modify it.

javax.agent.service.directory.NotRegisteredException - If theAgentDescription is not currently registered.

register

public void register(javax.agent.service.directory.AgentDescription desc)
              throws javax.agent.service.directory.AlreadyRegisteredException,
                     javax.agent.service.directory.DirectoryFailure

Specified by:

register in interface javax.agent.service.directory.AgentDirectoryService

Throws:

javax.agent.service.directory.AlreadyRegisteredException

javax.agent.service.directory.DirectoryFailure

deregister

public void deregister(javax.agent.service.directory.AgentDescription desc)
                throws javax.agent.service.directory.NotRegisteredException,
                       javax.agent.service.directory.DirectoryFailure

Specified by:

deregister in interface javax.agent.service.directory.AgentDirectoryService

Throws:

javax.agent.service.directory.NotRegisteredException

javax.agent.service.directory.DirectoryFailure

modify

public void modify(javax.agent.service.directory.AgentDescription desc)
            throws javax.agent.service.directory.NotRegisteredException,
                   javax.agent.service.directory.DirectoryFailure

Specified by:

modify in interface javax.agent.service.directory.AgentDirectoryService

Throws:

javax.agent.service.directory.NotRegisteredException

javax.agent.service.directory.DirectoryFailure

search

public javax.agent.service.directory.AgentDescription[] search(javax.agent.service.directory.AgentDescription desc)
                                                        throws javax.agent.service.directory.SearchException,
                                                               javax.agent.service.directory.DirectoryFailure

Specified by:

search in interface javax.agent.service.directory.AgentDirectoryService

Throws:

javax.agent.service.directory.SearchException

javax.agent.service.directory.DirectoryFailure

search

public javax.agent.service.directory.AgentDescription[] search(javax.agent.service.directory.AgentDescription desc,
                                                               int maxResults)
                                                        throws javax.agent.service.directory.SearchException,
                                                               javax.agent.service.directory.DirectoryFailure

Specified by:

search in interface javax.agent.service.directory.AgentDirectoryService

Throws:

javax.agent.service.directory.SearchException

javax.agent.service.directory.DirectoryFailure

createAgentDescription

public javax.agent.service.directory.AgentDescription createAgentDescription()

Specified by:

createAgentDescription in interface javax.agent.service.directory.AgentDirectoryService

terminateService

public void terminateService(AbleSecureKey theSecureKey)
                      throws AbleException,
                             javax.agent.service.naming.NamingException

Description copied from interface: AblePlatformService

Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.

Specified by:

terminateService in interface AblePlatformService

Parameters:

theSecureKey - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.

Throws:

javax.agent.service.naming.NamingException - On any naming error.

AbleException - On any remote error or Able error.

getState

public int getState()
             throws AbleException

Description copied from interface: AblePlatformService

Returns the state of this service.

Specified by:

getState in interface AblePlatformService

Returns:

The state of this service.

Throws:

AbleException - On any remote error or Able error.

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener observer)
                                         throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Adds a service event listener to this service.

Specified by:

addAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

observer - Any object interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be added is null, or on any error.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener observer)
                                            throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Removes a service event listener from this service.

Specified by:

removeAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

observer - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be removed is null, or on any error.

getAblePlatformServiceEventListeners

public java.util.Vector getAblePlatformServiceEventListeners()
                                                      throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Gets a collection of all service event listeners registered with this service event generator.

Specified by:

getAblePlatformServiceEventListeners in interface AblePlatformServiceEventGenerator

Returns:

All registered AblePlatformServiceEventListener objects.

Throws:

AbleException - On any error.

getServiceProperties

public javax.agent.service.ServiceProperties getServiceProperties()

Retrieve the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; null is always returned.

Specified by:

getServiceProperties in interface javax.agent.service.Service

Returns:

null at all times.

setServiceProperties

public void setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties)

Set the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; the call is simply ignored.

Specified by:

setServiceProperties in interface javax.agent.service.Service

Parameters:

theServiceProperties - The service properties to be used by the service.

toString

public java.lang.String toString()

Retrieve a string describing (the contents of) the object.

Returns:

A String containing the current contents of the object.