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

com.ibm.able.platform
Class RmiAgentLifeCycleSystem

java.lang.Object
  |
  +--java.rmi.server.RemoteObject
        |
        +--org.jagent.service.util.RMIBasicService
              |
              +--com.ibm.able.platform.AbleBasicService
                    |
                    +--com.ibm.able.platform.RmiAgentLifeCycleSystem
All Implemented Interfaces:
AblePersistenceSupportProcessor, org.jagent.service.IPService, java.rmi.Remote, RmiAblePlatformService, RmiAblePlatformServiceEventGenerator, RmiAgentLifeCycleService, org.jagent.service.RMIService, java.io.Serializable, javax.agent.service.Service

public final class RmiAgentLifeCycleSystem
extends AbleBasicService
implements RmiAgentLifeCycleService, AblePersistenceSupportProcessor

RmiAgentLifeCycleSystem is the implementation of an Agent Lifecycle Service; the Service can be used to get a list of agents that are permitted to run on the platform, and then start instances of particular agents in particular agent pools. Once running, an agent's lifecycle can be influenced in that an agent may be suspended, resumed, moved, destroyed, and so on.

See Also:
Serialized Form

Fields inherited from class com.ibm.able.platform.AbleBasicService
ANS_PRINCIPAL, LOCAL_PRINCIPAL, myAnsPrincipal, myKeyPair, myMsgLog, myPrincipal, mySecSppt, myServiceEventListeners, myServiceProperties, myTrcLog, myTrustLevel, myVerifiableAgentName, myVerifiableNamingService, REQUESTORS_PORT, SOCKET_FACTORY
 
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
RmiAgentLifeCycleSystem()
          Creates an instance of an RMI-based Agent Life Cycle Service.
RmiAgentLifeCycleSystem(javax.agent.service.ServiceProperties theServiceProperties)
          Creates an instance of an RMI-based Agent Life Cycle Service, using the specified service properties.
 
Method Summary
 void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
          Adds a service event listener to this service, and, if persistence is on, adds the listener to persistence store.
 AblePlatformAgent createAgentInstance(AbleAgentClassDescription theAgentClassDescription, java.lang.String theAgentPoolAlias, AbleSecureKey theSecureKey)
          Creates an instance of an agent in a specified agent pool.
 AblePlatformAgent createAgentInstanceAndInitialize(AbleAgentClassDescription theAgentClassDescription, java.lang.String theAgentPoolAlias, AbleSecureKey theSecureKey)
          Creates an instance of an agent in a specified agent pool and initializes the agent using parameters found in the specified AbleAgentClassDescription.
 AblePlatformAgent createAgentInstanceAndInitialize(AbleAgentClassDescription theAgentClassDescription, java.lang.String theAgentPoolAlias, java.lang.Object theInitArg, AbleSecureKey theSecureKey)
          Creates an instance of an agent in a specified agent pool and initializes the agent using the specified parameters.
 java.lang.String getBindingName()
           
 java.util.Vector getCreatedAgents(AbleSecureKey theSecureKey)
          Gets a collection of all AblePlatformAgent objects created by this particular Agent Lifecycle Service.
 AbleAgentClassDescription[] getPermittedAgents()
          Gets a collection of agents that are permitted to run on this platform.
 void initializeAgent(AblePlatformAgent theAblePlatformAgent, AbleSecureKey theSecureKey)
          Initializes a previously created agent.
 void initializeAgent(AblePlatformAgent theAblePlatformAgent, java.lang.Object theInitArg, AbleSecureKey theSecureKey)
          Initializes a previously created agent instance using the specified initialization argument.
 void quiesceAgentPool(java.lang.String theAgentPoolAlias, AbleSecureKey theSecureKey)
          Quiesces the specified agent pool by sending a quitAgent to each agent known to be running in the pool.
 void quitAgent(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey theSecureKey)
          Requests the agent represented by the specified AgentDescription to quit itself along with any threads the agent owns and any other beans and agents the agent may contain.
 void quitAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList, AbleSecureKey theSecureKey)
          Requests each agent represented in the specified AgentDescription list to quit itself along with any threads the agent owns and any other beans and agents the agent may contain.
 void refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport, java.lang.Object[] thePersistedRecords)
          Takes the persisted Objects that are read in, and sets them locally.
 void reinitializeAgent(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey theSecureKey)
          Re-initializes a previously initialized agent.
 void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
          Removes a service event listener from this service, and, if persistence is on, removes the listener from persistence store.
 void resetAgent(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey theSecureKey)
          Requests the agent represented by the specified AgentDescription to reset itself along with any threads the agent owns and any other beans and agents the agent may contain; however, the agent itself may decide whether to reset any internal agents and beans it may contain.
 void resetAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList, AbleSecureKey theSecureKey)
          Requests each agent represented in the specified AgentDescription list to reset itself along with any threads the agent owns and any other beans and agents the agent may contain.
 void resumeAgent(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey theSecureKey)
          Requests the agent represented by the specified AgentDescription to resume itself along with any threads the agent owns and any other beans and agents the agent may contain; however, the agent itself may decide whether to resume any internal agents and beans it may contain.
 void resumeAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList, AbleSecureKey theSecureKey)
          Requests each agent represented in the specified AgentDescription list to resume itself along with any threads the agent owns and any other beans and agents the agent may contain.
 void suspendAgent(javax.agent.service.directory.AgentDescription theAgentDescription, AbleSecureKey theSecureKey)
          Requests the agent represented by the specified AgentDescription to suspend itself along with any threads the agent owns and any other beans and agents the agent may contain; however, the agent itself may decide whether to suspend any internal agents and beans it may contain.
 void suspendAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList, AbleSecureKey theSecureKey)
          Requests each agent represented in the specified AgentDescription list to suspend itself along with any threads the agent owns and any other beans and agents the agent may contain.
 void terminateService(AbleSecureKey theSecureKey)
          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, notifyAblePlatformServiceEventListeners, 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.RmiAblePlatformServiceEventGenerator
getAblePlatformServiceEventListeners
 

Constructor Detail

RmiAgentLifeCycleSystem

public RmiAgentLifeCycleSystem()
                        throws java.lang.Exception
Creates an instance of an RMI-based Agent Life Cycle Service.
Throws:
java.lang.Exception - On any error.

RmiAgentLifeCycleSystem

public RmiAgentLifeCycleSystem(javax.agent.service.ServiceProperties theServiceProperties)
                        throws java.lang.Exception
Creates an instance of an RMI-based Agent Life Cycle Service, using the specified service properties.
Parameters:
theServiceProperties - Service properties on which the service is based.

Throws:
java.lang.Exception - On any error.
Method Detail

getBindingName

public java.lang.String getBindingName()
Overrides:
getBindingName in class org.jagent.service.util.RMIBasicService

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException
Adds a service event listener to this service, and, if persistence is on, adds the listener to persistence store.
Specified by:
addAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator
Overrides:
addAblePlatformServiceEventListener in class AbleBasicService
Parameters:
theListener - Any object interested in listening for service events generated by this service.

Throws:
AbleException - On any error adding the listener.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException
Removes a service event listener from this service, and, if persistence is on, removes the listener from persistence store.
Specified by:
removeAblePlatformServiceEventListener in interface RmiAblePlatformServiceEventGenerator
Overrides:
removeAblePlatformServiceEventListener in class AbleBasicService
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 removing the listener.

terminateService

public void terminateService(AbleSecureKey theSecureKey)
                      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:
theSecureKey - If security is on, the key used to secure this communication; otherwise, null.

Throws:
AbleException - If the caller is not authorized to make this call.
javax.agent.service.naming.NamingException - On all naming errors.

getPermittedAgents

public AbleAgentClassDescription[] getPermittedAgents()
                                               throws java.rmi.RemoteException,
                                                      AgentLifeCycleException,
                                                      AgentLifeCycleFailure
Description copied from interface: RmiAgentLifeCycleService
Gets a collection of agents that are permitted to run on this platform.
Specified by:
getPermittedAgents in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Returns:
a collection of agent class descriptions, each of which defines an agent that can run somewhere in the platform. These are passed to createAgentInstance methods to create new instances of agents in the platform.
Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.

createAgentInstance

public AblePlatformAgent createAgentInstance(AbleAgentClassDescription theAgentClassDescription,
                                             java.lang.String theAgentPoolAlias,
                                             AbleSecureKey theSecureKey)
                                      throws java.rmi.RemoteException,
                                             AgentLifeCycleException,
                                             AgentLifeCycleFailure,
                                             javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Creates an instance of an agent in a specified agent pool.

If the AbleAgentClassDescription contains constructor parameters, a constructor that matches the parameters will be used, if found. Otherwise, the agent's null argument constructor is used.

The agent is constructed, but not initialized; initialization must be performed as a separate step by calling one of the initializeAgent methods.

Specified by:
createAgentInstance in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentClassDescription - A class description obtained from the RmiAgentLifeCycleService.getPermittedAgents() method. The specified class description is verified that it is one from Agent Lifecycle's internal permitted agent list so that it cannot be spoofed.

theAgentPoolAlias - Specifies in which of the agent's eligible agent pools (defined in the platform preference file) the agent is to be created. The specified agent pool is verified against the agent's class description, so that an agent cannot be created in an agent pool in which it is not allowed to run.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Returns:
an AblePlatformAgent remote interface reference to the newly created agent.
Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException -

If the AbleAgentClassDescription is null.

If the AbleAgentClassDescription does not exist in the services's actual permitted agent list; that is, the AbleAgentClassDescription appears to have been spoofed.

If the specified agent pool name is not a valid agent pool for the AbleAgentClassDescription.

If the agent represented by the AbleAgentClassDescription is not an AblePlatformAgent.

AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

createAgentInstanceAndInitialize

public AblePlatformAgent createAgentInstanceAndInitialize(AbleAgentClassDescription theAgentClassDescription,
                                                          java.lang.String theAgentPoolAlias,
                                                          AbleSecureKey theSecureKey)
                                                   throws java.rmi.RemoteException,
                                                          AgentLifeCycleException,
                                                          AgentLifeCycleFailure,
                                                          javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Creates an instance of an agent in a specified agent pool and initializes the agent using parameters found in the specified AbleAgentClassDescription.

If the AbleAgentClassDescription contains constructor parameters, a constructor that matches the parameters will be used, if found. Otherwise, the agent's null argument constructor is used.

If the AbleAgentClassDescription contains intialization parameters, those parameters are packaged into an Object[] that is used to intialize the agent; otherwise, the agent is initialized without any special parameters.

Specified by:
createAgentInstanceAndInitialize in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentClassDescription - A class description obtained from the RmiAgentLifeCycleService.getPermittedAgents() method. The specified class description is verified that it is one from Agent Lifecycle's internal permitted agent list so that it cannot be spoofed.

theAgentPoolAlias - Specifies in which of the agent's eligible agent pools (defined in the platform preference file) the agent is to be created. The specified agent pool is verified against the agent's class description, so that an agent cannot be created in an agent pool in which it is not allowed to run.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Returns:
an AblePlatformAgent remote interface reference to the newly created agent.
Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException -

If the AbleAgentClassDescription is null.

If the AbleAgentClassDescription does not exist in the services's actual permitted agent list; that is, the AbleAgentClassDescription appears to have been spoofed.

If the specified agent pool name is not a valid agent pool for the AbleAgentClassDescription.

If the agent represented by the AbleAgentClassDescription is not an AblePlatformAgent.

AgentLifeCycleFailure - If the agent cannot be created.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

createAgentInstanceAndInitialize

public AblePlatformAgent createAgentInstanceAndInitialize(AbleAgentClassDescription theAgentClassDescription,
                                                          java.lang.String theAgentPoolAlias,
                                                          java.lang.Object theInitArg,
                                                          AbleSecureKey theSecureKey)
                                                   throws java.rmi.RemoteException,
                                                          AgentLifeCycleException,
                                                          AgentLifeCycleFailure,
                                                          javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Creates an instance of an agent in a specified agent pool and initializes the agent using the specified parameters.

If the AbleAgentClassDescription contains constructor parameters, a constructor that matches the parameters will be used, if found. Otherwise, the agent's null argument constructor is used.

Specified by:
createAgentInstanceAndInitialize in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentClassDescription - A class description obtained from the RmiAgentLifeCycleService.getPermittedAgents() method. The specified class description is verified that it is one from Agent Lifecycle's internal permitted agent list so that it cannot be spoofed.

theAgentPoolAlias - Specifies in which of the agent's eligible agent pools (defined in the platform preference file) the agent is to be created. The specified agent pool is verified against the agent's class description, so that an agent cannot be created in an agent pool in which it is not allowed to run.

theInitArg - If the initialization parameter is not null, the agent is initialized using the specified initialization parameter; otherwise, the agent is initialized without any special parameters.
theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Returns:
an AblePlatformAgent remote interface reference to the newly created agent.
Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException -

If the AbleAgentClassDescription is null.

If the AbleAgentClassDescription does not exist in the services's actual permitted agent list; that is, the AbleAgentClassDescription appears to have been spoofed.

If the specified agent pool name is not a valid agent pool for the AbleAgentClassDescription.

If the agent represented by the AbleAgentClassDescription is not an AblePlatformAgent.

AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

initializeAgent

public void initializeAgent(AblePlatformAgent theAblePlatformAgent,
                            AbleSecureKey theSecureKey)
                     throws java.rmi.RemoteException,
                            AgentLifeCycleException,
                            AgentLifeCycleFailure,
                            javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Initializes a previously created agent. The agent is initialized without any special parameters.
Specified by:
initializeAgent in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAblePlatformAgent - The agent to initialize.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

initializeAgent

public void initializeAgent(AblePlatformAgent theAblePlatformAgent,
                            java.lang.Object theInitArg,
                            AbleSecureKey theSecureKey)
                     throws java.rmi.RemoteException,
                            AgentLifeCycleException,
                            AgentLifeCycleFailure,
                            javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Initializes a previously created agent instance using the specified initialization argument.
Specified by:
initializeAgent in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAblePlatformAgent - The agent to initialize.

theInitArg - The initialization argument; typically this is an Object[] array, but depends on each agent's init method.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

reinitializeAgent

public void reinitializeAgent(javax.agent.service.directory.AgentDescription theAgentDescription,
                              AbleSecureKey theSecureKey)
                       throws java.rmi.RemoteException,
                              AgentLifeCycleException,
                              AgentLifeCycleFailure,
                              javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Re-initializes a previously initialized agent. The agent is reinitialized without any special parameters.
Specified by:
reinitializeAgent in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescription - The agent to reinitialize.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

quitAgent

public void quitAgent(javax.agent.service.directory.AgentDescription theAgentDescription,
                      AbleSecureKey theSecureKey)
               throws java.rmi.RemoteException,
                      AgentLifeCycleException,
                      AgentLifeCycleFailure,
                      javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests the agent represented by the specified AgentDescription to quit itself along with any threads the agent owns and any other beans and agents the agent may contain.
Specified by:
quitAgent in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescription - The agent to quit.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

quitAgents

public void quitAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList,
                       AbleSecureKey theSecureKey)
                throws AbleException,
                       AgentLifeCycleException,
                       AgentLifeCycleFailure,
                       javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests each agent represented in the specified AgentDescription list to quit itself along with any threads the agent owns and any other beans and agents the agent may contain.
Specified by:
quitAgents in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescriptionList - The agents to quit.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

suspendAgent

public void suspendAgent(javax.agent.service.directory.AgentDescription theAgentDescription,
                         AbleSecureKey theSecureKey)
                  throws java.rmi.RemoteException,
                         AgentLifeCycleException,
                         AgentLifeCycleFailure,
                         javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests the agent represented by the specified AgentDescription to suspend itself along with any threads the agent owns and any other beans and agents the agent may contain; however, the agent itself may decide whether to suspend any internal agents and beans it may contain.
Specified by:
suspendAgent in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescription - The agent to suspend.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

suspendAgents

public void suspendAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList,
                          AbleSecureKey theSecureKey)
                   throws java.rmi.RemoteException,
                          AgentLifeCycleException,
                          AgentLifeCycleFailure,
                          javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests each agent represented in the specified AgentDescription list to suspend itself along with any threads the agent owns and any other beans and agents the agent may contain.
Specified by:
suspendAgents in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescriptionList - The agents to suspend.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

resumeAgent

public void resumeAgent(javax.agent.service.directory.AgentDescription theAgentDescription,
                        AbleSecureKey theSecureKey)
                 throws java.rmi.RemoteException,
                        AgentLifeCycleException,
                        AgentLifeCycleFailure,
                        javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests the agent represented by the specified AgentDescription to resume itself along with any threads the agent owns and any other beans and agents the agent may contain; however, the agent itself may decide whether to resume any internal agents and beans it may contain.
Specified by:
resumeAgent in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescription - The agent to resume.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

resumeAgents

public void resumeAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList,
                         AbleSecureKey theSecureKey)
                  throws java.rmi.RemoteException,
                         AgentLifeCycleException,
                         AgentLifeCycleFailure,
                         javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests each agent represented in the specified AgentDescription list to resume itself along with any threads the agent owns and any other beans and agents the agent may contain.
Specified by:
resumeAgents in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescriptionList - The agents to resume.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

resetAgent

public void resetAgent(javax.agent.service.directory.AgentDescription theAgentDescription,
                       AbleSecureKey theSecureKey)
                throws java.rmi.RemoteException,
                       AgentLifeCycleException,
                       AgentLifeCycleFailure,
                       javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests the agent represented by the specified AgentDescription to reset itself along with any threads the agent owns and any other beans and agents the agent may contain; however, the agent itself may decide whether to reset any internal agents and beans it may contain.
Specified by:
resetAgent in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescription - The agent to reset.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

resetAgents

public void resetAgents(javax.agent.service.directory.AgentDescription[] theAgentDescriptionList,
                        AbleSecureKey theSecureKey)
                 throws java.rmi.RemoteException,
                        AgentLifeCycleException,
                        AgentLifeCycleFailure,
                        javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Requests each agent represented in the specified AgentDescription list to reset itself along with any threads the agent owns and any other beans and agents the agent may contain.
Specified by:
resetAgents in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theAgentDescriptionList - The agents to reset.

theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Throws:
java.rmi.RemoteException - On any RMI error.
AgentLifeCycleException - On any Agent Lifecycle error.
AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
javax.agent.service.naming.NamingException - On any Agent Naming Service error.

getCreatedAgents

public java.util.Vector getCreatedAgents(AbleSecureKey theSecureKey)
                                  throws java.rmi.RemoteException,
                                         AgentLifeCycleException,
                                         AgentLifeCycleFailure,
                                         javax.agent.service.naming.NamingException
Description copied from interface: RmiAgentLifeCycleService
Gets a collection of all AblePlatformAgent objects created by this particular Agent Lifecycle Service.
Specified by:
getCreatedAgents in interface RmiAgentLifeCycleService
Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
Parameters:
theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

Returns:
A collection of Object arrays.

Each element of the collection is an Object[n] object.

Each element of that is

  • [0] - (AbleAgentClassDescription) The AbleAgentClassDescription used to create the agent.
  • [1] - (String) The selected agent pool alias in which the agent was created.
  • [2] - (String) The system's IP name or address that was used to reach the agent pool.
  • [3] - (String) The system's port that was used.
  • [4] - (String) The fully qualified class name of the agent.
  • [5] - (Object) A reference to the created agent; this can be cast to the AblePlatformAgent interface.
  • [6] - (String) The globally unique AgentName of the agent.
  • [7] - (Boolean) A flag indicating whether the agent was initialzed by the Lifecycle Service
  • [8] - (Object) If initialized, any initialization arguments used.

    The collection may be empty, but not null.

    Throws:
    java.rmi.RemoteException - On any RMI error.
    AgentLifeCycleException - On any Agent Lifecycle error.
    AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
    javax.agent.service.naming.NamingException - On any Agent Naming Service error.

  • quiesceAgentPool

    public void quiesceAgentPool(java.lang.String theAgentPoolAlias,
                                 AbleSecureKey theSecureKey)
                          throws AbleException,
                                 AgentLifeCycleException,
                                 AgentLifeCycleFailure,
                                 javax.agent.service.naming.NamingException
    Description copied from interface: RmiAgentLifeCycleService
    Quiesces the specified agent pool by sending a quitAgent to each agent known to be running in the pool.

    Note that there is nothing that prevents new agents from being created in the pool during the time the pool is being quiesced.

    Specified by:
    quiesceAgentPool in interface RmiAgentLifeCycleService
    Following copied from interface: com.ibm.able.platform.RmiAgentLifeCycleService
    Parameters:
    theAgentPoolAlias - The name of an agent pool defined in the platform preference file.

    theSecureKey - Used when security is on to make sure that the caller is authentic and has the authority to perform the operation; may be null when security is off.

    Throws:
    java.rmi.RemoteException - On any RMI error.
    AgentLifeCycleException - On any Agent Lifecycle error.
    AgentLifeCycleFailure - When there is a problem in the lifecycle infrastructure code.
    javax.agent.service.naming.NamingException - On any Agent Naming Service error.

    refreshLocalFromPersistence

    public void refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport,
                                            java.lang.Object[] thePersistedRecords)
                                     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
    Following copied from interface: com.ibm.able.platform.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.

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

    (C) Copyright IBM Corporation 1999, 2003