com.ibm.able.platform
Class AbleEServerDefaultAgent

com.ibm.able.platform.AblePlatformDefaultAgent
  |
  +--com.ibm.able.platform.AbleEServerDefaultAgent
All Implemented Interfaces:
AbleEServerAgent, AblePlatformAgent, javax.agent.service.transport.MessageListener, java.io.Serializable
Direct Known Subclasses:
EServerTemplateAgent

public class AbleEServerDefaultAgent
extends AblePlatformDefaultAgent
implements AbleEServerAgent, java.io.Serializable

This class defines the base behavior, which all ABLE eServer agents must support. This behavior includes:

  1. A set of methods to deal with the capabilities and autonomy level of this agent.
  2. A set of methods to deal with the answering of this agent's requests.

See Also:
Serialized Form

Field Summary
protected  java.util.HashMap capabilities
          This HashMap holds the capabilities of this agent.
protected  java.util.Vector capabilityOrder
          The order that the capabilities are displayed in might be important.
protected  java.util.HashMap customCapabilitySettings
          This HashMap holds the autonomy levels of the custom capabilitie settings.
protected  java.util.HashMap highCapabilitySettings
          This HashMap holds the HIGH pre-defined autonomy levels for the capabilities of this agent.
protected  java.util.HashMap lowCapabilitySettings
          This HashMap holds the LOW pre-defined autonomy levels for the capabilities of this agent.
protected  java.util.HashMap mediumCapabilitySettings
          This HashMap holds the MEDIUM pre-defined autonomy levels for the capabilities of this agent.
protected  AgentLoggingService myEServerLoggingService
          The eServer Logging service for this agent, set by the init() method.
 
Fields inherited from class com.ibm.able.platform.AblePlatformDefaultAgent
agentLastUpdate, agentMovable, agentStatus, agentSummary, agentToAutoRegister, agentToBindToRmi, agentType, agentVendor, agentVersion, myAgentInboxes, myJasAbleLocator, myJasAgentAttributes, myJasAgentDescription, myJasAgentDirectoryService, myJasAgentName, myJasAgentNamingService, myJasDefaultLocator, myJasMessageTransportService, myJasServiceRoot, myJasTransportSystem, myJasVerifiableDirectoryService, myJasVerifiableNamingService, myKeyPair, myPrincipal, myReceiveMessageMethod, myRequestKey, mySecSppt, myTrustLevel, myVerifiableAgentName
 
Constructor Summary
AbleEServerDefaultAgent()
          Creates an AbleEServerDefaultAgent wrapped around an AblePlatformDefaultAgent instance.
AbleEServerDefaultAgent(java.lang.String theName)
          Creates an AbleEServerDefaultAgent wrapped around an AblePlatformDefaultAgent instance with specified name.
AbleEServerDefaultAgent(java.lang.String theName, java.lang.String theComment)
          Creates an AbleEServerDefaultAgent wrapped around an AblePlatformDefaultAgent instance with specified name and comment.
 
Method Summary
protected  void _answerRequest(AbleAgentSituationReport answeredAbleAgentSituationReport, AbleSecureKey key)
          This is the default implementation of _answerRequest and it does nothing.
protected  java.lang.Object _getAboutDataBean()
          Override this method to return an AUIML DataBean to the ABLE console for the About panel.
protected  java.lang.Object _getCustomizerDataBean()
          Override this method to return an AUIML DataBean to the ABLE console for the Customize panel.
protected  java.lang.String[] _getCustomizerInfo()
          Returns info that the Admin GUI needs to display the Customizer and the About panels.
protected  void _init()
          Initialize and configure the bean.
protected  void _init(java.lang.Object capabilities)
          Initialize and configure the bean.
protected  void _quitAll()
          This method is overridden so this agent can remove all of its logs from the logging service if someone chose to quit this agent.
protected  void _setCustomizerDataBean(java.lang.Object dataBean, AbleSecureKey key)
          Override this method to first handle authorization of this set request, and then to handle applying the data bean's properties to this agent.
 void answerRequest(AbleAgentSituationReport agentReport, AbleSecureKey key)
          This method is called to answer a request that this agent had previously logged to the Logging Service.
protected  void authenticateAndAuthorizeCaller(AbleAgentSituationReport answeredAbleAgentSituationReport, AbleSecureKey key)
          This is the default implementation of authenticateAndAuthorizeCaller and it does nothing.
protected  void authorizeCapabilityChangeRequest(AbleSecureKey key)
          This is the default implementation of authorizeCapabilityChangeRequest and it does nothing.
protected  AbleAgentSituationReport createAbleAgentSituationReport(java.io.Serializable theIdentifier, AbleEServerCapability theCapability, AbleEServerSituation theSituation, com.ibm.able.AbleMessageContainer theSuggestedResponse, com.ibm.able.AbleMessageContainer theResponseTaken, com.ibm.able.AbleMessageContainer theResultsSummary, boolean theState)
          Helper method used to create an AbleAgentSituationReport for this agent.
 byte[] getAboutDataBean()
          This is an internal version of _getAboutDataBean().
 int getAutonomyLevel()
          Return the autonomy level of this agent.
 java.util.HashMap getCapabilities()
          Get the HashMap of this agent's capabilites.
 AbleEServerCapability getCapability(java.lang.Object capabilityIdentifier)
          Get a specific capability of this agent.
 java.util.Vector getCapabilityOrder()
          The order that an agent's AbleEServerCapabilities may be important.
 java.util.HashMap[] getCapabilityPresets()
          Return an array of four HashMaps.
 java.util.HashMap getCapabilitySettings()
          Get the HashMap of this agent's capability settings ((Object)CapabiltiyIdentifier)->((Integer)autonomyLevel)
 com.ibm.able.AbleMessageContainer getCapabilitySettingsSummary(int autonomyLevel)
          Return an AbleMessageContainer that describes the overall agent autonomy summary if the agent's autonomy level was set to autonomyLevel.
 com.ibm.able.AbleMessageContainer getCapabilitySettingsSummary(java.util.Map capabilitySettings)
          Return a string that describes the overall agent autonomy summary if the agent's capability settings were set to capabilitySettings.
 byte[] getCustomizerDataBean()
          This is an internal version of _getCustomizerDataBean().
 java.lang.String[] getCustomizerInfo()
          This is an internal version of the _getCustomizerInfo() method.
 byte[] getCustomizerResource(java.lang.String resourceName)
          Method getCustomizerResource.
protected  void lclInit(java.lang.Object theCapabilities)
          This method will perform some of the initial setup of this agent when it is first initialized(started).
protected  void logAbleAgentSituationReport(AbleAgentSituationReport theAbleAgentSituationReport)
          This method will handle the details of logging an AbleAgentSituationReport to the Logging Service for this agent.
protected  void logHistory(com.ibm.able.AbleMessageContainer description, com.ibm.able.AbleMessageContainer action, com.ibm.able.AbleMessageContainer summary)
          Helper method used to log a History log.
protected  com.ibm.able.AbleMessageContainer makeCapabilitySettingsSummary(java.util.Map capabilitySettings)
          Return an AbleMessage Container that describes the overall agent autonomy summary if the agent's capability settings were set to capabilitySettings.
protected  void removeAbleAgentSituationReports(java.util.Vector AbleAgentSituationReportsToRemove)
          This method will handle the details of removing one of this agent's AbleAgentSituationReports.
protected  void setAgentAutonomyLevel(int theAgentAutonomyLevel)
          This method is overridden to handle the updating of the capabilities when the agent's autonomy level is changed.
 void setAgentAutonomyLevel(int agentAutonomyLevel, AbleSecureKey key)
          Sets the agent's autonomy level.
 void setCapabilitySetting(java.lang.Object capabilityIdentifier, int autonomyLevel, AbleSecureKey key)
          Sets the autonomy level of the one of this agent's capabilities.
 void setCapabilitySettings(java.util.Map theCapabilities, AbleSecureKey key)
          Update the autonomy levels of this agent's capabilities according to the autonomy level settings in the passed in Map((Object)CapabiltiyIdentifier)->((Integer)autonomyLevel)
 void setCustomizerDataBean(java.lang.Object dataBean, AbleSecureKey key)
          This is an internal version of _setCustomizerData().
protected  void updateAbleAgentSituationReport(AbleAgentSituationReport oldAbleAgentSituationReport, AbleAgentSituationReport newAbleAgentSituationReprot)
          This method will handle the details of updating one of this agent's AbleAgentSituationReports.
protected  void validateRequest(AbleAgentSituationReport answeredAbleAgentSituationReport)
          This is the default implementation of validateRequest and it does nothing.
protected  void verifyCapabilities()
          All subclasses must define their own capabilities and their settings.
 
Methods inherited from class com.ibm.able.platform.AblePlatformDefaultAgent
_reset, _resumeAll, _suspendAll, addAgentInbox, addJasAgentAttribute, broadcastTransportMessage, Copyright, createLocatorAndBindToMethod, getAgentAutonomyLevel, getAgentInboxes, getAgentLastUpdate, getAgentStatus, getAgentSummary, getAgentType, getAgentVendor, getAgentVersion, getAndSetAgentDescription, getAndSetAgentNames, getAndSetTransportServices, getAndValidateServiceRoot, getJasAgentAttributes, getJasAgentName, getNewAgentDescription, getPlatformAgentName, getPrincipal, getTransportMessageContent, getTransportMessageContent2, init, init, initializeAgent, initializeAgent, isAgentMovable, isAgentToAutoRegister, isAgentToBindToRmi, loadAgentDescriptionWithAbleAttributes, loadAgentDescriptionWithAbleLocator, loadAgentDescriptionWithAgentName, loadAgentDescriptionWithBaseLocators, loadAgentDescriptionWithPublicKey, loadAgentDescriptionWithUserAttributes, logException, lookUpAgent, lookUpAgent, main, maybeDeregisterWithAgentDirectoryService, maybeRebindToRmi, maybeRegisterWithAgentDirectoryService, maybeUnbindFromRmi, preInit, preInit, process, quitAgent, quitAll, receiveMessage, removeAgentInbox, removeAgentInboxes, removeJasAgentAttribute, reset, resetAgent, resumeAgent, resumeAll, sendTransportMessage, sendTransportMessage, setAgentMovable, setAgentNameUniqueID, setAgentSummary, setAgentToAutoRegister, setAgentToBindToRmi, setAgentType, setAgentVendor, setAgentVersion, setPrincipal, setRequestKey, setRestartedFromPersistence, suspendAgent, suspendAll, toString, updateDescriptionWithAgentDirectoryService
 
Methods inherited from interface com.ibm.able.platform.AblePlatformAgent
getAgentAutonomyLevel, getAgentLastUpdate, getAgentStatus, getAgentSummary, getAgentType, getAgentVendor, getAgentVersion, getJasAgentAttributes, getJasAgentName, getPlatformAgentName, initializeAgent, initializeAgent, isAgentMovable, isAgentToAutoRegister, isAgentToBindToRmi, preInit, preInit, quitAgent, resetAgent, resumeAgent, suspendAgent
 
Methods inherited from interface javax.agent.service.transport.MessageListener
equals, hashCode
 

Field Detail

myEServerLoggingService

protected AgentLoggingService myEServerLoggingService
The eServer Logging service for this agent, set by the init() method.

capabilities

protected java.util.HashMap capabilities
This HashMap holds the capabilities of this agent. ((Object)CapabiltiyIdentifier) -> ((AbleEServerCapability)Capability)

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 setting HashMaps: highCapabilitySettings, mediumCapabilitySettings and lowCapabilitySettings, and the capabilityOrder when the agent is instantiated. The agent should then call its verifyCapabilities() method to guarantee that its capabilities and settings are valid, and the order vector contains appropriate identifierss. If these were not set correctly, the agent when fail on init.

The only other way to set the capabilities is by passing an AbleEServerCapability[] as the init arguments. Using the init arguments would overwrite any capability and settings that might have already been set.


capabilityOrder

protected java.util.Vector capabilityOrder
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.

highCapabilitySettings

protected java.util.HashMap highCapabilitySettings
This HashMap holds the HIGH pre-defined autonomy levels for the capabilities of this agent. ((Object)CapabiltiyIdentifier -> (Integer)autonomyLevel)
See Also:
capabilities

mediumCapabilitySettings

protected java.util.HashMap mediumCapabilitySettings
This HashMap holds the MEDIUM pre-defined autonomy levels for the capabilities of this agent. ((Object)CapabiltiyIdentifier -> (Integer)autonomyLevel)
See Also:
capabilities

lowCapabilitySettings

protected java.util.HashMap lowCapabilitySettings
This HashMap holds the LOW pre-defined autonomy levels for the capabilities of this agent. ((Object)CapabiltiyIdentifier -> (Integer)autonomyLevel)
See Also:
capabilities

customCapabilitySettings

protected java.util.HashMap customCapabilitySettings
This HashMap holds the autonomy levels of the custom capabilitie settings. The custom capabilities are set whenever the capabilities of this agent are set, and they do not match one of the three defined autonomy level settings: HIGH, MEDIUM, or LOW autonomy. ((Object)CapabiltiyIdentifier -> (Integer)autonomyLevel)
Constructor Detail

AbleEServerDefaultAgent

public AbleEServerDefaultAgent()
                        throws com.ibm.able.AbleException,
                               java.rmi.RemoteException
Creates an AbleEServerDefaultAgent wrapped around an AblePlatformDefaultAgent instance.

Throws:
AbleException -

java.rmi.RemoteException -  

AbleEServerDefaultAgent

public AbleEServerDefaultAgent(java.lang.String theName)
                        throws com.ibm.able.AbleException,
                               java.rmi.RemoteException
Creates an AbleEServerDefaultAgent wrapped around an AblePlatformDefaultAgent instance with specified name.

Parameters:
theName - The name of this agent.

Throws:
RemoteException, - AbleException

AbleEServerDefaultAgent

public AbleEServerDefaultAgent(java.lang.String theName,
                               java.lang.String theComment)
                        throws com.ibm.able.AbleException,
                               java.rmi.RemoteException
Creates an AbleEServerDefaultAgent wrapped around an AblePlatformDefaultAgent instance with specified name and comment.

Parameters:
theName - The name of this agent.

theComment - The comment for this agent.

Throws:
RemoteException, - AbleException
Method Detail

setCapabilitySettings

public void setCapabilitySettings(java.util.Map theCapabilities,
                                  AbleSecureKey key)
                           throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Update the autonomy levels of this agent's capabilities according to the autonomy level settings in the passed in Map((Object)CapabiltiyIdentifier)->((Integer)autonomyLevel)

Specified by:
setCapabilitySettings in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
theCapabilities - Map of autonomy level settings.

key - AbleSecureKey used to secure communications.

Throws:
AbleException -

If the caller is not verified by the Naming Service.

If authorization failed.

If unable to update the capabilities of this agent.

java.rmi.RemoteException - On all remote errors.

setCapabilitySetting

public void setCapabilitySetting(java.lang.Object capabilityIdentifier,
                                 int autonomyLevel,
                                 AbleSecureKey key)
                          throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Sets the autonomy level of the one of this agent's capabilities.

Specified by:
setCapabilitySetting in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
capabilityIdentifier - The identifier of the capability whose autonomy level will be set.

autonomyLevel - The autonomy level this capability will be set to.

key - AbleSecureKey used to secure communications.

Throws:
AbleException -

If the caller is not verified by the VerifiableAgentNamingService.

If authorization failed.

If unable to update the capabilities of this agent.

java.rmi.RemoteException - On all remote errors.

getCapabilities

public java.util.HashMap getCapabilities()
                                  throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Get the HashMap of this agent's capabilites. ((Object)CapabiltiyIdentifier) -> ((AbleEServerCapability)Capability)

Specified by:
getCapabilities in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
A HashMap of this agent's capabilities.

Throws:
java.rmi.RemoteException - On all remote errors.

getCapabilitySettings

public java.util.HashMap getCapabilitySettings()
                                        throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Get the HashMap of this agent's capability settings ((Object)CapabiltiyIdentifier)->((Integer)autonomyLevel)

Specified by:
getCapabilitySettings in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
HashMap of this agent's capabilitySettings.

Throws:
java.rmi.RemoteException - On all remote errors.

getCapability

public AbleEServerCapability getCapability(java.lang.Object capabilityIdentifier)
                                    throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Get a specific capability of this agent.

Specified by:
getCapability in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
capabilityIdentifier - The identifier of the capability to return.

Returns:
The AbleEServerCapability requested.

Throws:
java.rmi.RemoteException - On all remote errors.

getCapabilityPresets

public java.util.HashMap[] getCapabilityPresets()
                                         throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Return an array of four HashMaps. Each HashMap will define the preset of the capabilities for this agent in this order: High, Medium, Low and 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 setting of the agent that did not match one of the three pre-defined presets.

Specified by:
getCapabilityPresets in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
HashMap[] of all the capability presets

Throws:
java.rmi.RemoteException - On all remote errors.

getCapabilitySettingsSummary

public com.ibm.able.AbleMessageContainer getCapabilitySettingsSummary(int autonomyLevel)
                                                               throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Return an AbleMessageContainer that describes the overall agent autonomy summary if the agent's autonomy level was set to autonomyLevel.

Specified by:
getCapabilitySettingsSummary in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
autonomyLevel - The autonomy level that you want the summary to represent.

Returns:
The capability setting summary string for the passed in autonomy level.

Throws:
AbleException - If unable to create the settings summary.

java.rmi.RemoteException - On all remote exceptions.

getCapabilitySettingsSummary

public com.ibm.able.AbleMessageContainer getCapabilitySettingsSummary(java.util.Map capabilitySettings)
                                                               throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Return a string that describes the overall agent autonomy summary if the agent's capability settings were set to capabilitySettings. If null, then the summary will be created against the current settings of this agent.

Specified by:
getCapabilitySettingsSummary in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
capabilitySettings - The capability settings that you want the summary to represent. (((Object)CapabiltiyIdentifier)->((Integer)autLevel))

Throws:
AbleException - If unable to create the settings summary.

java.rmi.RemoteException - On all remote exceptions.

getCapabilityOrder

public java.util.Vector getCapabilityOrder()
                                    throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
The order that an agent's AbleEServerCapabilities may be important. If so, a Vecotr may be set that lists the identifiers of the capabilities in the desired order. This method will return that Vector. If nothing is set, then the order is not important.

Specified by:
getCapabilityOrder in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
Vector containing the capability order.

Throws:
java.rmi.RemoteException - On all remote exceptions.

setAgentAutonomyLevel

public void setAgentAutonomyLevel(int agentAutonomyLevel,
                                  AbleSecureKey key)
                           throws com.ibm.able.AbleException,
                                  javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformAgent
Sets the agent's autonomy level.
Specified by:
setAgentAutonomyLevel in interface AblePlatformAgent
Overrides:
setAgentAutonomyLevel in class AblePlatformDefaultAgent
Following copied from interface: com.ibm.able.platform.AblePlatformAgent
Parameters:
theAgentAutonomyLevel - An autonomy level as defined in AblePlatform.

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

Throws:
java.rmi.RemoteException - On any RMI error.
com.ibm.able.AbleException - If the specified autonomy level isn't a level defined in AblePlatform or if the caller is not authorized.
javax.agent.service.naming.NamingException - If the caller is not authenticated.

getAutonomyLevel

public int getAutonomyLevel()
                     throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Return the autonomy level of this agent.

Specified by:
getAutonomyLevel in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
The autonomy level of this agent.

Throws:
java.rmi.RemoteException - On any remote error.

answerRequest

public final void answerRequest(AbleAgentSituationReport agentReport,
                                AbleSecureKey key)
                         throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
This method is called to answer a request that this agent had previously logged to the Logging Service.

The process of handling an answered request will be done in 4 steps.

Specified by:
answerRequest in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
agentReport - The original AbleAgentSituationReport containing an answer to the request.

key - The AbleSecureKey used to secure communication.

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.

java.rmi.RemoteException - On all remote errors.

getCustomizerResource

public byte[] getCustomizerResource(java.lang.String resourceName)
                             throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
Method getCustomizerResource. Internal remote method used by the remote admin console to get class files and resource files needed to display this agent's customizer panel. Since this method can return resource files as well as class files, it requires the type of file at the end of the resource name, like ".class" or ".auiml". Returns class files and resource files in a byte[].

Examples:

The default implementation looks for the files in the agent's local classpath. If not found, it returns null.

Specified by:
getCustomizerResource in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
resourceName -

Returns:
byte[]

Throws:
AbleException - If unable to read in the resource.

java.rmi.RemoteException - On all remote errors.

setCustomizerDataBean

public final void setCustomizerDataBean(java.lang.Object dataBean,
                                        AbleSecureKey key)
                                 throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
This is an internal version of _setCustomizerData(). Override _setCustomizerData() to receive a data bean from the console when the user is done with agent's customize panel.

Specified by:
setCustomizerDataBean in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Parameters:
dataBean -

key - AbleSecureKey used to secure communication

Throws:
AbleException -

If the caller is not verified by the Naming Service.

On all errors setting the customizer dataBean.

java.rmi.RemoteException - On all remote errors.

getCustomizerDataBean

public final byte[] getCustomizerDataBean()
                                   throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
This is an internal version of _getCustomizerDataBean(). Override _getCustomizerDataBean() to send a data bean that the console should use when it displays the agent's Customize panel. See the description of _getCustomizerDataBean() for more details.

Specified by:
getCustomizerDataBean in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
byte[] containing the data bean.

Throws:
AbleException -

On all errors getting the customizer dataBean.

On errors creating the byte[].

java.rmi.RemoteException - On all remote errors.

getAboutDataBean

public final byte[] getAboutDataBean()
                              throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
This is an internal version of _getAboutDataBean(). Override _getAboutDataBean() to send a data bean that the console should use when it displays the agent's About panel. See the description of _getAboutDataBean() for more details.

Specified by:
getAboutDataBean in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
byte[] containing the data bean.

Throws:
AbleException -

On all errors getting the About dataBean.

On errors creating the byte[].

java.rmi.RemoteException - On all remote errors.

getCustomizerInfo

public final java.lang.String[] getCustomizerInfo()
                                           throws com.ibm.able.AbleException
Description copied from interface: AbleEServerAgent
This is an internal version of the _getCustomizerInfo() method. Override that method to provide information about this agent's customizer panel. See the description of _getCustomizerInfo() for more details.

Specified by:
getCustomizerInfo in interface AbleEServerAgent
Following copied from interface: com.ibm.able.platform.AbleEServerAgent
Returns:
String[] with customizer info.

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

java.rmi.RemoteException - On all remote errors.

_init

protected void _init()
              throws com.ibm.able.AbleException
Initialize and configure the bean.
Overrides:
_init in class AblePlatformDefaultAgent
Following copied from class: com.ibm.able.platform.AblePlatformDefaultAgent
Throws:
AbleException - In any error situation.

_init

protected void _init(java.lang.Object capabilities)
              throws com.ibm.able.AbleException
Initialize and configure the bean. The parameter capabilities is expected to be the capabilities that this agent will be setup with when calling lclInit. If capabilities is not null it is expected to be an array of AbleEServerCapability Objects.

Overrides:
_init in class AblePlatformDefaultAgent
Parameters:
capabilities - If this is not null it is expected that this will contain an array of four Maps used to define the capabilities of this agent. The first would be the actual capabilities of the agent, and the next three would be set to highCapabilitySettings, mediumCapabilitySettings and lowCapabilitySettings respectivley.

Throws:
AbleException -

If the super init failed.

If the call to lclInit failed.


_quitAll

protected void _quitAll()
This method is overridden so this agent can remove all of its logs from the logging service if someone chose to quit this agent.

All exceptions are just logged and eaten since this is quit and it does not need to throw any exceptions.

Overrides:
_quitAll in class AblePlatformDefaultAgent

setAgentAutonomyLevel

protected void setAgentAutonomyLevel(int theAgentAutonomyLevel)
                              throws com.ibm.able.AbleException
This method is overridden to handle the updating of the capabilities when the agent's autonomy level is changed.

Overrides:
setAgentAutonomyLevel in class AblePlatformDefaultAgent
Throws:
AbleException -

On errors getting the autonomyLevel of this agent.

On errors updating the capabilities of this agent.

On errors updating the AgentDescription of this agent.

If the super setAgentAutonomyLevel(int) failed.


verifyCapabilities

protected void verifyCapabilities()
                           throws com.ibm.able.AbleException
All subclasses must define their own capabilities and their settings. This means that the capabilities, highCapabilitySettings, mediumCapabilitySettings and lowCapabilitySettings HashMaps must have been initialized.

This method is used to verify that this agent's capabilities settings are valid. The capabilities could be set in one of two ways.

  • By a subclass initializing and setting these four HashMaps.
By passing an AbleEServerCapability[] as the init arguments.

To be verified, the overall capabilities and three individual preset HashMaps 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 settings to make sure that they are valid.

Throws:
AbleException -

If any of the four capability HashMaps are null.

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

If the capability order Vector contains invalid or duplicate capabilities.


authenticateAndAuthorizeCaller

protected void authenticateAndAuthorizeCaller(AbleAgentSituationReport answeredAbleAgentSituationReport,
                                              AbleSecureKey key)
                                       throws com.ibm.able.AbleException
This is the default implementation of authenticateAndAuthorizeCaller and it does nothing. This method should be overridden by all subclasses that cares 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 AbleAgentSituationReport that is answering the request, and the VerifiableAgentName that sent this answer, it must decide if it will proceed with this answer.

Parameters:
answeredAbleAgentSituationReport - The answered AbleAgentSituationReport that this agent had previously logged.

key - The AbleSecureKey from the entity answering the request.

Throws:
AbleException - If caller failed to authenticate or authorize.

validateRequest

protected void validateRequest(AbleAgentSituationReport answeredAbleAgentSituationReport)
                        throws com.ibm.able.AbleException
This is the default implementation of validateRequest and it does nothing. This method should be overridden by all subclasses that have requests that may turn invalid after they 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 Logging Service, 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 answering of the request. Then the only way to notify the caller about anything is to log a history log.

Parameters:
answeredAbleAgentSituationReport - The answered AbleAgentSituationReport that this agent had previously logged.

Throws:
AbleException - If the request is no longer valid.

_answerRequest

protected void _answerRequest(AbleAgentSituationReport answeredAbleAgentSituationReport,
                              AbleSecureKey key)
This is the default implementation of _answerRequest and it does nothing. This method should be overridden by all subclasses. After the processing of an answered AbleAgentSituationReport has passed(Authentication, Validation, Authorization), the Asynchronous Delegation step will call this method to do the actual processing of the answered AbleAgentSituationReport.

This method will not throw any exceptions since this is on a different thread than the original answerRequest call. The only way to notify the caller of failures now is by logging to the Logging Service.

Parameters:
answeredAbleAgentSituationReport - The answered AbleAgentSituationReport that this agent had previously logged.

key - The AbleSecureKey that was used to answer this request.

authorizeCapabilityChangeRequest

protected void authorizeCapabilityChangeRequest(AbleSecureKey key)
                                         throws com.ibm.able.AbleException
This is the default implementation of authorizeCapabilityChangeRequest and it does nothing. This method should be overridden by all subclasses who will not allow everyone to change the capability settings of this agent. Based on the VerifiableAgentName that sent the change request, it must decide if it will make this change. This assumes the key has already been verified.

Parameters:
key - The AbleSecureKey from the entity attempting to make the change.

Throws:
AbleException -

If this capability change request is not authorized.


_setCustomizerDataBean

protected void _setCustomizerDataBean(java.lang.Object dataBean,
                                      AbleSecureKey key)
                               throws com.ibm.able.AbleException
Override this method to first handle authorization of this set request, and then to handle applying the data bean's properties to this agent. The user will enter values into the customizer panel on the client, and the AUIML data bean will get serialized and sent to this agent.

Parameters:
dataBean -

Throws:
AbleException - On all errors setting the customizer dataBean.

_getCustomizerDataBean

protected java.lang.Object _getCustomizerDataBean()
                                           throws com.ibm.able.AbleException
Override this method to return an AUIML DataBean to the ABLE console for the Customize panel. The Customize panel is an agent-specific AUIML panel that is used give the console user a way to set agent-specific properties. Here's the sequence of events: 1) User presses Customize... on the Properties panel 2) _getCustomizerInfo() is called. If null returned, it stops at this point. 3) _getCustomizerDataBean() called. If none returned, console creates a new instance of the data bean. 4) If the data bean also implements AbleRemotePanelDataBean, the databean's setUTM() method is called to give it a reference to the AUIML UserTaskManager object. 5) The data bean's load() method is called. 6) Console displays the Customize panel. 7) If user presses Ok button (button tied to AUIML COMPLETE action) the _setCustomizerDataBean() method is called to return the data bean with the user's settings to the agent. Implementing the data bean You can use the AUIML Builder to generate the initial code for the data bean. Once you have the code generated, you also have to implement the Serializable interface so the data bean can be sent to the console on a remote system. If you regenerate the data bean code, you have to add the Serializable again. You can also get a reference to the AUIML UserTaskManager object that is used to display the data bean by implementing the AbleRemotePanelDataBean interface. The one method on the interface, setUTM(), is then called before the data bean's load() method is called.
Returns:
Object (the data bean)
Throws:
AbleException - On any error getting the databean.

_getAboutDataBean

protected java.lang.Object _getAboutDataBean()
                                      throws com.ibm.able.AbleException
Override this method to return an AUIML DataBean to the ABLE console for the About panel. The About panel is an agent-specific AUIML panel that is used give the console user more information about the agent. Here's the sequence of events: 1) User presses About... 2) _getCustomizerInfo() is called. If null returned, it stops at this point. 3) _getAboutDataBean() called. If none returned, console creates a new instance of the data bean. 4) If the data bean also implements AbleRemotePanelDataBean, the databean's setUTM() method is called to give it a reference to the AUIML UserTaskManager object. 5) The data bean's load() method is called. 6) Console displays the About panel. Implementing the data bean You can use the AUIML Builder to generate the initial code for the data bean. Once you have the code generated, you also have to implement the Serializable interface so the data bean can be sent to the console on a remote system. If you regenerate the data bean code, you have to add the Serializable again. You can also get a reference to the AUIML UserTaskManager object that is used to display the data bean by implementing the AbleRemotePanelDataBean interface. The one method on the interface, setUTM(), is then called before the data bean's load() method is called.
Returns:
Object (the data bean)
Throws:
AbleException - On any error getting the databean.

_getCustomizerInfo

protected java.lang.String[] _getCustomizerInfo()
Returns info that the Admin GUI needs to display the Customizer and the About panels. You should override this method only if this agent has a Customizer or About panel. Here is the data that you need to return: --Return null for Strings 0,1, and 2 if there is no Customizer panel-- [0] - Name of Customizer AUIML file and resource bundle class. E.g.: "com.ibm.agent.CustomizerPanel" [1] - The Customizer data bean class to use with the AUIML panel. The _setCustomizerData() method should be expecting a class of this type. e.g.: "com.ibm.agent.CustomizerDataBean" [2] - Name of Customizer panel in auiml file. E.g.: "MainPanel" --The following three Strings are only required if there is an About panel-- [3] - Name of AUIML file that has the About panel. E.g.: "com.ibm.agent.AboutPanel" [4] - The About data bean class to use with the AUIML panel. E.g.: "com.ibm.agent.AboutDataBean" [5] - Name of About panel in auiml file. E.g.: "AboutPanel" Implementing the data bean You can use the AUIML Builder to generate the initial code for the data bean. Once you have the code generated, you also have to implement the Serializable interface so the data bean can be sent to the console on a remote system. If you regenerate the data bean code, you have to add the Serializable again. You can also get a reference to the AUIML UserTaskManager object that is used to display the data bean by implementing the AbleRemotePanelDataBean interface. The one method on the interface, setUTM(), is then called before the data bean's load() method is called.
Returns:
String [] - string array with info about About, Customizer panels

lclInit

protected void lclInit(java.lang.Object theCapabilities)
                throws com.ibm.able.AbleException
This method will perform some of the initial setup of this agent when it is first initialized(started). Mainly, a reference to the Logging Service will be made.

Subclasses should override this method to do their initial setup.

Parameters:
theCapabilities - If this is not null it is expected that this will contain an array of four Maps used to define the capabilities of this agent. The first would be actual capabilities of this agent, and the next three HashMaps would be highCapabilitySettings, mediumCapabilitySettings and lowCapabilitySettings respectivley.

Throws:
AbleException -

If a reference to the Logging Service could not be made.

If the capabilities were not properly setup.


logAbleAgentSituationReport

protected void logAbleAgentSituationReport(AbleAgentSituationReport theAbleAgentSituationReport)
                                    throws com.ibm.able.AbleException
This method will handle the details of logging an AbleAgentSituationReport to the Logging Service for this agent.

Parameters:
theAbleAgentSituationReport - The AbleAgentSituationReport 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.


updateAbleAgentSituationReport

protected void updateAbleAgentSituationReport(AbleAgentSituationReport oldAbleAgentSituationReport,
                                              AbleAgentSituationReport newAbleAgentSituationReprot)
                                       throws com.ibm.able.AbleException
This method will handle the details of updating one of this agent's AbleAgentSituationReports.

Parameters:
oldAbleAgentSituationReport - The AbleAgentSituationReport that is to be updated

newAbleAgentSituationReprot - The updated AbleAgentSituationReport.

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 removing the logs.


removeAbleAgentSituationReports

protected void removeAbleAgentSituationReports(java.util.Vector AbleAgentSituationReportsToRemove)
                                        throws com.ibm.able.AbleException
This method will handle the details of removing one of this agent's AbleAgentSituationReports.

Parameters:
AbleAgentSituationReportsToRemove - The AbleAgentSituationReports that are to be removed.

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 removing the logs.


logHistory

protected void logHistory(com.ibm.able.AbleMessageContainer description,
                          com.ibm.able.AbleMessageContainer action,
                          com.ibm.able.AbleMessageContainer summary)
                   throws com.ibm.able.AbleException
Helper method used to log a History log. A history log only needs three things, a description, action and summary.

Parameters:
description - A description of this event being logged

action - The action of this event being logged

summary - The summary of this event being logged.

Throws:
AbleException -

On errors logging to the Logging Service.

On errors getting the name of this agent.


createAbleAgentSituationReport

protected AbleAgentSituationReport createAbleAgentSituationReport(java.io.Serializable theIdentifier,
                                                                  AbleEServerCapability theCapability,
                                                                  AbleEServerSituation theSituation,
                                                                  com.ibm.able.AbleMessageContainer theSuggestedResponse,
                                                                  com.ibm.able.AbleMessageContainer theResponseTaken,
                                                                  com.ibm.able.AbleMessageContainer theResultsSummary,
                                                                  boolean theState)
                                                           throws com.ibm.able.AbleException
Helper method used to create an AbleAgentSituationReport for this agent.

This will fill the AbleAgentSituationReport 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().


makeCapabilitySettingsSummary

protected com.ibm.able.AbleMessageContainer makeCapabilitySettingsSummary(java.util.Map capabilitySettings)
                                                                   throws com.ibm.able.AbleException
Return an AbleMessage Container that describes the overall agent autonomy summary if the agent's capability settings were set to capabilitySettings.

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:
capabilitySettings - The capability settings that you want the summary to represent. (((Object)CapabilityIdentifier)->((Integer)autLevel))

Returns:
The capability setting summary string for the passed in capability settings.

Throws:
AbleException - If an invalid capability was set in capabilitySettings