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.