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