Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  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:

- Some entity causes the Agent Lifecycle Service to create an instance of the agent in an agent pool. The agent's constructor may perform some self customization and configuration.
- Immediately after creating the agent, Agent Lifecycle Service calls the agent's `preInit()` method, which causes the agent to look up several platform Services and obtain a unique AgentName for itself from the Agent Naming Service.

  Note that if the agent is created by something other than the Agent Lifecycle Service, `preInit()` must be called immediately after creation, but if security is on, `setPrincipal(String)` must be called first.

- Some entity may perform further customization of the agent by calling the agent's remote methods.
- Some entity, either using Agent Lifecycle Service or through direct means, initializes the agent by calling the agent's `initializeAgent(AbleSecureKey)` method. This causes the agent to obtain an AgentDescription, load it up with the attributes and Locators it wants to advertise, and registers the description with the Agent Directory Service. The agent may also, if configured to do so, bind with RMI.
- At this point the agent is active and performing its assigned task.
- The agent may be suspended, resumed, or otherwise controlled, either through the Agent Lifecycle Service or by direct means. If security is on, only entities with the proper authority may perform these actions.
- The agent may be "killed" by calling its `quitAgent(AbleSecureKey)` method, at which time the agent will free its resources.

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 AgentLoggingService` | `myAgentLoggingService` The AgentLoggingService for this agent.
`protected java.util.Map` | `myCapabilities` The capabilities of this agent.
`protected java.util.Vector` | `myCapabilityOrder` The order that the capabilities are displayed in might be important.
`protected java.util.Map` | `myCustomCapabilityAutonomyLevels` The autonomy levels of the custom capability.
`protected java.util.Map` | `myHighCapabilityAutonomyLevels` The HIGH pre-defined autonomy levels for the capabilities of 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.util.Map` | `myLowCapabilityAutonomyLevels` The LOW pre-defined autonomy levels for the capabilities of this agent.
`protected java.util.Map` | `myMediumCapabilityAutonomyLevels` Yhe MEDIUM pre-defined autonomy levels for the capabilities of this agent.
`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, properties, 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` | `authenticateAndAuthorizeCaller(AbleAgentSituationReport theAnsweredAgentSituationReport, AbleSecureKey theSecureKey)` This default implementation, called by `handleAnsweredRequest(com.ibm.able.platform.AbleAgentSituationReport, com.ibm.able.platform.AbleSecureKey)` in order to determine whether the answerer of the request is authentic and authorized to answer the request, does nothing.
`protected void` | `authorizeCapabilityChangeRequest(AbleSecureKey theSecureKey)` This default implementation, called by those methods that change an agent's AutonomyLevel or the autonomy levels of its AgentCapabilities to determine whether the caller of the method is authorized to perform the requested change, performs a simple check: all the callers in the chain must have a trust level that is greater than or equal to the trust level of this agent in order for the operation to proceed.
`protected void` | `broadcastTransportMessage(java.util.Vector theDestinations, java.lang.Object theMessageToSend)` Sends a message to a list of agents.
`protected AbleAgentSituationReport` | `createAgentSituationReport(java.io.Serializable theIdentifier, AbleAgentCapability theCapability, AbleAgentSituation theSituation, AbleMessageContainer theSuggestedResponse, AbleMessageContainer theResponseTaken, AbleMessageContainer theResultsSummary, boolean theProblemState)` Helper method used to create an AgentSituationReport for this agent.
`protected javax.agent.Locator` | `createLocatorAndBindToMethod(java.lang.String theProtocol, AbleUserDefinedFunction theUserDefinedFunction)` This is a helper method for `loadAgentDescriptionWithBaseLocators()`.
`java.io.Serializable` | `getAboutDataBean()` Gets the data bean from which a console can obtain the information that is displayed on this agent's 'About' panel.
`int` | `getAgentAutonomyLevel()` Gets the agent's autonomy level.
`javax.agent.service.directory.AgentDescription` | `getAgentDescription()` Retrieves the agent's AgentDescription.
`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.
`protected void` | `getAgentLoggingService(java.lang.String theMsgId, java.lang.Object[] theSubstitutionText, java.lang.String theMethod)` Sets `myAgentLoggingService` to reference the AgentLoggingService.
`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.Map` | `getCapabilities()` Gets a Map of this agent's AgentCapability objects.
`AbleAgentCapability` | `getCapability(java.lang.Object theCapabilityIdentifier)` Gets a specific AgentCapability of this agent.
`java.util.Map` | `getCapabilityAutonomyLevels()` Gets, based on the agent's current AutonomyLevel setting, the appropriate set of capability autonomy levels.
`java.util.Vector` | `getCapabilityOrder()` The order of an agent's AgentCapabilities may be important.
`java.util.Map[]` | `getCapabilityPresets()` Returns an array of four Maps.
`AbleMessageContainer` | `getCapabilitySummaryByAgentAutonomyLevel(int theAgentAutonomyLevel)` Gets an NLS text summary of the agent's capabilities based on the specified agent AutonomyLevel.
`AbleMessageContainer` | `getCapabilitySummaryByCapabilityAutonomyLevels(java.util.Map theCapabilityAutonomyLevels)` Gets an NLS text summary of the agent's capabilities based on the specified capability autonomy levels.
`java.io.Serializable` | `getCustomizerDataBean()` Gets the data bean from which a console can obtain this agent's customizable data so that the data can be displayed on this agent's 'Customize' panel.
`java.lang.String[]` | `getCustomizerInfo()` Gets information about this agent's 'Customize' and 'About' GUIs.
`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`.
`javax.agent.AgentName` | `getPlatformAgentName()` Gets the agent's AgentName object.
`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` | `handleAnsweredRequest(AbleAgentSituationReport theAgentSituationReport, AbleSecureKey theSecureKey)` This method is called to answer a request that this agent had previously logged to the AgentLoggingService.
`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.
`protected void` | `initAgentCapabilities(java.util.Map[] theCapabilities)` Initializes the agent with the specified AgentCapabilities.
`protected void` | `initCommonCode(java.lang.Object theArg)` Initializes the agent with the specified argument.
`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()` Specifies whether the agent is movable from one agent pool to another.
`boolean` | `isAgentToAutoRegister()` Specifies whether the agent is to register with an RMI Registry at initialization time.
`boolean` | `isAgentToBindToRmi()` Specifies 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` | `logAgentSituationReport(AbleAgentSituationReport theAgentSituationReport)` This method handles the details of logging an AgentSituationReport to the AgentLoggingService for this agent.
`protected void` | `logException(java.lang.String theMethodName, java.lang.Exception theException)` Logs an exception.
`protected void` | `logHistory(AbleMessageContainer theDescription, AbleMessageContainer theAction, AbleMessageContainer theSummary)` Helper method used to log a History log.
`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 AbleMessageContainer` | `makeCapabilityAutonomyLevelsSummary(java.util.Map theCapabilityAutonomyLevels)` Returns an AbleMessage Container that describes the overall agent autonomy summary if the agent's capability autonomy levels are set to `theCapabilityAutonomyLevels`.
`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).
`void` | `preInit(java.lang.String theAgentNameUniqueID)` This version of preInit should be called when this agent is being restarted from persistence.
`java.lang.Object` | `process(java.lang.Object theArg)` Performs the main, standard processing function of this platform agent, using the argument.
`protected void` | `processAnsweredRequest(AbleAgentSituationReport theAnsweredAgentSituationReport, AbleSecureKey theSecureKey)` This default implementation of `processAnsweredRequest` does nothing.
`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()`
`protected void` | `removeAgentSituationReports(java.util.Vector theAgentSituationReportsToRemove)` This method handles the details of removing one of this agent's AgentSituationReports.
`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.
`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` | `setAgentNameUniqueID(java.lang.String theAgentNameUniqueID)`
`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` | `setCapabilityAutonomyLevel(java.lang.Object theCapabilityIdentifier, int theAutonomyLevel, AbleSecureKey theSecureKey)` Sets the autonomy level of the specified AgentCapability.
`void` | `setCapabilityAutonomyLevels(java.util.Map theCapabilityAutonomyLevels, AbleSecureKey theSecureKey)` Updates the autonomy level of each of this agent's capabilities according to the autonomy levels in the specified Map.
`void` | `setCustomizerDataBean(java.io.Serializable theDataBean, AbleSecureKey theSecureKey)` Sets the data bean from which this agent can retrieve it's updated customizable data.
`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` | `setRestartedFromPersistence(boolean isRestartedFromPersistence)`
`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` | `updateAgentSituationReport(AbleAgentSituationReport theOldAgentSituationReport, AbleAgentSituationReport theNewAgentSituationReport)` This method handles the details of updating one of this agent's AgentSituationReports.
`protected void` | `updateDescriptionWithAgentDirectoryService()` Updates this agent's description with the Agent Directory Service.
`protected void` | `validateAnsweredRequest(AbleAgentSituationReport theAnsweredAgentSituationReport)` This default implementation, called by `handleAnsweredRequest(com.ibm.able.platform.AbleAgentSituationReport, com.ibm.able.platform.AbleSecureKey)` in order to determine whether the specified request is still valid, does nothing.
`protected void` | `verifyCapabilities()` All subclasses using AgentCapabilities must define their own capabilities and each capability's autonomy level.
`protected void` | `verifyKey(AbleSecureKey theSecureKey, java.lang.String theMethod)` Helper method used to verify a secure key.

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, getEventConnections, getNumEpochs, getProcessList, getUserDefinedFunction, getUserDefinedFunctions, handleAbleEvent, initAllBeans, invokeUserDefinedFunction, isActiveDataSource, process, propertyChange, quitEnabledEventProcessing, removeAllBeans, removeAllConnections, removeAllEventConnections, removeBean, removeBean, removeBeans, removeEventConnection, removeUserDefinedFunction, resetAllBeans, 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, getInputBufferAsString, getInputBufferAsStringArray, getInputBufferContents, getLogger, getName, getOutputBuffer, getOutputBuffer, getOutputBufferAsString, getOutputBufferAsStringArray, getOutputBufferContents, getParent, getProperties, getProperty, getPropertyChangeListeners, getPropertyConnectionManager, getSleepTime, getSourceBufferConnections, getState, getTraceLogger, hasInputBuffer, hasOutputBuffer, isAbleEventPostingEnabled, isAbleEventProcessingEnabled, isChanged, isConnectable, isDataFlowEnabled, isTimerEventProcessingEnabled, notifyAbleEventListeners, processAbleEvent, processBufferConnections, processNoEventProcessingEnabledSituation, processTimerEvent, removeAbleEventListener, removeAllAbleEventListeners, removeAllBufferConnections, removeAllPropertyConnections, removeDestBufferConnection, removeProperty, removePropertyChangeListener, removePropertyConnection, removeSourceBufferConnection, removeStateChangeListener, restartEnabledEventProcessing, restoreFromFile, restoreFromFile, restoreFromSerializedFile, restoreFromStream, resumeEnabledEventProcessing, saveToFile, saveToFile, setAbleEventProcessingEnabled, setChanged, setComment, setFileName, setInputBuffer, setInputBuffer, setLogger, setName, setOutputBuffer, setOutputBuffer, setParent, setProperties, setProperty, 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.platform.AblePlatformAgent
`getComment`

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, getProperties, getProperty, getState, process, removeProperty, setProperties, setProperty`

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, getProperties, getProperty, getState, getTraceLogger, isChanged, removeProperty, setChanged, setComment, setLogger, setName, setParent, setProperties, setProperty, setState, setTraceLogger`

Methods inherited from interface com.ibm.able.AbleDataBufferManager
`addDestBufferConnection, addSourceBufferConnection, getDestBufferConnections, getInputBuffer, getInputBuffer, getInputBufferAsString, getInputBufferAsStringArray, getInputBufferContents, getOutputBuffer, getOutputBuffer, getOutputBufferAsString, 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, getPropertyChangeListeners, 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!

### myAgentLoggingService

    protected AgentLoggingService myAgentLoggingService

  The AgentLoggingService for this agent. This member is set lazily; that is, a reference to the AgentLoggingService is not obtained until it is needed. Methods that need the agent logging service must test this member for null, and then call `getAgentLoggingService` if necessary.

### myCapabilities

    protected java.util.Map myCapabilities

  The capabilities of this agent. Each entry of the Map is:

       Key:   ((Object)              aCapabilityIdentifier)
       Value: ((AbleAgentCapability) anAgentCapability    )

  This is where all of the capabilities of an agent are defined. It is the agent's responsibility to set its capabilities along with the three capability autonomy level Maps: highCapabilityAutonomyLevels, mediumCapabilityAutonomyLevels and lowCapabilityAutonomyLevels, and the capabilityOrder when the agent is instantiated. The agent must then call its `verifyCapabilities()` method to verify that its capabilities and autonomy levels are valid, and the order vector contains appropriate identifiers. If these are not set correctly, the agent when fail when initialized.

  The only other way to set the capabilities is by passing an AbleAgentCapability[] as the init arguments. Using the init arguments overwrites any capability and autonomy levels that might have already been set.

### myCapabilityOrder

    protected java.util.Vector myCapabilityOrder

  The order that the capabilities are displayed in might be important. If so, this Vector should be filled with the identifiers of the Capabilities of this agent, in the desired order.

### myHighCapabilityAutonomyLevels

    protected java.util.Map myHighCapabilityAutonomyLevels

  The HIGH pre-defined autonomy levels for the capabilities of this agent.

  Each entry of the Map is:

       Key:   ((Object)  aCapabilityIdentifier)
       Value: ((Integer) anAutonomyLevel      )

  See Also:
    `myCapabilities`

### myMediumCapabilityAutonomyLevels

    protected java.util.Map myMediumCapabilityAutonomyLevels

  Yhe MEDIUM pre-defined autonomy levels for the capabilities of this agent.

  Each entry of the Map is:

       Key:   ((Object)  aCapabilityIdentifier)
       Value: ((Integer) anAutonomyLevel      )

  See Also:
    `myCapabilities`

### myLowCapabilityAutonomyLevels

    protected java.util.Map myLowCapabilityAutonomyLevels

  The LOW pre-defined autonomy levels for the capabilities of this agent.

  Each entry of the Map is:

       Key:   ((Object)  aCapabilityIdentifier)
       Value: ((Integer) anAutonomyLevel      )

  See Also:
    `myCapabilities`

### myCustomCapabilityAutonomyLevels

    protected java.util.Map myCustomCapabilityAutonomyLevels

  The autonomy levels of the custom capability. The custom capabilities are set whenever the capabilities of this agent are set, and they do not match one of the three defined autonomy levels: HIGH, MEDIUM, or LOW autonomy.

  Each entry of the Map is:

       Key:   ((Object)  aCapabilityIdentifier)
       Value: ((Integer) anAutonomyLevel      )

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`
  Returns:
    An autonomy level as defined in `AblePlatform`.
  Throws:
    `AbleException`

### setAgentAutonomyLevel

    public void setAgentAutonomyLevel(int theAgentAutonomyLevel,
                                      AbleSecureKey theSecureKey)
                               throws AbleException

  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.

### 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`
  Returns:
    The date and time the agent's description was last updated.
  Throws:
    `AbleException`

### 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`
  Returns:
    The agent's real time status.
  Throws:
    `AbleException`

### 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`
  Returns:
    The agent's current summary text.
  Throws:
    `AbleException`

### 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`
  Returns:
    The agent's type description.
  Throws:
    `AbleException`

### 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`
  Returns:
    The agent's vendor.
  Throws:
    `AbleException`

### 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`
  Returns:
    The agent's version.
  Throws:
    `AbleException`

### 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`
  Specifies whether the agent is to register with an RMI Registry at initialization time.

  Specified by:
    `isAgentToAutoRegister` in interface `AblePlatformAgent`
  Returns:
    true if the agent is to register with an RMI Registry; false otherwise.
  Throws:
    `AbleException`

### 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`
  Specifies whether the agent is to bind to RMI Naming at initialization time.

  Specified by:
    `isAgentToBindToRmi` in interface `AblePlatformAgent`
  Returns:
    true if the agent is to bind to RMI Naming; false otherwise.
  Throws:
    `AbleException`

### 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`
  Specifies whether the agent is movable from one agent pool to another.

  Specified by:
    `isAgentMovable` in interface `AblePlatformAgent`
  Returns:
    true if the agent is movable; false otherwise.
  Throws:
    `AbleException`

### 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`
  Returns:
    A cloned collection of the agent's attributes, both those built-in by ABLE, and those added by the user.
  Throws:
    `AbleException`

### 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`
  Returns:
    A `toString()` version of the agent's unique AgentName.
  Throws:
    `AbleException`

### getPlatformAgentName

    public javax.agent.AgentName getPlatformAgentName()
                                               throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets the agent's AgentName object.

  Specified by:
    `getPlatformAgentName` in interface `AblePlatformAgent`
  Returns:
    The agent's AgentName object.
  Throws:
    `AbleException`

### 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`
  Throws:
    `AbleException`

### preInit

    public void preInit(java.lang.String theAgentNameUniqueID)
                 throws AbleException

  Description copied from interface: `AblePlatformAgent`
  This version of preInit should be called when this agent is being restarted from persistence. This method will first call preInit() which will use `theAgentNameUniqueID` when requesting the AgentName for this agent. This method will then also remove all previously persisted AgentDescriptions from the Directory Service since this agent is being restarted from persistence.

  Specified by:
    `preInit` in interface `AblePlatformAgent`
  Parameters:
    `theAgentNameUniqueID` - When an agent is being restarted from persistence, it will want to have an AgentName that matches the one it had in it's previous life. This way the recreated agent can still get at logs and it's agent description. So instead of having the NamingService create a new unique identifier for the AgentName of this recreated agent, this old uniqueID will be used.
  Throws:
    `AbleException`

### setAgentNameUniqueID

    public void setAgentNameUniqueID(java.lang.String theAgentNameUniqueID)
                              throws AbleException

  Throws:
    `AbleException`

### setRestartedFromPersistence

    public void setRestartedFromPersistence(boolean isRestartedFromPersistence)
                                     throws AbleException

  Throws:
    `AbleException`

### 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`
  Parameters:
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `javax.agent.service.naming.NamingException` - On any naming error.
    `AbleException`

### 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`
  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:
    `javax.agent.service.naming.NamingException` - On any naming error.
    `AbleException`

### 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`
  Parameters:
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `javax.agent.service.naming.NamingException` - On any naming error.
    `AbleException`

### 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`
  Parameters:
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `javax.agent.service.naming.NamingException` - On any naming error.
    `AbleException`

### 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`
  Parameters:
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `javax.agent.service.naming.NamingException` - On any naming error.
    `AbleException`

### 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`
  Parameters:
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `javax.agent.service.naming.NamingException` - On any naming error.
    `AbleException`

### getAgentDescription

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

  Description copied from interface: `AblePlatformAgent`
  Retrieves the agent's AgentDescription.

  Specified by:
    `getAgentDescription` in interface `AblePlatformAgent`
  Returns:
    The agent's AgentDescription object.

### 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.
  See Also:
    `AbleObject.init()`

### 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.
  See Also:
    `AbleObject.init()`

### 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.
  See Also:
    `AbleObject.inputBuffer`, `AbleObject.outputBuffer`, `AbleBean.process()`

### 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`
  Throws:
    `AbleException`
  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`
  Throws:
    `AbleException`

### 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`
  Throws:
    `AbleException`

### _init

    protected void _init()
                  throws AbleException

  Performs the actual work of initialization. In particular,
  - Calls `preInit()`, in case it has not been called before, which, depending on need,
    - Calls `getAndValidateServiceRoot()` to get addressability to the ServiceRoot. All services must be up and running. If the Naming Service, Directory Service, or the Transport System is not available, an exception is thrown.
    - Calls `getAndSetAgentNames()` to get the Globally Unique ID (GUID, or AgentName) of this agent from the Agent Naming Service.
  - Calls `getAndSetAgentDescription()` to get a new, empty Agent Description and then load it with both the built-in Able attributes and any user-defined agent attributes as found in the data member `myJasAgentAttributes`.
  - Calls `getAndSetTransportServices()` to get the Message Transport Services from the Transport System, and then selects one to use.
  - Calls `loadAgentDescriptionWithBaseLocators()` to add Locators to the AgentDescription. The number of locators created depends on the data member `myAgentInboxes`, but at least one locator is always created.
  - Calls `loadAgentDescriptionWithAbleLocator()` to add a special Able Locator to the Agent Description. See the data member `myJasAbleLocator`.
  - Calls `maybeRegisterWithAgentDirectoryService(boolean)` to register the Agent Description with the Agent Directory Service. See the data member `agentToAutoRegister`.
  - Calls `maybeRebindToRmi(boolean)` to (re)bind the agent to an RMI Naming service, so that the agent can be located by RMI lookup. See the data member `agentToBindToRmi`.
  - Calls `super.init()` to allow the super classes to initialize.
  - Calls `updateAgentDescription()` to cause the agent's AgentDescription to be refreshed with the Agent Directory Service.

  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.

  Parameters:
    `theArg` - Usually an Object[] containing data that can be used to initialize the agent.
  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
  - `reset()` in condition 1.
  - `resetAgent(AbleSecureKey)` in conditions 1 and 2.

  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
  - `quitAll()` in condition 1.
  - `quitAgent(AbleSecureKey)` in conditions 1 and 2.

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

  As needed:

  - Calls `super.quitAll()` to stop all threads
  - Calls `maybeDeregisterWithAgentDirectoryService()` to deregister from the Agent Directory Service
  - Calls `maybeUnbindFromRmi()` to unbind from the RMI Naming service
  - Releases the unique agent name back to the Agent Naming Service
  - Zaps data members to null
  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
  - `suspendAll()` in condition 1.
  - `suspendAgent(AbleSecureKey)` in conditions 1 and 2.

  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
  - `resumeAll()` in condition 1.
  - `resumeAgent(AbleSecureKey)` in conditions 1 and 2.

  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
  - 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.

  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

  - `AblePlatform.AbleAgentAutonomyLevel` from `AblePlatform`
  - `JasConstants.AGENT_DISPLAY_NAME` from `AbleObject.name`
  - `AblePlatform.AbleAgentDescription` from `AbleObject.comment`
  - `AblePlatform.AbleAgentMovable` from `agentMovable`
  - `AblePlatform.AbleAgentLastUpdate` from `agentLastUpdate`
  - `AblePlatform.AbleAgentSummary` from `agentSummary`
  - `AblePlatform.AbleAgentType` from `agentType`
  - `AblePlatform.AbleAgentVendor` from `agentVendor`
  - `AblePlatform.AbleAgentVersion` from `agentVersion`
  - `AblePlatform.AbleAgentAgentPool`

  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

  Throws:
    `AbleException`

### toString

    public java.lang.String toString()

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

  Returns:
    A String containing the current contents of the object.

### getCapability

    public AbleAgentCapability getCapability(java.lang.Object theCapabilityIdentifier)
                                      throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets a specific AgentCapability of this agent.

  Specified by:
    `getCapability` in interface `AblePlatformAgent`
  Parameters:
    `theCapabilityIdentifier` - The identifier of the AgentCapability to return.
  Returns:
    The AgentCapability requested, or null if a capability with the specified identifier does not exist.
  Throws:
    `AbleException`

### getCapabilities

    public java.util.Map getCapabilities()
                                  throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets a Map of this agent's AgentCapability objects. Each entry of the Map is:

       Key:   ((Object)              aCapabilityIdentifier)
       Value: ((AbleAgentCapability) anAgentCapability    )

  Specified by:
    `getCapabilities` in interface `AblePlatformAgent`
  Returns:
    A Map of this agent's capabilities. The Map may be empty if no AgentCapabilities exist for this agent.
  Throws:
    `AbleException`

### setCapabilityAutonomyLevel

    public void setCapabilityAutonomyLevel(java.lang.Object theCapabilityIdentifier,
                                           int theAutonomyLevel,
                                           AbleSecureKey theSecureKey)
                                    throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Sets the autonomy level of the specified AgentCapability.

  Specified by:
    `setCapabilityAutonomyLevel` in interface `AblePlatformAgent`
  Parameters:
    `theCapabilityIdentifier` - The identifier of the AgentCapability whose autonomy level is to be set.
    `theAutonomyLevel` - The new autonomy level for the specified AgentCapability.
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `AbleException` -

    If the caller cannot be verified by the VerifiableAgentNamingService.

    If authorization failed.

    If unable to update the capabilities of this agent.

### setCapabilityAutonomyLevels

    public void setCapabilityAutonomyLevels(java.util.Map theCapabilityAutonomyLevels,
                                            AbleSecureKey theSecureKey)
                                     throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Updates the autonomy level of each of this agent's capabilities according to the autonomy levels in the specified Map. Each entry of the Map is:

       Key:   ((Object)  anExistingCapabilityIdentifier)
       Value: ((Integer) aNewAutonomyLevel             )

  Specified by:
    `setCapabilityAutonomyLevels` in interface `AblePlatformAgent`
  Parameters:
    `theCapabilityAutonomyLevels` - Map of capabilityID/autonomyLevel pairs. Each entry of the Map is:

                    Key:   ((Object)  anExistingCapabilityIdentifier)
                    Value: ((Integer) aNewAutonomyLevel             )

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

    If the caller cannot be verified by the VerifiableAgentNamingService.

    If authorization failed.

    If unable to update the capabilities of this agent.

### getCapabilityAutonomyLevels

    public java.util.Map getCapabilityAutonomyLevels()
                                              throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets, based on the agent's current AutonomyLevel setting, the appropriate set of capability autonomy levels. The set represents either the HIGH, MEDIUM, LOW, or CUSTOM capability autonomy levels. Each entry of the returned Map is:

       Key:   ((Object)  aCapabilityIdentifier)
       Value: ((Integer) anAutonomyLevel      )

  Specified by:
    `getCapabilityAutonomyLevels` in interface `AblePlatformAgent`
  Returns:
    A Map of this agent's autonomy levels for each of the agent's AgentCapabilities at the agent's current AutonomyLevel setting.
  Throws:
    `AbleException`

### getCapabilitySummaryByAgentAutonomyLevel

    public AbleMessageContainer getCapabilitySummaryByAgentAutonomyLevel(int theAgentAutonomyLevel)
                                                                  throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets an NLS text summary of the agent's capabilities based on the specified agent AutonomyLevel.

  Returns a MessageContainer that describes the overall agent autonomy summary if the agent's AutonomyLevel is set to `theAutonomyLevel`.

  Specified by:
    `getCapabilitySummaryByAgentAutonomyLevel` in interface `AblePlatformAgent`
  Parameters:
    `theAgentAutonomyLevel` - The agent AutonomyLevel that the summary is to represent. Must be one of:
    - AblePlatform.HighAutonomy
    - AblePlatform.MediumAutonomy
    - AblePlatform.LowAutonomy
    - AblePlatform.CustomAutonomy
  Returns:
    The capability autonomy level summary string for the specified agent AutonomyLevel, or null if an unknown agent AutonomyLevel is specified. (No exception is thrown in this case.)
  Throws:
    `AbleException` - If unable to create the capability autonomy level summary.

### getCapabilitySummaryByCapabilityAutonomyLevels

    public AbleMessageContainer getCapabilitySummaryByCapabilityAutonomyLevels(java.util.Map theCapabilityAutonomyLevels)
                                                                        throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets an NLS text summary of the agent's capabilities based on the specified capability autonomy levels.

  Specified by:
    `getCapabilitySummaryByCapabilityAutonomyLevels` in interface `AblePlatformAgent`
  Parameters:
    `theCapabilityAutonomyLevels` - The capability autonomy levels that the summary is to represent. Each entry of the Map is:

        			      Key:   ((Object)  aCapabilityIdentifier)
                    Value: ((Integer) anAutonomyLevel      )

    If null, then the summary is created using the current agent AutonomyLevel of this agent.
  Returns:
    A string that describes the overall agent autonomy summary if the agent's capability autonomy levels are set to `theCapabilityAutonomyLevels`.
  Throws:
    `AbleException` - If unable to create the autonomy levels summary.

### getCapabilityPresets

    public java.util.Map[] getCapabilityPresets()
                                         throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Returns an array of four Maps. Each Map defines the preset autonomy level of each capability for this agent in this order: [0]High, [1]Medium, [2]Low and [3]Custom. The presets of the High, Medium, and Low autonomy levels are defined when the agent is created. The custom preset is the last custom capabilities autonomy level of the agent that did not match one of the three pre-defined presets.

  Specified by:
    `getCapabilityPresets` in interface `AblePlatformAgent`
  Returns:
    Map[] of all the AgentCapability presets.
  Throws:
    `AbleException`

### getCapabilityOrder

    public java.util.Vector getCapabilityOrder()
                                        throws AbleException

  Description copied from interface: `AblePlatformAgent`
  The order of an agent's AgentCapabilities may be important. If so, the agent may set and maintain a list that specifies the Identifiers of the agent's capabilities in the desired order. This method returns that list. If nothing is set, then the order is not important, and the returned list is empty (but not null).

  Specified by:
    `getCapabilityOrder` in interface `AblePlatformAgent`
  Returns:
    A list containing the AgentCapability order.
  Throws:
    `AbleException`

### handleAnsweredRequest

    public final void handleAnsweredRequest(AbleAgentSituationReport theAgentSituationReport,
                                            AbleSecureKey theSecureKey)
                                     throws AbleException

  Description copied from interface: `AblePlatformAgent`
  This method is called to answer a request that this agent had previously logged to the AgentLoggingService.

  The process of handling an answered request is done in several steps:

  1. Validation. Before continuing with processing the specified request, the agent must determine if the request is still valid. If the request is outdated, and the agent no longer needs assistance, the process can be killed now. The method `validateRequest(AbleAgentSituationReport)` is called to determine if the request is still valid.
  2. Authentication. If platform security is on, `theSecureKey` is checked to make sure that the caller is trusted by the platform, and using a valid AbleSecureKey.
  3. Authorization. If security is on, the agent now knows that the caller is trusted by the platform. However, the agent must now decide if the caller has enough authority to answer the specified request. The method `authenticateAndAuthorizeCaller(AbleAgentSituationReport,AbleSecureKey)` is called to perform steps 2 and 3.
  4. Asynchronous Delegation. At this point, the agent has decided to process this answered request. However, processing the request can take a "long" time. Therefore, a seperate thread is started to do the processing, allowing this method to return. From now on, no failures can be returned to the caller; failures should be logged to the AgentLoggingService.

     Note that the Thread that is spawned to do the actual processing of the answer calls the method `processAnsweredRequest`.

  Specified by:
    `handleAnsweredRequest` in interface `AblePlatformAgent`
  Parameters:
    `theAgentSituationReport` - The original AgentSituationReport containing an answer to an outstanding (prevously logged) request.
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `AbleException` -

    If the caller is not verified by the Naming Service.

    If the request is no longer valid.

    If authorization failed.

    If unable to update the capabilities of this agent.

### getAboutDataBean

    public java.io.Serializable getAboutDataBean()
                                          throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets the data bean from which a console can obtain the information that is displayed on this agent's 'About' panel.

  Specified by:
    `getAboutDataBean` in interface `AblePlatformAgent`
  Returns:
    The agent's 'about' data bean.
  Throws:
    `AbleException` -

    On all errors getting the 'About' dataBean.

### setCustomizerDataBean

    public void setCustomizerDataBean(java.io.Serializable theDataBean,
                                      AbleSecureKey theSecureKey)
                               throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Sets the data bean from which this agent can retrieve it's updated customizable data. The console has displayed the data on the agent's 'Customize' panel, allowed a user to change the data, and then uses this method to send the data back to the agent.

  Specified by:
    `setCustomizerDataBean` in interface `AblePlatformAgent`
  Parameters:
    `theDataBean` - Contains data from the agent's 'Customize' panel.
    `theSecureKey` - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.
  Throws:
    `AbleException` -

    If the caller is not verified by the Naming Service.

    On all errors setting the customizer data bean.

### getCustomizerDataBean

    public java.io.Serializable getCustomizerDataBean()
                                               throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets the data bean from which a console can obtain this agent's customizable data so that the data can be displayed on this agent's 'Customize' panel.

  Specified by:
    `getCustomizerDataBean` in interface `AblePlatformAgent`
  Returns:
    The agent's 'customize' data bean.
  Throws:
    `AbleException` -

    On all errors getting the 'Customize' data bean.

### getCustomizerInfo

    public java.lang.String[] getCustomizerInfo()
                                         throws AbleException

  Description copied from interface: `AblePlatformAgent`
  Gets information about this agent's 'Customize' and 'About' GUIs.

  Specified by:
    `getCustomizerInfo` in interface `AblePlatformAgent`
  Returns:
    String[] with customizer info.

    String[0] is the fully qualified name of the customizer class.

    String[1] is the fully qualified name of the about class.

    Returns null if there is no customizer info for this agent; null is returned by the AblePlatformDefaultAgent implementation.

  Throws:
    `AbleException` - On all errors getting the customizer info.

### initCommonCode

    protected void initCommonCode(java.lang.Object theArg)
                           throws AbleException

  Initializes the agent with the specified argument. Because there are two initialization paths, one path without an initialization argument and one path with an initialization argument, it can be inconvenient to have to override the methods of the two paths and have to put duplicate, common code in both paths. This method, called at the end of both paths, allows a programmer to put code common to both paths in a single place.

  Subclasses that override this method must call this super method.

  Note that the last thing this method does is check the specified argument to see whether it is a Map[4] that can be used to set up AgentCapabilities. If the argument is a Map[4], `initAgentCapabilities(Map[])` is called. All other argument types are ignored in this implementation.

  If you override this method in order to handle a complex initialization argument, one from which you might need to extract several different types of initialization arguments, you can call `initAgentCapabilities(Map[])` directly from your overriding method at any time, and then pass null to this method on the super call. Or, you can do all your other initializations first, and then pass the extracted Map[4] here.

  Parameters:
    `theArg` - abc...
  Throws:
    `AbleException` - If the agent is using AgentCapabilities and the AgentLoggingService cannot be found, or if the AgentCapabilities are not set up properly.

### initAgentCapabilities

    protected void initAgentCapabilities(java.util.Map[] theCapabilities)
                                  throws AbleException

  Initializes the agent with the specified AgentCapabilities. This method may be called during the standard ABLE 'init' process from `initCommonCode(Object)`, but only if the argument is a Map[4]. If the initialization argument needs to be something else, call this method directly from on overridden version of `initCommonCode(Object)`.

  Parameters:
    `theCapabilities` - An array of four `Map`s defining the capabilities of this agent. The first Map (element [0]) must contain the actual AgentCapabilities of this agent, and the next three Maps must be: `highCapabilityAutonomyLevels`, `mediumCapabilityAutonomyLevels` and `lowCapabilityAutonomyLevels`, respectively.

    This parameter may be null, in which case no capabilities are set in the agent.

  Throws:
    `AbleException` -

    If the capabilities are not properly setup.

  Since:
    ABLE 2.2.0

### verifyCapabilities

    protected void verifyCapabilities()
                               throws AbleException

  All subclasses using AgentCapabilities must define their own capabilities and each capability's autonomy level. This means that the capabilities highCapabilityAutonomyLevel, mediumCapabilityAutonomyLevel and lowCapabilityAutonomyLevel Maps must be initialized.

  This method, called by `initAgentCapabilities(Map[])`, is used to verify that the autonomy level of each of this agent's capabilities is valid. The capabilities can be set in one of two ways:

  - By a subclass initializing and setting these four Maps.
  - By passing a Map[4] as the init arguments.

  To be verified, the overall capabilities and three individual preset Maps must not be null, and each preset must contain the same keys as the capabilities.

  This method is called when init is called, but a subclass should call this method right after it has defined the capabilities and autonomy levels to make sure that they are valid.

  Throws:
    `AbleException` -

    If any of the four capability Maps are null.

    If any of the presets do not have the same keys as the capabilities Map.

    If the capability order Vector contains invalid or duplicate capabilities.

    If an AgentLoggingService is not available.

  Since:
    ABLE 2.2.0

### authorizeCapabilityChangeRequest

    protected void authorizeCapabilityChangeRequest(AbleSecureKey theSecureKey)
                                             throws AbleException

  This default implementation, called by those methods that change an agent's AutonomyLevel or the autonomy levels of its AgentCapabilities to determine whether the caller of the method is authorized to perform the requested change, performs a simple check: all the callers in the chain must have a trust level that is greater than or equal to the trust level of this agent in order for the operation to proceed.

  Subclasses can override this method to restrict authorization based on the VerifiableAgentName that sent the change request.

  This method assumes the SecureKey has already been verified. In other words, call `verifyKey(AbleSecureKey,String)` before calling this method.

  Parameters:
    `theSecureKey` - The AbleSecureKey from the entity attempting to make the change.
  Throws:
    `AbleException` - If this capability change request is not authorized.
  Since:
    ABLE 2.2.0

### makeCapabilityAutonomyLevelsSummary

    protected AbleMessageContainer makeCapabilityAutonomyLevelsSummary(java.util.Map theCapabilityAutonomyLevels)
                                                                throws AbleException

  Returns an AbleMessage Container that describes the overall agent autonomy summary if the agent's capability autonomy levels are set to `theCapabilityAutonomyLevels`.

  The default implementation of this method will return a basic string in this format: "Automate {0} capabilities, Ask first for {1} capabilities, never run {2} capabilities." This method can be overridden to create a summary String more specific to the agent subclass.

  Parameters:
    `theCapabilityAutonomyLevels` - The capability autonomy levels that you want the summary to represent. Each entry of the Map is:

                    Key:   ((Object)  aCapabilityIdentifier)
                    Value: ((Integer) anAutonomyLevel      )

  Returns:
    The capability autonomy level summary string for the passed in capability autonomy levels.
  Throws:
    `AbleException` - If an invalid capability was set in `theCapabilityAutonomyLevels`.
  Since:
    ABLE 2.2.0

### validateAnsweredRequest

    protected void validateAnsweredRequest(AbleAgentSituationReport theAnsweredAgentSituationReport)
                                    throws AbleException

  This default implementation, called by `handleAnsweredRequest(com.ibm.able.platform.AbleAgentSituationReport, com.ibm.able.platform.AbleSecureKey)` in order to determine whether the specified request is still valid, does nothing.

  This method should be overridden by all subclasses that have requests that may turn invalid after the requests were logged.

  If an agent logged a request a while back, by the time it was answered it may no longer be a valid request. The agent should have removed it from the AgentLoggingService, but if it didn't, this is the last chance to end this process, and notifiy the caller. After this, if authorization succeeds, a new thread will be started to handle the processing of the answered request. Then the only way to notify the caller about anything is to log a history log.

  Parameters:
    `theAnsweredAgentSituationReport` - The answered AgentSituationReport that this agent had previously logged.
  Throws:
    `AbleException` - If the request is no longer valid.
  Since:
    ABLE 2.2.0

### authenticateAndAuthorizeCaller

    protected void authenticateAndAuthorizeCaller(AbleAgentSituationReport theAnsweredAgentSituationReport,
                                                  AbleSecureKey theSecureKey)
                                           throws AbleException

  This default implementation, called by `handleAnsweredRequest(com.ibm.able.platform.AbleAgentSituationReport, com.ibm.able.platform.AbleSecureKey)` in order to determine whether the answerer of the request is authentic and authorized to answer the request, does nothing.

  This method should be overridden by all subclasses that care about who is allowed to answer the requests of this agent. It is what handles authorizing an answer to one of the agent's logged requests. Based on the AgentSituationReport that is answering the request, and the VerifiableAgentName that sent this answer, the method must decide if it will proceed with this answer.

  Parameters:
    `theAnsweredAgentSituationReport` - The answered AgentSituationReport that this agent had previously logged.
    `theSecureKey` - The AbleSecureKey from the entity answering the request.
  Throws:
    `AbleException` - If caller failed to authenticate or authorize.
  Since:
    ABLE 2.2.0

### processAnsweredRequest

    protected void processAnsweredRequest(AbleAgentSituationReport theAnsweredAgentSituationReport,
                                          AbleSecureKey theSecureKey)

  This default implementation of `processAnsweredRequest` does nothing.

  This method should be overridden by all subclasses. After the processing of an answered AgentSituationReport has passed Validation, Authentication and Authorization, the thread spawned by the Asynchronous Delegation step calls this method to do the actual processing of the answered AgentSituationReport.

  This method does not throw any exceptions since the processing is on a different thread than the original `handleAnsweredRequest(com.ibm.able.platform.AbleAgentSituationReport, com.ibm.able.platform.AbleSecureKey)` call. The only way to notify the caller of failures now is by logging to the AgentLoggingService.

  Parameters:
    `theAnsweredAgentSituationReport` - The answered AgentSituationReport that this agent had previously logged to the AgentLoggingService.
    `theSecureKey` - The AbleSecureKey that was used to answer this request.
  Since:
    ABLE 2.2.0

### logHistory

    protected void logHistory(AbleMessageContainer theDescription,
                              AbleMessageContainer theAction,
                              AbleMessageContainer theSummary)
                       throws AbleException

  Helper method used to log a History log. A history log only needs three things, a description, action and summary.

  Parameters:
    `theDescription` - A description of this event being logged
    `theAction` - The action of this event being logged
    `theSummary` - The summary of this event being logged.
  Throws:
    `AbleException` -

    On errors logging to the AgentLoggingService.

    On errors getting the name of this agent.

  Since:
    ABLE 2.2.0

### createAgentSituationReport

    protected AbleAgentSituationReport createAgentSituationReport(java.io.Serializable theIdentifier,
                                                                  AbleAgentCapability theCapability,
                                                                  AbleAgentSituation theSituation,
                                                                  AbleMessageContainer theSuggestedResponse,
                                                                  AbleMessageContainer theResponseTaken,
                                                                  AbleMessageContainer theResultsSummary,
                                                                  boolean theProblemState)
                                                           throws AbleException

  Helper method used to create an AgentSituationReport for this agent.

  This will fill the AgentSituationReport with this agent's:

  - AgentName
  - Agent Description
  - Time Created
  - Host
  All that will need to be supplied is the:
  - Identifier
  - Capability
  - Situation
  - Suggested Response
  - Response Taken
  - Results Summary
  - Problem State

  Throws:
    `AbleException` -

    On errors calling getAgentName() to create the agent description.

    On errors calling getAgentHost().

  Since:
    ABLE 2.2.0

### logAgentSituationReport

    protected void logAgentSituationReport(AbleAgentSituationReport theAgentSituationReport)
                                    throws AbleException

  This method handles the details of logging an AgentSituationReport to the AgentLoggingService for this agent.

  Parameters:
    `theAgentSituationReport` - The AgentSituationReport that is to be logged
  Throws:
    `AbleException` -

    If a reference to the Logging Service does not exist. This is common if the agent has not been initialized yet.

    On any errors adding the logs.

  Since:
    ABLE 2.2.0

### updateAgentSituationReport

    protected void updateAgentSituationReport(AbleAgentSituationReport theOldAgentSituationReport,
                                              AbleAgentSituationReport theNewAgentSituationReport)
                                       throws AbleException

  This method handles the details of updating one of this agent's AgentSituationReports.

  Parameters:
    `theOldAgentSituationReport` - The AgentSituationReport that is to be updated.
    `theNewAgentSituationReport` - The updated AgentSituationReport.
  Throws:
    `AbleException` -

    If a reference to the AgentLogging does not exist. This is common if the agent has not been initialized yet.

    On any errors removing the logs.

  Since:
    ABLE 2.2.0

### removeAgentSituationReports

    protected void removeAgentSituationReports(java.util.Vector theAgentSituationReportsToRemove)
                                        throws AbleException

  This method handles the details of removing one of this agent's AgentSituationReports.

  Parameters:
    `theAgentSituationReportsToRemove` - The AgentSituationReports that are to be removed.
  Throws:
    `AbleException` -

    If a reference to the AgentLoggingService does not exist. This is common if the agent has not been initialized yet.

    On any errors removing the logs.

  Since:
    ABLE 2.2.0

### verifyKey

    protected final void verifyKey(AbleSecureKey theSecureKey,
                                   java.lang.String theMethod)
                            throws AbleException

  Helper method used to verify a secure key. It catches all NamingExceptions, logs them and re-throws them as AbleExceptions.

  Throws:
    `AbleException` - On any namming error while verifying the `key`.
  Since:
    ABLE 2.2.0

### getAgentLoggingService

    protected final void getAgentLoggingService(java.lang.String theMsgId,
                                                java.lang.Object[] theSubstitutionText,
                                                java.lang.String theMethod)
                                         throws AbleException

  Sets `myAgentLoggingService` to reference the AgentLoggingService. If a reference cannot be obtained, a message is logged and an exception is thrown.

  Parameters:
    `theMsgId` - The resource bundle ID of the message to report if the AgentLoggingService cannot be obtained.
    `theSubstitutionText` - Text to be substituted into the message specified above, or null if no text needs to be substituted.
    `theMethod` - the name of the calling method, for logging purposes.
  Throws:
    `AbleException` - If the AgentLoggingService cannot be obtained from the ServiceRoot.

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005