ABLE 2.0.0 07/02/2003 10:25:01

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

Fields inherited from interface com.ibm.able.platform.VerifiableAgentDirectoryService
DIRECTORY_SERVICE_COLUMN_NAMES, DIRECTORY_SERVICE_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.
static java.lang.String Copyright()
          Determine the copyright of this class.
 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.
 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
Following copied from interface: com.ibm.able.platform.VerifiableAgentDirectoryService
Parameters:
theAgentDescription - 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
Following copied from interface: com.ibm.able.platform.VerifiableAgentDirectoryService
Parameters:
theAgentDescription - The agent description to be deregistered.

key - The AbleSecureKey used to secure the communication.

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

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.


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
Following copied from interface: com.ibm.able.platform.VerifiableAgentDirectoryService
Parameters:
theAgentDescription - The agent description to be modified.

key - The AbleSecureKey used to secure the communication.

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

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.


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

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

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

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

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

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
Following copied from interface: com.ibm.able.platform.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:
AbleException - On any remote error or Able error.
javax.agent.service.naming.NamingException - On any naming 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
Following copied from interface: com.ibm.able.platform.AblePlatformServiceEventGenerator
Parameters:
theListener - Any object interested in listening for service events generated by this service.

Throws:
AbleException - 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
Following copied from interface: com.ibm.able.platform.AblePlatformServiceEventGenerator
Parameters:
theListener - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:
AbleException - 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
Following copied from interface: com.ibm.able.platform.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.

Overrides:
toString in class java.lang.Object
Returns:
A String containing the current contents of the object.

Copyright

public static java.lang.String Copyright()
Determine the copyright of this class.

Returns:
A String containing this class's copyright statement.

ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003