com.ibm.able.platform
Class RMIVerifiableDirectorySystem

java.lang.Object
  java.rmi.server.RemoteObject
      org.jagent.service.util.RMIBasicService
          com.ibm.able.platform.AbleBasicService
              com.ibm.able.platform.RMIVerifiableDirectorySystem

All Implemented Interfaces:

AblePersistenceSupportProcessor, org.jagent.service.IPService, java.rmi.Remote, RmiAblePlatformService, RmiAblePlatformServiceEventGenerator, org.jagent.service.RMIService, RMIVerifiableDirectoryService, java.io.Serializable, javax.agent.service.Service

public final class RMIVerifiableDirectorySystem

extends AbleBasicService

implements RMIVerifiableDirectoryService, AblePersistenceSupportProcessor

A verifiable adapter for AgentDirectoryService. The RMIVerifiableDirectorySystem is a remote object that implements the RMIVerifiableDirectoryService interface. This will be used by the platform to register/update/deregister agent description. It will also be used to search for agent descriptions.

This class also extends RmiAblePlatformService, so it will notify all registered listeners about changes to the AgentDescriptions inside this AgentDirectoryService

See Also:

Serialized Form

Field Summary

Fields inherited from class com.ibm.able.platform.AbleBasicService

ANS_PRINCIPAL, LOCAL_PRINCIPAL, myAnsPrincipal, myKeyPair, myMsgLog, myPrincipal, mySecSppt, myServiceEventListeners, myServiceProperties, myTrcLog, myTrustLevel, myVerifiableAgentName, myVerifiableNamingService, Refreshing, REQUESTORS_PORT, Running, SOCKET_FACTORY, Terminated, Unknown

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface org.jagent.service.RMIService

RMI, SERVICE_PROTOCOL

Fields inherited from interface org.jagent.service.IPService

SERVICE_HOST, SERVICE_PORT

Constructor Summary

RMIVerifiableDirectorySystem()
Creates a new RMI-based Verifiable Directory Service.

RMIVerifiableDirectorySystem(javax.agent.service.ServiceProperties env)
Creates a new RMI-based Verifiable Directory Service with the given ServiceProperties.

Method Summary

void	addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Since this Verifiable Directory Service will be persisting listeners, AbleBasicService's addAblePlatformServiceEventListener method must be overridden to handle the adding of this service's listeners from persistence.
javax.agent.service.directory.AgentDescription	createAgentDescription() The original createAgentDescription method off of the AgentDirectoryService is still being exposed.
void	deregister(javax.agent.service.directory.AgentDescription theAgentDescription) The original deregister method off of the AgentDirectoryService is still being exposed.
void	deregister(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey key) Deregister theAgentDescription from the VerifiableAgentDirectoryService.
java.lang.String	getBindingName() Abstract method from org.jagent.service.util.RMIBasicService.
void	modify(javax.agent.service.directory.AgentDescription theAgentDescription) The original modify method off of the AgentDirectoryService is still being exposed.
void	modify(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey key) Modify theAgentDescription in the VerifiableAgentDirectoryService.
void	refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport, java.lang.Object[] persistedRecords) Takes the persisted Objects that are read in, and sets them locally.
void	register(javax.agent.service.directory.AgentDescription theAgentDescription) The original register method off of the AgentDirectoryService is still being exposed.
void	register(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey key) Register theAgentDescription to the VerifiableAgentDirectoryService.
void	removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Since this Verifiable Directory Service will be persisting listeners, AbleBasicService's removeAblePlatformServiceEventListener method must be overridden to handle the removing of this service's listeners from persistence.
javax.agent.service.directory.AgentDescription[]	search(javax.agent.service.directory.AgentDescription theAgentDescription) The original search method off of the AgentDirectoryService is still being exposed.
javax.agent.service.directory.AgentDescription[]	search(javax.agent.service.directory.AgentDescription theAgentDescription, int maxResults) The original search method off of the AgentDirectoryService is still being exposed.
void	terminateService(AbleSecureKey key) When this service is terminated, there will be Verifiable Directory specific cleanup that needs to be done.

Methods inherited from class com.ibm.able.platform.AbleBasicService

getAblePlatformServiceEventListeners, getState, notifyAblePlatformServiceEventListeners, setState, thenNotifyAblePlatformServiceEventListeners

Methods inherited from class org.jagent.service.util.RMIBasicService

bindServiceToRegistry, getServiceProperties, setServiceProperties, shutdown

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.ibm.able.platform.RmiAblePlatformService

getState

Methods inherited from interface com.ibm.able.platform.RmiAblePlatformServiceEventGenerator

getAblePlatformServiceEventListeners

Constructor Detail

RMIVerifiableDirectorySystem

public RMIVerifiableDirectorySystem()
                             throws java.lang.Exception

Creates a new RMI-based Verifiable Directory Service.

Throws:

java.lang.Exception - On errors looking up other required services.

RMIVerifiableDirectorySystem

public RMIVerifiableDirectorySystem(javax.agent.service.ServiceProperties env)
                             throws java.lang.Exception

Creates a new RMI-based Verifiable Directory Service with the given ServiceProperties.

Parameters:

env - The properties that will help define this Service.

Throws:

java.lang.Exception - On errors looking up other required services.

Method Detail

getBindingName

public java.lang.String getBindingName()

Abstract method from org.jagent.service.util.RMIBasicService.

Returns:

String the binding name for this remote object.

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException

Since this Verifiable Directory Service will be persisting listeners, AbleBasicService's addAblePlatformServiceEventListener method must be overridden to handle the adding of this service's listeners from persistence.

Specified by:

addAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator

Overrides:

addAblePlatformServiceEventListener in class AbleBasicService

Throws:

AbleException - On any error adding the listener.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException

Since this Verifiable Directory Service will be persisting listeners, AbleBasicService's removeAblePlatformServiceEventListener method must be overridden to handle the removing of this service's listeners from persistence.

Specified by:

removeAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator

Overrides:

removeAblePlatformServiceEventListener in class AbleBasicService

Throws:

AbleException - On any error adding the listener.

terminateService

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

When this service is terminated, there will be Verifiable Directory specific cleanup that needs to be done. AbleBasicService's terminateService method has been overridden to take care of this cleanup.

Since this service is persisting information, it's persistence support Object will do some cleanup when being terminated.

Specified by:

terminateService in interface RmiAblePlatformService

Overrides:

terminateService in class AbleBasicService

Parameters:

key - The key that is used to secure this communication.

Throws:

AbleException - If the caller was not authorized to make this call.

javax.agent.service.naming.NamingException - On all naming errors.

refreshLocalFromPersistence

public void refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport,
                                        java.lang.Object[] persistedRecords)
                                 throws java.lang.Exception

Description copied from interface: AblePersistenceSupportProcessor

Takes the persisted Objects that are read in, and sets them locally.

This method is called one time during the lifetime of this AblePersistenceSupportProcessor Object. This method will be called the first time a successful connection is made to the PlatformPersistenceService and the persisted Objects are read in.

Specified by:

refreshLocalFromPersistence in interface AblePersistenceSupportProcessor

Parameters:

thePersistenceSupport - the object making the callback so that the processor can tell which AblePersistenceSupport object is making the call.

persistedRecords - Object[] containing all of the rows of the table this Object persists to.

Throws:

java.lang.Exception - On any error locally restoring the persisted data.

register

public void register(javax.agent.service.directory.AgentDescription theAgentDescription,
                     AbleSecureKey key)
              throws java.rmi.RemoteException,
                     javax.agent.service.directory.AlreadyRegisteredException,
                     javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

Register theAgentDescription to the VerifiableAgentDirectoryService.

If the platform is not secure when this method is called, theAgentDescription will be passed along to the non-secure register method.

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 RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The agent description to be registered.

key - The AbleSecureKey used to secure the communication.

Throws:

java.rmi.RemoteException - On all remote errors.

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.

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

deregister

public void deregister(javax.agent.service.directory.AgentDescription theAgentDescription,
                       AbleSecureKey key)
                throws java.rmi.RemoteException,
                       javax.agent.service.directory.NotRegisteredException,
                       javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

Deregister theAgentDescription from the VerifiableAgentDirectoryService.

If the platform is not secure when this method is called, theAgentDescription will be passed along to the non-secure deregister method.

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 RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The agent description to be deregistered.

key - The AbleSecureKey used to secure the communication.

Throws:

java.rmi.RemoteException - On all remote errors.

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 theAgentDescription,
                   AbleSecureKey key)
            throws java.rmi.RemoteException,
                   javax.agent.service.directory.NotRegisteredException,
                   javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

Modify theAgentDescription in the VerifiableAgentDirectoryService.

If the platform is not secure when this method is called, theAgentDescription will be passed along to the non-secure modify method.

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 RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The agent description to be modified.

key - The AbleSecureKey used to secure the communication.

Throws:

java.rmi.RemoteException - On all remote errors.

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 theAgentDescription)
              throws java.rmi.RemoteException,
                     javax.agent.service.directory.AlreadyRegisteredException,
                     javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

The original register method off of the AgentDirectoryService is still being exposed. It had to be included in this interface so persistence could be handled and since it is now a remote method.

This will insecurely register theAgentDescription to the AgentDirectoryService.

Specified by:

register in interface RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The agent description to be registered.

Throws:

javax.agent.service.directory.DirectoryFailure - On any error registering the agent description.

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

java.rmi.RemoteException - On any remote error.

deregister

public void deregister(javax.agent.service.directory.AgentDescription theAgentDescription)
                throws java.rmi.RemoteException,
                       javax.agent.service.directory.NotRegisteredException,
                       javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

The original deregister method off of the AgentDirectoryService is still being exposed. It had to be included in this interface so persistence could be handled and since it is now a remote method.

This will insecurely deregister theAgentDescription from the AgentDirectoryService.

Only non-verifiable agent descriptions can be deregistered using this method.

Specified by:

deregister in interface RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The agent description to be deregistered.

Throws:

javax.agent.service.directory.DirectoryFailure -

On any error deregistering the agent description.

If the agent description that is to be deregistered is a verifiable agent description.

java.rmi.RemoteException - On any remote error.

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

modify

public void modify(javax.agent.service.directory.AgentDescription theAgentDescription)
            throws java.rmi.RemoteException,
                   javax.agent.service.directory.NotRegisteredException,
                   javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

The original modify method off of the AgentDirectoryService is still being exposed. It had to be included in this interface so persistence could be handled and since it is now a remote method.

This will insecurely modify theAgentDescription in the AgentDirectoryService.

Only non-verifiable agent descriptions can be modified using this method.

Specified by:

modify in interface RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The agent description to be modified.

Throws:

javax.agent.service.directory.DirectoryFailure -

On any error modifying the agent description.

If the agent description that is to be modified is a verifiable agent description.

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

java.rmi.RemoteException - On any remote error.

search

public javax.agent.service.directory.AgentDescription[] search(javax.agent.service.directory.AgentDescription theAgentDescription)
                                                        throws java.rmi.RemoteException,
                                                               javax.agent.service.directory.SearchException,
                                                               javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

The original search method off of the AgentDirectoryService is still being exposed. It had to be included in this interface since it is now a remote method.

Specified by:

search in interface RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The AgentDescription to search for.

Returns:

All matching AgentDescriptions.

Throws:

javax.agent.service.directory.DirectoryFailure - On any error searching for theAgentDescription.

java.rmi.RemoteException - On any remote error.

javax.agent.service.directory.SearchException - On any error searching for theAgentDescription.

search

public javax.agent.service.directory.AgentDescription[] search(javax.agent.service.directory.AgentDescription theAgentDescription,
                                                               int maxResults)
                                                        throws java.rmi.RemoteException,
                                                               javax.agent.service.directory.SearchException,
                                                               javax.agent.service.directory.DirectoryFailure

Description copied from interface: RMIVerifiableDirectoryService

The original search method off of the AgentDirectoryService is still being exposed. It had to be included in this interface since it is now a remote method.

Specified by:

search in interface RMIVerifiableDirectoryService

Parameters:

theAgentDescription - The AgentDescription to search for.

maxResults - The maximum number of matching AgentDescription to return.

Returns:

All matching AgentDescriptions.

Throws:

javax.agent.service.directory.SearchException - On any error searching for theAgentDescription.

java.rmi.RemoteException - On any remote error.

javax.agent.service.directory.DirectoryFailure - On any error searching for theAgentDescription.

createAgentDescription

public javax.agent.service.directory.AgentDescription createAgentDescription()
                                                                      throws java.rmi.RemoteException

Description copied from interface: RMIVerifiableDirectoryService

The original createAgentDescription method off of the AgentDirectoryService is still being exposed. It had to be included in this interface since it is now a remote method.

Specified by:

createAgentDescription in interface RMIVerifiableDirectoryService

Returns:

An empty AgentDescription will be returned.

Throws:

java.rmi.RemoteException - On any remote error.