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

com.ibm.able.platform
Class AblePlatformDefaultAgent

java.lang.Object
  |
  +--com.ibm.able.AbleObject
        |
        +--com.ibm.able.AbleDefaultAgent
              |
              +--com.ibm.able.AbleRemoteDefaultAgent
                    |
                    +--com.ibm.able.platform.AblePlatformDefaultAgent
All Implemented Interfaces:
AbleAgent, AbleBean, AbleBeanContainer, AbleBeanRemoteContainer, AbleDataBufferManager, AbleEventListener, AbleEventListenerManager, AbleEventListenerRemoteManager, AbleEventQueueManager, AbleEventQueueProcessor, AbleEventQueueRemoteManager, AblePlatformAgent, AblePropertyChangeManager, AbleRemoteAgent, AbleRemoteBean, AbleRemoteEventListener, AbleSerializable, AbleUserDefinedFunctionManager, AbleUserDefinedFunctionRemoteManager, java.util.EventListener, javax.agent.service.transport.MessageListener, java.beans.PropertyChangeListener, java.rmi.Remote, java.io.Serializable
Direct Known Subclasses:
AbleJasConversationAgent, AblePlatformConversationAgent, JasKnnCentralAgent, JasKnnDistributedAgent, JasNaiveBayesCentralAgent, JasNaiveBayesDistributedAgent

public class AblePlatformDefaultAgent
extends AbleRemoteDefaultAgent
implements AblePlatformAgent, javax.agent.service.transport.MessageListener, java.io.Serializable

This class provides an enhanced implementation of a JSR 87 (Java Agent Services or JAS) compliant agent, but also inherits all the capabilities of an AbleDefaultAgent; as a JAS agent, the agent obtains a globally unique AgentName from the Agent Naming Service, registers a description with the Agent Directory Service, and is able to send and receive messages through the Message Transport System.

Typically, an agent's lifecycle is as follws:

See Also:
Serialized Form

Field Summary
protected  java.util.Date agentLastUpdate
          The date and time when the agent's description was last updated with the Agent Directory Service.
protected  boolean agentMovable
          Specifies whether the agent is movable from one agent pool to another; must be set before the agent is initialized, at which time it is placed into the agent's registered description.
protected  java.lang.String agentStatus
          The agent's status at the last time the agent's description was updated with the Agent Directory Service.
protected  AbleMessageContainer agentSummary
          The agent's last set summary text.
protected  boolean agentToAutoRegister
          Specifies whether the agent is to register an AgentDescription of itself with the Agent Directory Service; must be set before the agent is initialized.
protected  boolean agentToBindToRmi
          Specifies whether the agent is to bind itself to the RMI Naming service; must be set before the agent is initialized.
protected  java.lang.String agentType
          The textual description of the type of agent; must be set before the agent is initialized, at which time it is placed into the agent's registered description; for documentation only.
protected  java.lang.String agentVendor
          The agent's vendor; must be set before the agent is initialized, at which time it is placed into the agent's registered description; for documentation only.
protected  java.lang.String agentVersion
          The agent's current version; must be set before the agent is initialized, at which time it is placed into the agent's registered description; for documentation only.
protected  java.util.Vector myAgentInboxes
          Locators/MessageListeners/Inboxes for this agent.
protected  javax.agent.Locator myJasAbleLocator
          An ABLE direct communication locator that contains an RMI reference to this agent so that methods on the agent can be called directly.
protected  java.util.Hashtable myJasAgentAttributes
          User-defined attributes for this agent.
protected  javax.agent.service.directory.AgentDescription myJasAgentDescription
          The JAS description for this agent, set at initialization time.
protected  javax.agent.service.directory.AgentDirectoryService myJasAgentDirectoryService
          A cached reference to the JAS Agent Directory service for this agent, set during pre-initialization.
protected  javax.agent.AgentName myJasAgentName
          The JAS globally unique Id for this agent, set during pre-initialization.
protected  javax.agent.service.naming.AgentNamingService myJasAgentNamingService
          A cached reference to the JAS Agent Naming service for this agent, set during pre-initialization.
protected  javax.agent.Locator myJasDefaultLocator
          A default locator, set by init() to the first of the generated Locators.
protected  javax.agent.service.transport.MessageTransportService myJasMessageTransportService
          A cached reference to the JAS Message Transport Service, if there is one; set at initialization time.
protected  javax.agent.service.ServiceRoot myJasServiceRoot
          A cached reference to the JAS Service Root for this agent, from which other services can be obtained; set during pre-initialization.
protected  javax.agent.service.transport.TransportSystem myJasTransportSystem
          The JAS Transport System for this agent, set during pre-initialization.
protected  VerifiableAgentDirectoryService myJasVerifiableDirectoryService
          The IBM Verifiable Agent Directory service for this agent, set during pre-initialization.
protected  VerifiableAgentNamingService myJasVerifiableNamingService
          The IBM Verifiable Agent Naming service for this agent, set during pre-initialization.
protected  java.security.KeyPair myKeyPair
          Public and Private keys, created by the constructors, but only if security is on.
protected  java.lang.String myPrincipal
          This field is used ONLY in a secure environment and ONLY when the agent is not started through the Agent Lifecycle Service; that is, the agent is started through a command line or by another agent.
protected  AbleUserDefinedFunction myReceiveMessageMethod
          The encapsulated default "receiveMessage()" method; this is the default method called by JAS Message Transport Service when a message arrives for the agent, but the agent can change this to some other method before init() is called.
protected  AbleSecureKey myRequestKey
          On secure platforms, having a loaded key of the Platform Support code that created an agent is very important to the agent.
protected  AbleSecuritySupport mySecSppt
          A helper object to assist with security related matters.
protected  java.lang.String myTrustLevel
          The Trust Level cached from the VerifiableAgentName (VAN) for this agent; set during pre-initialization.
protected  VerifiableAgentName myVerifiableAgentName
          A globally unique verifiable Id for this agent, set during pre-initialization.
 
Fields inherited from class com.ibm.able.AbleRemoteDefaultAgent
agentAddr, agentHost, agentName, defaultName, myRemoteStub
 
Fields inherited from class com.ibm.able.AbleDefaultAgent
activeDataSource, eventConnections, myBeans, numEpochs, processList, processListOK, userDefinedFunctions
 
Fields inherited from class com.ibm.able.AbleObject
changed, chgSupport, comment, dataFlowEnabled, destBufferConnections, eventQueue, fileName, inputBuffer, listeners, logger, name, outputBuffer, parent, propertyConnectionMgr, sourceBufferConnections, state, stateChgSupport, trace
 
Constructor Summary
AblePlatformDefaultAgent()
          Creates a new platform agent.
AblePlatformDefaultAgent(java.lang.String theName)
          Creates a new platform agent with the specified display name (not to be confused with the agent's globally unique AgentName).
AblePlatformDefaultAgent(java.lang.String theName, java.lang.String theComment)
          Creates a new platform agent with the specified display name (not to be confused with the agent's globally unique AgentName) and comment.
 
Method Summary
protected  void _init()
          Performs the actual work of initialization.
protected  void _init(java.lang.Object theArg)
          Does all the initial Java Agent Services (JAS) housekeeping in a manner identical to _init(), but the specified argument is passed to the super class for handling.
protected  void _quitAll()
          Performs the actual work of destroying this agent; this method must be used only when security is off, or only when security is on AND an Able SecureKey has already been verified.
protected  void _reset()
          Performs the actual work of resetting the agent; this method must be used only when security is off, or only when security is on AND an Able SecureKey has already been verified.
protected  void _resumeAll()
          Performs the actual work of resuming this agent; this method must be used only when security is off, or only when security is on AND an Able SecureKey has already been verified.
protected  void _suspendAll()
          Performs the actual work of suspending this agent; this method must be used only when security is off, or only when security is on AND an Able SecureKey has already been verified.
 void addAgentInbox(java.lang.Object[] theProtocol)
           
 void addJasAgentAttribute(java.lang.String theKey, java.lang.Object theAttribute)
          Adds a named attribute to the agent's set of attributes.
protected  void broadcastTransportMessage(java.util.Vector theDestinations, java.lang.Object theMessageToSend)
          Sends a message to a list of agents.
static java.lang.String Copyright()
          Gets the copyright statement of this class.
protected  javax.agent.Locator createLocatorAndBindToMethod(java.lang.String theProtocol, AbleUserDefinedFunction theUserDefinedFunction)
          This is a helper method for loadAgentDescriptionWithBaseLocators().
 int getAgentAutonomyLevel()
          Gets the agent's autonomy level.
 java.util.Vector getAgentInboxes()
           
 java.util.Date getAgentLastUpdate()
          Gets the date and time when the agent's description was last updated with the Agent Directory Service..
 java.lang.String getAgentStatus()
          Gets the agent's current real time status (state).
 AbleMessageContainer getAgentSummary()
          Gets the agent's current summary text.
 java.lang.String getAgentType()
          Gets the agent's type description.
 java.lang.String getAgentVendor()
          Gets the agent's vendor.
 java.lang.String getAgentVersion()
          Gets the agent's version.
protected  void getAndSetAgentDescription()
          Calls getNewAgentDescription() to get a new, empty Agent Description and then Calls loadAgentDescriptionWithAgentName() to set the agent's names into the description Calls loadAgentDescriptionWithPublicKey() to set the agent's public key into the description Calls loadAgentDescriptionWithAbleAttributes() to set built-in Able attributes into the description Calls loadAgentDescriptionWithUserAttributes() to set any user-defined attributes into the description.
protected  void getAndSetAgentNames()
          Gets this agent's Globally Unique ID (GUID or AgentName) from the Agent Naming Service and saves it away in the data member myJasAgentName; additionally, if security is on, a verifiable agent name is obtained and saved in the data member myVerifiableAgentName, and the data members myTrustLevel, myPrincipal, and mySecSppt are also set.
protected  void getAndSetTransportServices()
          Gets all available Message Transport Services from the Message Transport System, selects the first one, and saves it away in the data member myJasMessageTransportService.
protected  void getAndValidateServiceRoot()
          Gets addressability to the JAS Service Root, and makes sure the Agent Naming Service, the Agent Directory Service, and the Message Transport System are all available.
 java.util.Hashtable getJasAgentAttributes()
          Gets the agent's JAS attributes.
 java.lang.String getJasAgentName()
          Gets the agent's globally unique ID (GUID or AgentName) in text form.
protected  void getNewAgentDescription()
          Gets a new, empty Agent Description and saves it away in the data member myJasAgentDescription.
 java.lang.String getPrincipal()
           
protected  java.lang.Object getTransportMessageContent(javax.agent.TransportMessage theTransportMessage)
          Extracts and returns the content of the specified transport message.
protected  java.lang.Object getTransportMessageContent2(javax.agent.TransportMessage theTransportMessage)
          Extracts and returns the content of the specified transport message.
 void init()
          Initializes and configures the bean, but only if security is off; when security is on, calls to this method are ignored -- the method initializeAgent(AbleSecureKey) must be used instead.
 void init(java.lang.Object theArg)
          Initializes and configures the bean, using the specified Object, but only if security is off; when security is on, calls to this method are ignored -- the method initializeAgent(Object,AbleSecureKey) must be used instead.
 void initializeAgent(AbleSecureKey theSecureKey)
          Initializes and configures the agent.
 void initializeAgent(java.lang.Object theInitArg, AbleSecureKey theSecureKey)
          Initializes and configures the agent using the specified parameter, which is typically an Object[], but may be anything that the agent is coded to expect.
 boolean isAgentMovable()
          Determines whether the agent is movable from one agent pool to another.
 boolean isAgentToAutoRegister()
          Determines whether the agent is to register with an RMI Registry at initialization time.
 boolean isAgentToBindToRmi()
          Determines whether the agent is to bind to RMI Naming at initialization time.
protected  void loadAgentDescriptionWithAbleAttributes()
          Loads this agent's description with the built-in Able attributes, which must be set before initialization time.
protected  void loadAgentDescriptionWithAbleLocator()
          Loads this agent's description with a special Able Locator, found in the data member myJasAbleLocator, which is a locator that contains an RMI reference to this agent, and which can be used to call those public, "remotable" methods found in this agent.
protected  void loadAgentDescriptionWithAgentName()
          Loads this agent's description with the agent's Globally Unique ID (GUID) or AgentName as contained in the data member myJasAgentName.
protected  void loadAgentDescriptionWithBaseLocators()
          Loads this agent's description with Locators created from the selected Message Transport Service.
protected  void loadAgentDescriptionWithPublicKey()
          Loads this agent's description with the agent's public key, but only if security is on.
protected  void loadAgentDescriptionWithUserAttributes()
          Loads this agent's description with those user-defined attributes that have been placed into the data member myJasAgentAttributes.
protected  void logException(java.lang.String theMethodName, java.lang.Exception theException)
          Logs an exception.
protected  javax.agent.service.directory.AgentDescription[] lookUpAgent(java.util.Hashtable theSearchAttributesAndValues)
          Finds all agents registered with the Agent Directory whose agent description contains the specified attributes and values.
protected  javax.agent.service.directory.AgentDescription[] lookUpAgent(java.lang.String theSearchAttribute, java.lang.Object theSearchValue)
          Finds all agents registered with the Agent Directory whose agent description contains the specified attribute and value.
static void main(java.lang.String[] args)
           
protected  void maybeDeregisterWithAgentDirectoryService()
          Deregisters this agent with the Agent Directory Service, depending on whether the agent is registered.
protected  void maybeRebindToRmi(boolean theBindToRmiFlag)
          (Re)binds this agent to RMI Naming lookup service, depending on the value of the specified flag.
protected  void maybeRegisterWithAgentDirectoryService(boolean theRegisterFlag)
          Registers this agent with the Agent Directory Service, depending on the value of the specified flag.
protected  void maybeUnbindFromRmi()
          Unbinds this agent from RMI Naming, depending on whether it has been bound to RMI.
 void preInit()
          Pre-initializes the agent immediately after creation, causing the agent to find the Service Root, extract references to various services, obtain a unique AgentName from the Agent Naming Service, and, when security is on, a VerifiableAgentName (VAN).
 java.lang.Object process(java.lang.Object theArg)
          Performs the main, standard processing function of this platform agent, using the argument.
 void quitAgent(AbleSecureKey theSecureKey)
          Quits the agent, which typically quits all contained beans and agents.
 void quitAll()
          Stops all of the bean's asynchronous threads of control, but only if security is off; when security is on, calls to this method are ignored -- the method quitAgent(AbleSecureKey) must be used instead.
 void receiveMessage(javax.agent.TransportMessage theTransportMessage)
          Receives and handles a message from the JAS Message Transport Service.
 void removeAgentInbox(java.lang.Object[] theProtocol)
           
 void removeAgentInboxes()
           
 void removeJasAgentAttribute(java.lang.String theKey)
          Removes a named attribute from the agent's set of attributes.
 void reset()
          Resets the bean, but only if security is off; when security is on, calls to this method are ignored -- the method resetAgent(AbleSecureKey) must be used instead.
 void resetAgent(AbleSecureKey theSecureKey)
          Resets the agent to its "initialized" state.
 void resumeAgent(AbleSecureKey theSecureKey)
          Resumes all asynchronous threads of control, typically including those in any contained beans and agents.
 void resumeAll()
          Resumes all of the bean's asynchronous threads of control, but only if security is off; when security is on, calls to this method are ignored -- the method resumeAgent(AbleSecureKey) must be used instead.
protected  void sendTransportMessage(javax.agent.Locator theDestinationLocator, javax.agent.AgentName theDestinationAgentName, java.lang.Object theMessageToSend)
          Sends a message to the specified agent.
protected  void sendTransportMessage(javax.agent.Locator theOriginationLocator, javax.agent.Locator theDestinationLocator, javax.agent.AgentName theDestinationAgentName, java.lang.Object theMessageToSend)
          Sends an ACL message to the specified agent.
protected  void setAgentAutonomyLevel(int theAgentAutonomyLevel)
          Sets the agent's autonomy level.
 void setAgentAutonomyLevel(int theAgentAutonomyLevel, AbleSecureKey theSecureKey)
          Sets the agent's autonomy level.
 void setAgentMovable(boolean theAgentMovableFlag)
          Sets whether the agent is movable from one agent pool to another.
 void setAgentSummary(AbleMessageContainer theAgentSummary)
          Sets the agent's current summary text.
 void setAgentToAutoRegister(boolean theAgentToAutoRegisterFlag)
          Sets whether the agent is to register with the Agent Directory Service at initialization time.
 void setAgentToBindToRmi(boolean theAgentToBindToRmiFlag)
          Sets whether the agent is to bind to the RMI Naming service at initialization time.
 void setAgentType(java.lang.String theAgentType)
          Sets the agent's type description.
 void setAgentVendor(java.lang.String theAgentVendor)
          Sets the agent's vendor.
 void setAgentVersion(java.lang.String theAgentVersion)
          Sets the agent's version.
 void setPrincipal(java.lang.String thePrincipal)
           
 void setRequestKey(AbleSecureKey theRequestKey)
          Sets the AbleSecureKey this agent will use to make a VAN request to the VerifiableAgentNamingService.
 void suspendAgent(AbleSecureKey theSecureKey)
          Temporarily suspends all asynchronous threads of control, typically including those in any contained beans and agents.
 void suspendAll()
          Suspends all of the bean's asynchronous threads of control, but only if security is off; when security is on, calls to this method are ignored -- the method suspendAgent(AbleSecureKey) must be used instead.
 java.lang.String toString()
          Gets a string describing (the contents of) the object.
protected  void updateDescriptionWithAgentDirectoryService()
          Updates this agent's description with the Agent Directory Service.
 
Methods inherited from class com.ibm.able.AbleRemoteDefaultAgent
getAgentAddr, getAgentHost, getAgentName, rmiRebind, rmiUnbind
 
Methods inherited from class com.ibm.able.AbleDefaultAgent
addBean, addBeans, addEventConnection, addUserDefinedFunction, buildProcessList, clsNm, containsBean, containsBean, containsUserDefinedFunction, debugTrace, generateUniqueName, getBean, getBeans, getDataSource, getNumEpochs, getProcessList, getUserDefinedFunction, getUserDefinedFunctions, handleAbleEvent, invokeUserDefinedFunction, isActiveDataSource, process, propertyChange, quitEnabledEventProcessing, removeAllBeans, removeAllConnections, removeAllEventConnections, removeBean, removeBean, removeBeans, removeEventConnection, removeUserDefinedFunction, setActiveDataSource, setDataFlowEnabled, setProcessList, setUserDefinedFunctions
 
Methods inherited from class com.ibm.able.AbleObject
addAbleEventListener, addDestBufferConnection, addPropertyChangeListener, addPropertyConnection, addSourceBufferConnection, addStateChangeListener, dataChanged, firePropertyChange, flushAbleEventQueue, getAbleEventListeners, getAbleEventProcessingEnabled, getAbleEventQueueSize, getComment, getDestBufferConnections, getFileName, getInputBuffer, getInputBuffer, getInputBufferAsStringArray, getInputBufferContents, getLogger, getName, getOutputBuffer, getOutputBuffer, getOutputBufferAsStringArray, getOutputBufferContents, getParent, getPropertyConnectionManager, getSleepTime, getSourceBufferConnections, getState, getTraceLogger, hasInputBuffer, hasOutputBuffer, isAbleEventPostingEnabled, isAbleEventProcessingEnabled, isChanged, isConnectable, isDataFlowEnabled, isTimerEventProcessingEnabled, notifyAbleEventListeners, processAbleEvent, processBufferConnections, processNoEventProcessingEnabledSituation, processTimerEvent, removeAbleEventListener, removeAllAbleEventListeners, removeAllBufferConnections, removeAllPropertyConnections, removeDestBufferConnection, removePropertyChangeListener, removePropertyConnection, removeSourceBufferConnection, removeStateChangeListener, restartEnabledEventProcessing, restoreFromFile, restoreFromFile, restoreFromSerializedFile, restoreFromStream, resumeEnabledEventProcessing, saveToFile, saveToFile, setAbleEventProcessingEnabled, setChanged, setComment, setFileName, setInputBuffer, setInputBuffer, setLogger, setName, setOutputBuffer, setOutputBuffer, setParent, setSleepTime, setState, setTimerEventProcessingEnabled, setTraceLogger, sourceConnectionsOK, startEnabledEventProcessing, suspendEnabledEventProcessing
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.ibm.able.AbleRemoteAgent
addEventConnection, getAgentAddr, getAgentHost, getAgentName, getDataSource, isActiveDataSource, removeEventConnection, setActiveDataSource
 
Methods inherited from interface com.ibm.able.AbleRemoteBean
getName, getState, process
 
Methods inherited from interface com.ibm.able.AbleRemoteEventListener
handleAbleEvent
 
Methods inherited from interface com.ibm.able.AbleEventListenerRemoteManager
addAbleEventListener, notifyAbleEventListeners, removeAbleEventListener
 
Methods inherited from interface com.ibm.able.AbleEventQueueRemoteManager
flushAbleEventQueue, getAbleEventProcessingEnabled, getAbleEventQueueSize, getSleepTime, isTimerEventProcessingEnabled, quitEnabledEventProcessing, restartEnabledEventProcessing, resumeEnabledEventProcessing, setAbleEventProcessingEnabled, setSleepTime, setTimerEventProcessingEnabled, startEnabledEventProcessing, suspendEnabledEventProcessing
 
Methods inherited from interface com.ibm.able.AbleBeanRemoteContainer
addBean, containsBean, containsBean, getBean, getBeans, removeAllBeans, removeBean, removeBean
 
Methods inherited from interface com.ibm.able.AbleUserDefinedFunctionRemoteManager
addUserDefinedFunction, containsUserDefinedFunction, getUserDefinedFunction, getUserDefinedFunctions, invokeUserDefinedFunction, removeUserDefinedFunction, setUserDefinedFunctions
 
Methods inherited from interface javax.agent.service.transport.MessageListener
equals, hashCode
 
Methods inherited from interface com.ibm.able.AbleBean
getComment, getLogger, getName, getParent, getState, getTraceLogger, isChanged, setChanged, setComment, setLogger, setName, setParent, setState, setTraceLogger
 
Methods inherited from interface com.ibm.able.AbleDataBufferManager
addDestBufferConnection, addSourceBufferConnection, getDestBufferConnections, getInputBuffer, getInputBuffer, getInputBufferAsStringArray, getInputBufferContents, getOutputBuffer, getOutputBuffer, getOutputBufferAsStringArray, getOutputBufferContents, getSourceBufferConnections, hasInputBuffer, hasOutputBuffer, isConnectable, isDataFlowEnabled, processBufferConnections, removeAllBufferConnections, removeDestBufferConnection, removeSourceBufferConnection, setInputBuffer, setInputBuffer, setOutputBuffer, setOutputBuffer
 
Methods inherited from interface com.ibm.able.AbleEventListenerManager
addAbleEventListener, dataChanged, getAbleEventListeners, notifyAbleEventListeners, removeAbleEventListener
 
Methods inherited from interface com.ibm.able.AbleEventQueueManager
flushAbleEventQueue, getAbleEventProcessingEnabled, getAbleEventQueueSize, getSleepTime, isAbleEventPostingEnabled, isAbleEventProcessingEnabled, isTimerEventProcessingEnabled, restartEnabledEventProcessing, resumeEnabledEventProcessing, setAbleEventProcessingEnabled, setSleepTime, setTimerEventProcessingEnabled, startEnabledEventProcessing, suspendEnabledEventProcessing
 
Methods inherited from interface com.ibm.able.AbleEventQueueProcessor
processAbleEvent, processNoEventProcessingEnabledSituation, processTimerEvent
 
Methods inherited from interface com.ibm.able.AblePropertyChangeManager
addPropertyChangeListener, addPropertyConnection, getPropertyConnectionManager, removeAllPropertyConnections, removePropertyChangeListener, removePropertyConnection
 
Methods inherited from interface com.ibm.able.AbleSerializable
getFileName, restoreFromFile, restoreFromFile, saveToFile, saveToFile, setFileName
 
Methods inherited from interface com.ibm.able.AbleBeanContainer
getName
 

Field Detail

agentLastUpdate

protected java.util.Date agentLastUpdate
The date and time when the agent's description was last updated with the Agent Directory Service.

agentStatus

protected java.lang.String agentStatus
The agent's status at the last time the agent's description was updated with the Agent Directory Service.

agentSummary

protected AbleMessageContainer agentSummary
The agent's last set summary text.

agentType

protected java.lang.String agentType
The textual description of the type of agent; must be set before the agent is initialized, at which time it is placed into the agent's registered description; for documentation only.

agentVendor

protected java.lang.String agentVendor
The agent's vendor; must be set before the agent is initialized, at which time it is placed into the agent's registered description; for documentation only.

agentVersion

protected java.lang.String agentVersion
The agent's current version; must be set before the agent is initialized, at which time it is placed into the agent's registered description; for documentation only.

agentToAutoRegister

protected boolean agentToAutoRegister
Specifies whether the agent is to register an AgentDescription of itself with the Agent Directory Service; must be set before the agent is initialized.

agentToBindToRmi

protected boolean agentToBindToRmi
Specifies whether the agent is to bind itself to the RMI Naming service; must be set before the agent is initialized.

agentMovable

protected boolean agentMovable
Specifies whether the agent is movable from one agent pool to another; must be set before the agent is initialized, at which time it is placed into the agent's registered description.

myJasAgentAttributes

protected java.util.Hashtable myJasAgentAttributes
User-defined attributes for this agent. The attributes must be set before the agent is initialized. At initialization time, any attributes found here are added to the agent's JAS AgentDescription.

myAgentInboxes

protected java.util.Vector myAgentInboxes
Locators/MessageListeners/Inboxes for this agent.

This field must be set before the agent is initialized. At initialization time, one Locator/AbleJasMessageListener pair is created for each entry found in this collection and the Locater is added to the agent's AgentDescription. The first entry here becomes a "default" Locator. If there are no entries here, a default Locator, tied to this agent's receiveMessage(TransportMessage) method is created.

Each element of the inbox collection is an array of Object[2]. The first element (index 0) of each subarray is the protocol designated for that inbox; this is simply a string that will appear in the Locator and its associated AbleJasMessageListener. Specify the empty string ("") if the agent doesn't care about tagging each inbox with a protocol. The second element (index 1) is the UDF the message listener will call when a message arrives. For example,

 (
   ( "carBuyerSeller"       UDF:receiveCarBuyerSellerMsg(TransportMessage) )
   ( "creditCheck"          UDF:receiveCreditCheckMsg(TransportMessage)  )
 )
 
See Also:
AbleJasMessageListener

myPrincipal

protected java.lang.String myPrincipal
This field is used ONLY in a secure environment and ONLY when the agent is not started through the Agent Lifecycle Service; that is, the agent is started through a command line or by another agent. It is up to the agent to set this field BEFORE init() is called. The setting of this field can be done through prompting, hard-coding, or by another entity, such as the program that created the agent.

myJasServiceRoot

protected javax.agent.service.ServiceRoot myJasServiceRoot
A cached reference to the JAS Service Root for this agent, from which other services can be obtained; set during pre-initialization.
See Also:
preInit()

myJasAgentDirectoryService

protected javax.agent.service.directory.AgentDirectoryService myJasAgentDirectoryService
A cached reference to the JAS Agent Directory service for this agent, set during pre-initialization.
See Also:
preInit()

myJasVerifiableDirectoryService

protected VerifiableAgentDirectoryService myJasVerifiableDirectoryService
The IBM Verifiable Agent Directory service for this agent, set during pre-initialization. This verifiable directory service is valid only when security is on and is the identical directory service of myJasAgentDirectoryService, but with additional methods.
See Also:
preInit()

myJasAgentNamingService

protected javax.agent.service.naming.AgentNamingService myJasAgentNamingService
A cached reference to the JAS Agent Naming service for this agent, set during pre-initialization.
See Also:
preInit()

myJasVerifiableNamingService

protected VerifiableAgentNamingService myJasVerifiableNamingService
The IBM Verifiable Agent Naming service for this agent, set during pre-initialization. This verifiable naming service is valid only when security is on and is the identical naming service of myJasAgentNamingService, but with additional methods.
See Also:
preInit()

myJasTransportSystem

protected javax.agent.service.transport.TransportSystem myJasTransportSystem
The JAS Transport System for this agent, set during pre-initialization.
See Also:
preInit()

myJasAgentName

protected javax.agent.AgentName myJasAgentName
The JAS globally unique Id for this agent, set during pre-initialization.
See Also:
preInit()

myVerifiableAgentName

protected VerifiableAgentName myVerifiableAgentName
A globally unique verifiable Id for this agent, set during pre-initialization. When security is on, this field is identical to myJasAgentName. When security is off, the field is null.
See Also:
preInit()

myTrustLevel

protected java.lang.String myTrustLevel
The Trust Level cached from the VerifiableAgentName (VAN) for this agent; set during pre-initialization.
See Also:
preInit()

myJasAgentDescription

protected javax.agent.service.directory.AgentDescription myJasAgentDescription
The JAS description for this agent, set at initialization time. The description will contain those attributes defined as integral to this base default ABLE Platform agent, as well as those set in the user-defined attributes, myJasAgentAttributes.

myJasMessageTransportService

protected javax.agent.service.transport.MessageTransportService myJasMessageTransportService
A cached reference to the JAS Message Transport Service, if there is one; set at initialization time.

myJasDefaultLocator

protected javax.agent.Locator myJasDefaultLocator
A default locator, set by init() to the first of the generated Locators. This locator appears in the AgentDescription.
See Also:
myAgentInboxes

myJasAbleLocator

protected javax.agent.Locator myJasAbleLocator
An ABLE direct communication locator that contains an RMI reference to this agent so that methods on the agent can be called directly. This locator appears in the AgentDescription.

myReceiveMessageMethod

protected AbleUserDefinedFunction myReceiveMessageMethod
The encapsulated default "receiveMessage()" method; this is the default method called by JAS Message Transport Service when a message arrives for the agent, but the agent can change this to some other method before init() is called. At init() time, the method encapsulated here is what is wired to the default JAS locator placed in the AgentDescription.

myKeyPair

protected java.security.KeyPair myKeyPair
Public and Private keys, created by the constructors, but only if security is on. If security is off, this field is null.

myRequestKey

protected AbleSecureKey myRequestKey
On secure platforms, having a loaded key of the Platform Support code that created an agent is very important to the agent. This key is set directly by platform support immediately after the agent is created and is the key that this agent will use when asking the ANS to create it a verifiable agent name.

This field tells the agent what AbleSecureKey to use to request a VAN.


mySecSppt

protected transient AbleSecuritySupport mySecSppt
A helper object to assist with security related matters.

This object is null unless security is on.

When security is on, this object is created during the preinitialization process, and thereafter is used as a helper object to generate and verify secure keys and trust levels.

On deserialization, this object must be recreated!

Constructor Detail

AblePlatformDefaultAgent

public AblePlatformDefaultAgent()
                         throws java.rmi.RemoteException,
                                AbleException
Creates a new platform agent.
Throws:
java.rmi.RemoteException - On any RMI error.
AbleException - On any error.

AblePlatformDefaultAgent

public AblePlatformDefaultAgent(java.lang.String theName)
                         throws java.rmi.RemoteException,
                                AbleException
Creates a new platform agent with the specified display name (not to be confused with the agent's globally unique AgentName).
Parameters:
theName - A string containing the Able display name of this new agent.

Throws:
java.rmi.RemoteException - On any RMI error.
AbleException - On any error.

AblePlatformDefaultAgent

public AblePlatformDefaultAgent(java.lang.String theName,
                                java.lang.String theComment)
                         throws java.rmi.RemoteException,
                                AbleException
Creates a new platform agent with the specified display name (not to be confused with the agent's globally unique AgentName) and comment.
Parameters:
theName - A string containing the Able display name of this new agent.

theComment - A string containing a comment for this new agent.

Throws:
java.rmi.RemoteException - On any RMI error.
AbleException - On any error.
Method Detail

getAgentAutonomyLevel

public int getAgentAutonomyLevel()
                          throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's autonomy level.
Specified by:
getAgentAutonomyLevel in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
An autonomy level as defined in AblePlatform.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentAutonomyLevel

public void setAgentAutonomyLevel(int theAgentAutonomyLevel,
                                  AbleSecureKey theSecureKey)
                           throws AbleException,
                                  javax.agent.service.naming.NamingException
Sets the agent's autonomy level.
Specified by:
setAgentAutonomyLevel in interface AblePlatformAgent
Parameters:
theAgentAutonomyLevel - An autonomy level as defined in AblePlatform.

theSecureKey - If security is on, a key that can be used to authenticate and authorize the caller; otherwise, may be null.

Throws:
AbleException - If the specified autonomy level isn't a level defined in AblePlatform or if the caller isn't authorized.
javax.agent.service.naming.NamingException - If the caller is not authenticated.

setAgentAutonomyLevel

protected void setAgentAutonomyLevel(int theAgentAutonomyLevel)
                              throws AbleException
Sets the agent's autonomy level.
Parameters:
theAgentAutonomyLevel - An autonomy level as defined in AblePlatform.

Throws:
AbleException - If the specified autonomy level isn't a level defined in AblePlatform.

getAgentLastUpdate

public java.util.Date getAgentLastUpdate()
                                  throws AbleException
Description copied from interface: AblePlatformAgent
Gets the date and time when the agent's description was last updated with the Agent Directory Service..
Specified by:
getAgentLastUpdate in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
The date and time the agent's description was last updated.
Throws:
java.rmi.RemoteException - On any RMI error.

getAgentStatus

public java.lang.String getAgentStatus()
                                throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's current real time status (state).
Specified by:
getAgentStatus in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
The agent's real time status.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentSummary

public void setAgentSummary(AbleMessageContainer theAgentSummary)
Sets the agent's current summary text.
Parameters:
theAgentSummary - The agent's summary text.

getAgentSummary

public AbleMessageContainer getAgentSummary()
                                     throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's current summary text.
Specified by:
getAgentSummary in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
The agent's summary current summary text.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentType

public void setAgentType(java.lang.String theAgentType)
Sets the agent's type description.
Parameters:
theAgentType - The agent's type description.

getAgentType

public java.lang.String getAgentType()
                              throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's type description.
Specified by:
getAgentType in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
The agent's type description.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentVendor

public void setAgentVendor(java.lang.String theAgentVendor)
Sets the agent's vendor.
Parameters:
theAgentVendor - The agent's vendor.

getAgentVendor

public java.lang.String getAgentVendor()
                                throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's vendor.
Specified by:
getAgentVendor in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
The agent's vendor.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentVersion

public void setAgentVersion(java.lang.String theAgentVersion)
Sets the agent's version.
Parameters:
theAgentVersion - The agent's version.

getAgentVersion

public java.lang.String getAgentVersion()
                                 throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's version.
Specified by:
getAgentVersion in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
The agent's version.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentToAutoRegister

public void setAgentToAutoRegister(boolean theAgentToAutoRegisterFlag)
Sets whether the agent is to register with the Agent Directory Service at initialization time.
Parameters:
theAgentToAutoRegisterFlag - Use true (default) if the agent is to register an AgentDescription with the Agent Directory Service; false otherwise.

isAgentToAutoRegister

public boolean isAgentToAutoRegister()
                              throws AbleException
Description copied from interface: AblePlatformAgent
Determines whether the agent is to register with an RMI Registry at initialization time.
Specified by:
isAgentToAutoRegister in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
true if the agent is to register with an RMI Registry; false otherwise.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentToBindToRmi

public void setAgentToBindToRmi(boolean theAgentToBindToRmiFlag)
Sets whether the agent is to bind to the RMI Naming service at initialization time.
Parameters:
theAgentToBindToRmiFlag - Use true if the agent is to bind to RMI Naming; false (default) otherwise.

isAgentToBindToRmi

public boolean isAgentToBindToRmi()
                           throws AbleException
Description copied from interface: AblePlatformAgent
Determines whether the agent is to bind to RMI Naming at initialization time.
Specified by:
isAgentToBindToRmi in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
true if the agent is to bind to RMI Naming; false otherwise.
Throws:
java.rmi.RemoteException - On any RMI error.

setAgentMovable

public void setAgentMovable(boolean theAgentMovableFlag)
Sets whether the agent is movable from one agent pool to another.
Parameters:
theAgentMovableFlag - Use true if the agent is movable; false otherwise.

isAgentMovable

public boolean isAgentMovable()
                       throws AbleException
Description copied from interface: AblePlatformAgent
Determines whether the agent is movable from one agent pool to another.
Specified by:
isAgentMovable in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
true if the agent is movable; false otherwise.
Throws:
java.rmi.RemoteException - On any RMI error.

addJasAgentAttribute

public void addJasAgentAttribute(java.lang.String theKey,
                                 java.lang.Object theAttribute)
Adds a named attribute to the agent's set of attributes.
Parameters:
theKey - the name of the attribute.
theAttribute - the attribute to add to the set.

removeJasAgentAttribute

public void removeJasAgentAttribute(java.lang.String theKey)
Removes a named attribute from the agent's set of attributes.
Parameters:
theKey - the name of the attribute to remove.

getJasAgentAttributes

public java.util.Hashtable getJasAgentAttributes()
                                          throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's JAS attributes.
Specified by:
getJasAgentAttributes in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
A cloned collection of the agent's attributes, both those built-in by Able, and those added by the user.
Throws:
java.rmi.RemoteException - On any RMI error.

getJasAgentName

public java.lang.String getJasAgentName()
                                 throws AbleException
Description copied from interface: AblePlatformAgent
Gets the agent's globally unique ID (GUID or AgentName) in text form.
Specified by:
getJasAgentName in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Returns:
A toString() version of the agent's unique AgentName.
Throws:
java.rmi.RemoteException - On any RMI error.

getAgentInboxes

public java.util.Vector getAgentInboxes()

addAgentInbox

public void addAgentInbox(java.lang.Object[] theProtocol)

removeAgentInbox

public void removeAgentInbox(java.lang.Object[] theProtocol)

removeAgentInboxes

public void removeAgentInboxes()

setPrincipal

public void setPrincipal(java.lang.String thePrincipal)

getPrincipal

public java.lang.String getPrincipal()

preInit

public void preInit()
             throws AbleException
Description copied from interface: AblePlatformAgent
Pre-initializes the agent immediately after creation, causing the agent to find the Service Root, extract references to various services, obtain a unique AgentName from the Agent Naming Service, and, when security is on, a VerifiableAgentName (VAN). Typically, in a secure environment, an agent needs a VerifiableAgentName before any other operations can be performed on it, including initialization. Once an agent has an AgentName (through any means), calls to this method are ignored.
Specified by:
preInit in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Throws:
java.rmi.RemoteException - On any remote error.

initializeAgent

public void initializeAgent(AbleSecureKey theSecureKey)
                     throws AbleException,
                            javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformAgent
Initializes and configures the agent. Typically, the agent will create an AgentDescription, fill the description with useful information such as Locators, and register the description with the Agent Directory Service.
Specified by:
initializeAgent in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
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:
java.rmi.RemoteException - On any remote error.
javax.agent.service.naming.NamingException - On any naming error.

initializeAgent

public void initializeAgent(java.lang.Object theInitArg,
                            AbleSecureKey theSecureKey)
                     throws AbleException,
                            javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformAgent
Initializes and configures the agent using the specified parameter, which is typically an Object[], but may be anything that the agent is coded to expect. Typically, the agent will create an AgentDescription, fill the description with useful information such as Locators, and register the description with the Agent Directory Service.
Specified by:
initializeAgent in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Parameters:
theInitArg - Argument to the initialization method.

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:
java.rmi.RemoteException - On any remote error.
javax.agent.service.naming.NamingException - On any naming error.

quitAgent

public void quitAgent(AbleSecureKey theSecureKey)
               throws AbleException,
                      javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformAgent
Quits the agent, which typically quits all contained beans and agents.
Specified by:
quitAgent in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
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:
java.rmi.RemoteException - On any remote error.
javax.agent.service.naming.NamingException - On any naming error.

suspendAgent

public void suspendAgent(AbleSecureKey theSecureKey)
                  throws AbleException,
                         javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformAgent
Temporarily suspends all asynchronous threads of control, typically including those in any contained beans and agents.
Specified by:
suspendAgent in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
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:
java.rmi.RemoteException - On any remote error.
javax.agent.service.naming.NamingException - On any naming error.

resumeAgent

public void resumeAgent(AbleSecureKey theSecureKey)
                 throws AbleException,
                        javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformAgent
Resumes all asynchronous threads of control, typically including those in any contained beans and agents.
Specified by:
resumeAgent in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
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:
java.rmi.RemoteException - On any remote error.
javax.agent.service.naming.NamingException - On any naming error.

resetAgent

public void resetAgent(AbleSecureKey theSecureKey)
                throws AbleException,
                       javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformAgent
Resets the agent to its "initialized" state.
Specified by:
resetAgent in interface AblePlatformAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
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:
java.rmi.RemoteException - On any remote error.
javax.agent.service.naming.NamingException - On any naming error.

receiveMessage

public void receiveMessage(javax.agent.TransportMessage theTransportMessage)
Receives and handles a message from the JAS Message Transport Service.

In this implementation, the process(Object) method is called to process the received message.

Specified by:
receiveMessage in interface javax.agent.service.transport.MessageListener
Parameters:
theTransportMessage - A message from the Message Transport Service.


init

public void init()
          throws AbleException
Initializes and configures the bean, but only if security is off; when security is on, calls to this method are ignored -- the method initializeAgent(AbleSecureKey) must be used instead.
Specified by:
init in interface AbleRemoteBean
Overrides:
init in class AbleRemoteDefaultAgent
Throws:
AbleException - On any error.

init

public void init(java.lang.Object theArg)
          throws AbleException
Initializes and configures the bean, using the specified Object, but only if security is off; when security is on, calls to this method are ignored -- the method initializeAgent(Object,AbleSecureKey) must be used instead.

In this implementation, the argument parameter is not used, but is passed on up to the super classes.

Specified by:
init in interface AbleRemoteBean
Overrides:
init in class AbleRemoteDefaultAgent
Parameters:
theArg - An Object used to initialize the bean.

Throws:
AbleException - On any error.

reset

public void reset()
           throws AbleException
Resets the bean, but only if security is off; when security is on, calls to this method are ignored -- the method resetAgent(AbleSecureKey) must be used instead.
Specified by:
reset in interface AbleRemoteBean
Overrides:
reset in class AbleDefaultAgent
Throws:
AbleException - On any error.

process

public java.lang.Object process(java.lang.Object theArg)
                         throws AbleException
Performs the main, standard processing function of this platform agent, using the argument.

Agents derived from this default platform agent must override this method in order to do anything useful. The default receiveMessage(TransportMessage) calls this method when a message is received by the Message Transport Service, but this method does nothing.

Specified by:
process in interface AbleRemoteBean
Overrides:
process in class AbleObject
Parameters:
theArg - The Object should be a JAS TransportMessage as received by the receiveMessage() method.

Returns:
the results of the process(Object) computation. In this default implementation, theArg is always returned.
Throws:
AbleException - In any error situation.

quitAll

public void quitAll()
             throws AbleException
Stops all of the bean's asynchronous threads of control, but only if security is off; when security is on, calls to this method are ignored -- the method quitAgent(AbleSecureKey) must be used instead.
Specified by:
quitAll in interface AbleRemoteBean
Overrides:
quitAll in class AbleDefaultAgent
See Also:
AbleDefaultAgent.quitEnabledEventProcessing()

suspendAll

public void suspendAll()
                throws AbleException
Suspends all of the bean's asynchronous threads of control, but only if security is off; when security is on, calls to this method are ignored -- the method suspendAgent(AbleSecureKey) must be used instead.
Specified by:
suspendAll in interface AbleRemoteBean
Overrides:
suspendAll in class AbleDefaultAgent
Following copied from interface: com.ibm.able.AbleRemoteBean
Throws:
java.rmi.RemoteException - If an error occurs.

resumeAll

public void resumeAll()
               throws AbleException
Resumes all of the bean's asynchronous threads of control, but only if security is off; when security is on, calls to this method are ignored -- the method resumeAgent(AbleSecureKey) must be used instead.
Specified by:
resumeAll in interface AbleRemoteBean
Overrides:
resumeAll in class AbleDefaultAgent
Following copied from interface: com.ibm.able.AbleRemoteBean
Throws:
java.rmi.RemoteException - If an error occurs.

_init

protected void _init()
              throws AbleException
Performs the actual work of initialization. In particular,
Throws:
AbleException - In any error situation.

_init

protected void _init(java.lang.Object theArg)
              throws AbleException
Does all the initial Java Agent Services (JAS) housekeeping in a manner identical to _init(), but the specified argument is passed to the super class for handling.
Throws:
AbleException - In any error situation.

_reset

protected void _reset()
               throws AbleException
Performs the actual work of resetting the agent; this method must be used
  1. only when security is off, or
  2. only when security is on AND an Able SecureKey has already been verified.
This method is called by

This method can be overridden, but must not be exposed to the public.

Throws:
AbleException - In any error situation.

_quitAll

protected void _quitAll()
Performs the actual work of destroying this agent; this method must be used
  1. only when security is off, or
  2. only when security is on AND an Able SecureKey has already been verified.
This method is called by

This method can be overridden, but must not be exposed to the public.

As needed:

and so on.

_suspendAll

protected void _suspendAll()
                    throws AbleException
Performs the actual work of suspending this agent; this method must be used
  1. only when security is off, or
  2. only when security is on AND an Able SecureKey has already been verified.
This method is called by

This method can be overridden, but must not be exposed to the public.

Throws:
AbleException - In any error situation.

_resumeAll

protected void _resumeAll()
                   throws AbleException
Performs the actual work of resuming this agent; this method must be used
  1. only when security is off, or
  2. only when security is on AND an Able SecureKey has already been verified.
This method is called by

This method can be overridden, but must not be exposed to the public.

Throws:
AbleException - In any error situation.

getAndValidateServiceRoot

protected void getAndValidateServiceRoot()
                                  throws AbleException
Gets addressability to the JAS Service Root, and makes sure the Agent Naming Service, the Agent Directory Service, and the Message Transport System are all available.
Throws:
AbleException - In any error situation.

getAndSetAgentNames

protected void getAndSetAgentNames()
                            throws AbleException
Gets this agent's Globally Unique ID (GUID or AgentName) from the Agent Naming Service and saves it away in the data member myJasAgentName; additionally, if security is on, a verifiable agent name is obtained and saved in the data member myVerifiableAgentName, and the data members myTrustLevel, myPrincipal, and mySecSppt are also set.
Throws:
AbleException - In any error situation.

getAndSetAgentDescription

protected void getAndSetAgentDescription()
                                  throws AbleException
Calls getNewAgentDescription() to get a new, empty Agent Description and then
Throws:
AbleException - In any error situation.

getNewAgentDescription

protected void getNewAgentDescription()
                               throws AbleException
Gets a new, empty Agent Description and saves it away in the data member myJasAgentDescription.
Throws:
AbleException - In any error situation.

loadAgentDescriptionWithAgentName

protected void loadAgentDescriptionWithAgentName()
                                          throws AbleException
Loads this agent's description with the agent's Globally Unique ID (GUID) or AgentName as contained in the data member myJasAgentName.
Throws:
AbleException - In any error situation.

loadAgentDescriptionWithPublicKey

protected void loadAgentDescriptionWithPublicKey()
Loads this agent's description with the agent's public key, but only if security is on.

loadAgentDescriptionWithAbleAttributes

protected void loadAgentDescriptionWithAbleAttributes()
                                               throws AbleException
Loads this agent's description with the built-in Able attributes, which must be set before initialization time.

Note that the agent's built-in attributes, those data members named with the pattern agentXxxx, can be set programatically, for example, setAgentVersion("1.2.3") or through a graphical customizer (not provided).

Attributes set include

Throws:
AbleException - In any error situation.

loadAgentDescriptionWithUserAttributes

protected void loadAgentDescriptionWithUserAttributes()
                                               throws AbleException
Loads this agent's description with those user-defined attributes that have been placed into the data member myJasAgentAttributes.
Throws:
AbleException - In any error situation.

getAndSetTransportServices

protected void getAndSetTransportServices()
                                   throws AbleException
Gets all available Message Transport Services from the Message Transport System, selects the first one, and saves it away in the data member myJasMessageTransportService.
Throws:
AbleException - In any error situation.

loadAgentDescriptionWithBaseLocators

protected void loadAgentDescriptionWithBaseLocators()
                                             throws AbleException
Loads this agent's description with Locators created from the selected Message Transport Service.

At least one Locator, perhaps bound to this agent's receiveMessage(TransportMessage) method is created. Note, however, that any number of Locators can be created, and they can be bound to callback methods other than receiveMessage().

The number of Locators (inboxes) and the methods to which they are bound is customizable through the data member myAgentInboxes. If myAgentInboxes is empty, then the default Locator is created.

Throws:
AbleException - In any error situation.

createLocatorAndBindToMethod

protected javax.agent.Locator createLocatorAndBindToMethod(java.lang.String theProtocol,
                                                           AbleUserDefinedFunction theUserDefinedFunction)
                                                    throws AbleException
This is a helper method for loadAgentDescriptionWithBaseLocators().
Parameters:
theProtocol - The protocol is simply passed to an AbleJasMessageListener, and set as an identifiable property in the Locator.

theUserDefinedFunction - The method that is to receive the callback when a message arrives through the created Locator.

Returns:
A Locator of the specified protocol and whose callback method is bound to the specified User-Defined Function.
Throws:
AbleException - In any error situation.

loadAgentDescriptionWithAbleLocator

protected void loadAgentDescriptionWithAbleLocator()
                                            throws AbleException
Loads this agent's description with a special Able Locator, found in the data member myJasAbleLocator, which is a locator that contains an RMI reference to this agent, and which can be used to call those public, "remotable" methods found in this agent.
Throws:
AbleException - In any error situation.

maybeRegisterWithAgentDirectoryService

protected void maybeRegisterWithAgentDirectoryService(boolean theRegisterFlag)
                                               throws AbleException
Registers this agent with the Agent Directory Service, depending on the value of the specified flag.

This method can also be used to update the agent's already registered agent description.

Parameters:
theRegisterFlag - If true, the agent will register with the Directory Service. Otherwise, nothing happens.

Throws:
AbleException - In any error situation.

maybeDeregisterWithAgentDirectoryService

protected void maybeDeregisterWithAgentDirectoryService()
                                                 throws AbleException
Deregisters this agent with the Agent Directory Service, depending on whether the agent is registered.
Throws:
AbleException - In any error situation.

updateDescriptionWithAgentDirectoryService

protected void updateDescriptionWithAgentDirectoryService()
                                                   throws AbleException
Updates this agent's description with the Agent Directory Service.
Throws:
AbleException - In any error situation.

maybeRebindToRmi

protected void maybeRebindToRmi(boolean theBindToRmiFlag)
                         throws AbleException
(Re)binds this agent to RMI Naming lookup service, depending on the value of the specified flag.
Parameters:
theBindToRmiFlag - If true, the agent will rebind itself to RMI Naming. Otherwise, nothing happens.

Throws:
AbleException - In any error situation.

maybeUnbindFromRmi

protected void maybeUnbindFromRmi()
                           throws AbleException
Unbinds this agent from RMI Naming, depending on whether it has been bound to RMI.
Throws:
AbleException - In any error situation.

lookUpAgent

protected javax.agent.service.directory.AgentDescription[] lookUpAgent(java.lang.String theSearchAttribute,
                                                                       java.lang.Object theSearchValue)
                                                                throws AbleException
Finds all agents registered with the Agent Directory whose agent description contains the specified attribute and value.
Parameters:
theSearchAttribute - The name of the attribute in the agent description to search.

theSearchValue - The value that the specified attribute must match. The equals() method is used.

Returns:
An array of agent descriptions that contain the specified attribute and value.
Throws:
AbleException - In any error situation.

lookUpAgent

protected javax.agent.service.directory.AgentDescription[] lookUpAgent(java.util.Hashtable theSearchAttributesAndValues)
                                                                throws AbleException
Finds all agents registered with the Agent Directory whose agent description contains the specified attributes and values.
Parameters:
theSearchAttributesAndValues - A set of attributes and associated values for which to search.

Returns:
An array of agent descriptions that contain the specified attributes and associated values.
Throws:
AbleException - In any error situation.

logException

protected void logException(java.lang.String theMethodName,
                            java.lang.Exception theException)
Logs an exception. Goes to both MessageLog and TraceLog.
Parameters:
theException - The exception to log.


broadcastTransportMessage

protected void broadcastTransportMessage(java.util.Vector theDestinations,
                                         java.lang.Object theMessageToSend)
                                  throws AbleException
Sends a message to a list of agents. This agent's default Locator is used as the origination Locator.
Parameters:
theDestinations - A vector of vectors: ( (Locator AgentName) (Locator AgentName) ... )

theMessageToSend - An Object containing the contents of the message to send.

Throws:
AbleException - In any error situation.
See Also:
sendTransportMessage(Locator, Locator, AgentName, Object)

sendTransportMessage

protected void sendTransportMessage(javax.agent.Locator theDestinationLocator,
                                    javax.agent.AgentName theDestinationAgentName,
                                    java.lang.Object theMessageToSend)
                             throws AbleException
Sends a message to the specified agent. This agent's default Locator is used as the origination Locator.
Parameters:
theDestinationLocator - The Locator of the destination agent.

theDestinationAgentName - The globally unique ID (Agent Name) of the destination agent.

theMessageToSend - An Object containing the contents of the message to send.

Throws:
AbleException - In any error situation.
See Also:
sendTransportMessage(Locator, Locator, AgentName, Object)

sendTransportMessage

protected void sendTransportMessage(javax.agent.Locator theOriginationLocator,
                                    javax.agent.Locator theDestinationLocator,
                                    javax.agent.AgentName theDestinationAgentName,
                                    java.lang.Object theMessageToSend)
                             throws AbleException
Sends an ACL message to the specified agent. Any one of this agent's Locators can be used as the origination Locator, and it is up to the caller to decide which.
Parameters:
theOriginationLocator - One of my own Locators, selected by the caller.

theDestinationLocator - The Locator of the destination agent.

theDestinationAgentName - The globally unique ID (Agent Name) of the destination agent.

theMessageToSend - An Object containing the contents of the message to send.

The message to send can be any of:

  • An AclMessage, all filled-out and ready-to-go. This means that the performative, sender, receiver(s), and content are already set in the message. You may use the AclMessageUtility class to help create the AclMessage.
  • A String, which will be encapsulated as an AcrString in an inform AclMessage.
  • Any other Object, which will be encapsulated as an AcrObject in an inform AclMessage.

Throws:
AbleException - In any error situation.

getTransportMessageContent

protected java.lang.Object getTransportMessageContent(javax.agent.TransportMessage theTransportMessage)
                                               throws AbleException
Extracts and returns the content of the specified transport message. The transport message must contain a properly formed ACL message. If it does not, null is returned. It should also go without saying that the expected content must be fully serializable. If it is not, it certainly won't show up here.

Important!

This method assumes that the content of the transport message's inner ACL message is wrapped in either an AcrObject or an AcrString object. If the transport message was sent with this class's implementation of the sendTransportMessage() method, that will indeed be the case. If the transport message was sent from some non-Able agent or from an overridden sendTransportMessage() method, this assumption may be false, and this method may return an AcrNode that you will have to decode yourself.

Parameters:
theTransportMessage - The message from which the ACL message and its inner content is to be extracted.

Returns:
The contents of the transport message's ACL message. In certain circumstances, null may be returned.
Throws:
AbleException - In any error situation.

getTransportMessageContent2

protected java.lang.Object getTransportMessageContent2(javax.agent.TransportMessage theTransportMessage)
                                                throws AbleException
Extracts and returns the content of the specified transport message. The transport message must contain a properly formed ACL message. If it does not, null is returned. It should also go without saying that the expected content must be fully serializable. If it is not, it certainly won't show up here.

Important!

This method assumes that the content of the transport message's inner ACL message is wrapped in either an AcrObject or an AcrString object. If the transport message was sent with this class's implementation of the sendTransportMessage() method, that will indeed be the case. If the transport message was sent from some non-Able agent or from an overridden sendTransportMessage() method, this assumption may be false, and this method may return an AcrNode that you will have to decode yourself.

Parameters:
theTransportMessage - The message from which the ACL message and its inner content is to be extracted.

Returns:
The contents of the transport message's ACL message. In certain circumstances, null may be returned.
Throws:
AbleException - In any error situation.

setRequestKey

public void setRequestKey(AbleSecureKey theRequestKey)
Sets the AbleSecureKey this agent will use to make a VAN request to the VerifiableAgentNamingService. Note: This method is intended for use by the platform support code when security is active.

main

public static void main(java.lang.String[] args)
                 throws AbleException

toString

public java.lang.String toString()
Gets 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()
Gets the copyright statement of this class.
Returns:
this class's copyright statement.

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

(C) Copyright IBM Corporation 1999, 2003