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

## com.ibm.able.platform
Interface AgentLoggingService

All Superinterfaces:
  AblePlatformService, AblePlatformServiceEventGenerator, javax.agent.service.Service

All Known Implementing Classes:
  RmiAgentLoggingServiceProxy

public interface AgentLoggingService
extends javax.agent.service.Service, AblePlatformService

The AgentLoggingService interface defines the operations that can be requested of an ABLE platform Agent Logging Service.

The AgentLoggingService is used by agents and other entities of the platform to log ABLE Agent Situation Reports. These AgentSituationReports represent situations that agents encounter and for which they require a response or intervention. When AgentSituationReports are logged to the service, other agents or users at a platform console can view the situation reports listed in the logs and respond to them.

Agents can also log their history to the AgentLoggingService. This allows users at a console to view the history of any agent using the logging service.

Since:
  ABLE n.n.n

Field Summary
`static java.lang.String[]` | `COLUMN_NAMES` The column names in the table that this service uses for persistence.
`static java.lang.String[]` | `COLUMN_TYPES` The column types in the table that this service uses for persistence.
`static java.lang.String` | `HISTORY_LOG_MAX` This string represents a property that the AgentLoggingService expects to be defined in the ableplatform.preferences file.
`static java.lang.String` | `SERVICE_TYPE` The well-known service type, set to `"agent-logging-service"`.

Method Summary
`void` | `answerAgentRequest(AbleAgentSituationReport theAnsweredAgentSituationReport, AbleSecureKey theSecureKey)` When an attempt is made to answer an existing problem AgentSituationReport, this method takes the answered AgentSituationReport and contacts the original logger of the request.
`java.util.Vector` | `getAgentHistory(javax.agent.AgentName theAgentName)` Returns a list of all AgentSituationReports that belong to the specified agent and that are not in the problem state.
`java.util.Vector` | `getAgentProblems(javax.agent.AgentName theAgentName)` Returns a list of all AgentSituationReports that belong to the specified agent and that are in the problem state.
`java.util.Vector` | `getAllLogs()` Returns a list of all AgentSituationReports.
`java.util.Vector` | `getAllProblems()` Returns a list of all AgentSituationReports that are in the problem state.
`void` | `logAgentSituationReport(AbleAgentSituationReport theAgentSituationReport, AbleSecureKey theSecureKey)` Logs an AgentSituationReport to the AgentLoggingService, and notifies all interested listeners about the added entry.
`void` | `removeAgentLogs(javax.agent.AgentName theAgentName, AbleSecureKey theSecureKey)` Removes all of the AgentSituationReports that belong to the specified agent.
`void` | `removeAgentSituationReports(java.util.Vector theAgentSituationReportsToRemove, AbleSecureKey theSecureKey)` Removes AgentSituationReports from the AgentLoggingService, and notifies all interested listeners about these removals.
`java.util.Vector` | `search(AbleAgentSituationReport theSearchAgentSituationReport)` Returns a list of all AgentSituationReports that match the criteria supplied in the specified AgentSituationReport.
`void` | `updateAgentSituationReport(AbleAgentSituationReport theOldAgentSituationReport, AbleAgentSituationReport theReplacementAgentSituationReport, AbleSecureKey theSecureKey)` Updates an AgentSituationReport in the Logging Service, and notifies all interested listeners about this update.

Methods inherited from interface javax.agent.service.Service
`getServiceProperties, setServiceProperties`

Methods inherited from interface com.ibm.able.platform.AblePlatformService
`getState, terminateService`

Methods inherited from interface com.ibm.able.platform.AblePlatformServiceEventGenerator
`addAblePlatformServiceEventListener, getAblePlatformServiceEventListeners, removeAblePlatformServiceEventListener`

Field Detail

### SERVICE_TYPE

    public static final java.lang.String SERVICE_TYPE

  The well-known service type, set to `"agent-logging-service"`.

  See Also:
    Constant Field Values

### HISTORY_LOG_MAX

    public static final java.lang.String HISTORY_LOG_MAX

  This string represents a property that the AgentLoggingService expects to be defined in the ableplatform.preferences file.

  See Also:
    Constant Field Values

### COLUMN_NAMES

    public static final java.lang.String[] COLUMN_NAMES

  The column names in the table that this service uses for persistence.

### COLUMN_TYPES

    public static final java.lang.String[] COLUMN_TYPES

  The column types in the table that this service uses for persistence.

Method Detail

### logAgentSituationReport

    public void logAgentSituationReport(AbleAgentSituationReport theAgentSituationReport,
                                        AbleSecureKey theSecureKey)
                                 throws AgentLoggingException

  Logs an AgentSituationReport to the AgentLoggingService, and notifies all interested listeners about the added entry.

  If platform security is enabled, the log request proceeds only if the caller is authenticated.

  Logging of duplicate AgentSituationReports will fail.

  Parameters:
    `theAgentSituationReport` - The AgentSituationReport that is to be logged.
    `theSecureKey` - The AbleSecureKey that secures communication.
  Throws:
    `AgentLoggingException` -
    - If the AgentSituationReport to be logged is null.
    - If the caller is not authenticated.
    - If a duplicate AgentSituationReport is already logged.

### updateAgentSituationReport

    public void updateAgentSituationReport(AbleAgentSituationReport theOldAgentSituationReport,
                                           AbleAgentSituationReport theReplacementAgentSituationReport,
                                           AbleSecureKey theSecureKey)
                                    throws AgentLoggingException

  Updates an AgentSituationReport in the Logging Service, and notifies all interested listeners about this update.

  An AgentSituationReport can be updated only if it is in the problem state. History logs may never be changed.

  When platform security is enabled, an AgentSituationReport that is in the problem state can be updated only by its own VerifiableAgentName.

  This method call cannot be delegated. The VerifiableAgentName of the AgentSituationReport that is to be updated must directly make the call.

  Parameters:
    `theOldAgentSituationReport` - The AgentSituationReport that is to be updated.
    `theReplacementAgentSituationReport` - The AgentSituationReport that is to replace the old AgentSituationReport.
    `theSecureKey` - The AbleSecureKey that secures communication.
  Throws:
    `AgentLoggingException` -
    - If the updated AgentSituationReport is null.
    - If the caller is not authenticated.
    - If the report to be updated does not exist.
    - If the report being updated already exists.
    - If the report we are updating is a history log.
    - If the caller is not the one who originally logged the report being updated.

### removeAgentSituationReports

    public void removeAgentSituationReports(java.util.Vector theAgentSituationReportsToRemove,
                                            AbleSecureKey theSecureKey)
                                     throws AgentLoggingException

  Removes AgentSituationReports from the AgentLoggingService, and notifies all interested listeners about these removals.

  When platform security is enabled and the AgentSituationReport is verifiable, an AgentSituationReport in the problem state can be removed only by it own VerifiableAgentName; this method call cannot be delegated in such a case.

  An AgentSituationReport in the history state can be removed by anyone with equal or greater authority to the VerifiableAgentName of the AgentSituationReport. This call can be delegated in this case.

  Parameters:
    `theAgentSituationReportsToRemove` - A list of all AgentSituationReports that should be removed.
    `theSecureKey` - The AbleSecureKey that secures communication.
  Throws:
    `AgentLoggingException` -
    - If the specified list is null.
    - If an AgentSituationReport that is to be removed does not exist.
    - If the caller is not authenticated.
    - If attempting to remove a problem log and the caller is not the one who originally logged it.
    - If attempting to remove a history log and the caller does not have equal to or greater authority as the one who originally logged it.

### getAllLogs

    public java.util.Vector getAllLogs()
                                throws AgentLoggingException

  Returns a list of all AgentSituationReports.

  Returns:
    A list of all AgentSituationReports currently logged to this service.
  Throws:
    `AgentLoggingException` - on all remote errors.

### getAllProblems

    public java.util.Vector getAllProblems()
                                    throws AgentLoggingException

  Returns a list of all AgentSituationReports that are in the problem state.

  Returns:
    A list of all AgentSituationReports in the problem state.
  Throws:
    `AgentLoggingException` - on all remote errors.

### getAgentHistory

    public java.util.Vector getAgentHistory(javax.agent.AgentName theAgentName)
                                     throws AgentLoggingException

  Returns a list of all AgentSituationReports that belong to the specified agent and that are not in the problem state. These are the history logs.

  Parameters:
    `theAgentName` - The AgentName of the agent whose history logs are to be returned.
  Returns:
    A list of all history AgentSituationReports for the specified agent.
  Throws:
    `AgentLoggingException` - on all remote errors.

### getAgentProblems

    public java.util.Vector getAgentProblems(javax.agent.AgentName theAgentName)
                                      throws AgentLoggingException

  Returns a list of all AgentSituationReports that belong to the specified agent and that are in the problem state.

  Parameters:
    `theAgentName` - The AgentName of the agent whose problem logs are to be returned.
  Returns:
    All of the specified agent's problem AgentSituationReports.
  Throws:
    `AgentLoggingException` - on all remote errors.

### answerAgentRequest

    public void answerAgentRequest(AbleAgentSituationReport theAnsweredAgentSituationReport,
                                   AbleSecureKey theSecureKey)
                            throws AbleException,
                                   AgentLoggingException

  When an attempt is made to answer an existing problem AgentSituationReport, this method takes the answered AgentSituationReport and contacts the original logger of the request.

  Parameters:
    `theAnsweredAgentSituationReport` - The answered problem AgentSituationReport.
    `theSecureKey` - The key that is used to secure this communication.
  Throws:
    `AgentLoggingException` -
    - If the answered AgentSituationReport is null.
    - If the caller is not authenticated.
    - If the AgentSituationReport that is being answered does not exist.
    - If unable to locate the agent that originally logged the request.
    - If using a History log to answer a request.
    - On any remote error calling the agent.
    `AbleException` - On errors coming back from the agent.

### removeAgentLogs

    public void removeAgentLogs(javax.agent.AgentName theAgentName,
                                AbleSecureKey theSecureKey)
                         throws AgentLoggingException

  Removes all of the AgentSituationReports that belong to the specified agent.

  When platform security is enabed, this method can be called only by the actual agent that logged the reports. This method call cannot be delegated.

  Parameters:
    `theAgentName` - The AgentName of the agent that is to have all of it's AgentSituationReports removed.
    `theSecureKey` - The key that is used to secure this communication.
  Throws:
    `AgentLoggingException` -
    - If the `agentName` parameter is null.
    - If the caller is not authenticated.

### search

    public java.util.Vector search(AbleAgentSituationReport theSearchAgentSituationReport)
                            throws AgentLoggingException

  Returns a list of all AgentSituationReports that match the criteria supplied in the specified AgentSituationReport.

  If fields in the AgentSituationReport are left as null, a match can contain anything in this field. There is no way to wildcard the search for the state and timeSent fields since they are primitive types.

  Parameters:
    `theSearchAgentSituationReport` - The AgentSituationReport that contains the criteria for which to search.
  Returns:
    A list of all reports that match the supplied AgentSituationReport.
  Throws:
    `AgentLoggingException` - If the specified AgentSituationReport is null.

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

(C) Copyright IBM Corporation 1999, 2005