com.ibm.able.platform
Interface AbleEServerAgent

All Superinterfaces:
AblePlatformAgent
All Known Implementing Classes:
AbleEServerDefaultAgent

public interface AbleEServerAgent
extends AblePlatformAgent

This class defines the base interface, or behavior, which all ABLE eServer agents must support. This is a subclass of AblePlatformAgent. What this class adds extra is capabilities, autonomy level, and logging support for both request and history logs.

Capabilities

When an AbleEServerAgent is created, it can contain a set of capabilities. These capabilites defines the behaviors and actions of an agent. If you created a storage monitor agent, it might contain a "Monitor DASD" or a "Monitor CPU" capability. Each capability can be set to one of three autonomy levels.

So with our previous capability examples, if the "Monitor DASD" capability was set to YES, it would take any action that it was programmed to take. It might go ahead and delete some log file once it saw that the DASD crossed a threshold. If it was set to ASK, it might send a request log to the Logging Service with possible actions it could take, and not take any action until a response came back. It it was set to NO, it might send a history log to the Logging Service with the situation it encountered, and the solution it recommended and continue without doing anything. These are the three autonomy levels a capability of an agent could be set too, and it is up to the programmer of the agent to decide how the agent will act at each level.

An agent will have some initial capability levels that it will default to. These level are meant to be changed to the user's preference for each agent. This interface also contains the methods to view and adjust these capability settings.

Autonomy Level

Each capability can be individually adjusted to the preferred autonomy level. The autonomy level of an agent defines the combined setting of all of it's capabilities. There are four autonomy levels defined in AblePlatform that an agent can be set to

Requests

When an agent encounters a situation for a capability where it needs outside advice to make a decision, it will log a request to the Logging Service. It will wait to take action until it's answerRequest method is called. This will take in the answer to a request that it had, and it will then decide if it should take that action.


Method Summary
 void answerRequest(AbleAgentSituationReport agentReport, AbleSecureKey key)
          This method is called to answer a request that this agent had previously logged to the Logging Service.
 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 capabilities)
          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.
 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().
 
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, setAgentAutonomyLevel, suspendAgent
 

Method Detail

setCapabilitySettings

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

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,
                                 java.rmi.RemoteException
Sets the autonomy level of the one of this agent's capabilities.

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 java.rmi.RemoteException
Get the HashMap of this agent's capabilites. ((Object)CapabiltiyIdentifier) -> ((AbleEServerCapability)Capability)

Returns:
A HashMap of this agent's capabilities.

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

getCapabilitySettings

public java.util.HashMap getCapabilitySettings()
                                        throws java.rmi.RemoteException
Get the HashMap of this agent's capability settings ((Object)CapabiltiyIdentifier)->((Integer)autonomyLevel)

Returns:
HashMap of this agent's capabilitySettings.

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

getCapability

public AbleEServerCapability getCapability(java.lang.Object capabilityIdentifier)
                                    throws java.rmi.RemoteException
Get a specific capability of this agent.

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 java.rmi.RemoteException
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.

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,
                                                                      java.rmi.RemoteException
Return an AbleMessageContainer that describes the overall agent autonomy summary if the agent's autonomy level was set to autonomyLevel.

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 capabilities)
                                                               throws com.ibm.able.AbleException,
                                                                      java.rmi.RemoteException
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.

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 java.rmi.RemoteException
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.

Returns:
Vector containing the capability order.

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

getAutonomyLevel

public int getAutonomyLevel()
                     throws java.rmi.RemoteException
Return the autonomy level of this agent.

Returns:
The autonomy level of this agent.

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

answerRequest

public void answerRequest(AbleAgentSituationReport agentReport,
                          AbleSecureKey key)
                   throws com.ibm.able.AbleException,
                          java.rmi.RemoteException
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.

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,
                                    java.rmi.RemoteException
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.

Parameters:
resourceName -

Returns:
byte[]

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

java.rmi.RemoteException - On all remote errors.

setCustomizerDataBean

public void setCustomizerDataBean(java.lang.Object dataBean,
                                  AbleSecureKey key)
                           throws com.ibm.able.AbleException,
                                  java.rmi.RemoteException
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.

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 byte[] getCustomizerDataBean()
                             throws com.ibm.able.AbleException,
                                    java.rmi.RemoteException
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.

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 byte[] getAboutDataBean()
                        throws com.ibm.able.AbleException,
                               java.rmi.RemoteException
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.

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 java.lang.String[] getCustomizerInfo()
                                     throws com.ibm.able.AbleException,
                                            java.rmi.RemoteException
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.

Returns:
String[] with customizer info.

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

java.rmi.RemoteException - On all remote errors.