com.ibm.able.platform
Class RmiAgentLoggingServiceProxy

java.lang.Object
  com.ibm.able.platform.RmiAgentLoggingServiceProxy

All Implemented Interfaces:

AblePlatformService, AblePlatformServiceEventGenerator, AgentLoggingService, java.io.Serializable, javax.agent.service.Service

public class RmiAgentLoggingServiceProxy

extends java.lang.Object

implements AgentLoggingService, java.io.Serializable

The RMIAgentLoggingServiceProxy is a proxy for the RMI implementation of the AgentLoggingService.

An RMI Agent Logging Service proxy contains a reference to an RMI version of an Agent Logging Service. The proxy contains methods identical to the methods in the actual service.

When a method is called on the proxy, the proxy forwards the call on to the actual service. However, the proxy:

• (1) traps all RemoteExceptions that might be thrown by the service.
• (2) turns the RemoteExceptions into AgentLoggingExceptions.
• (3) rethrows the new exception.

In this way, code making use of the proxy does not have to be sensitive to RMI RemoteExceptions and can code to a common Agent Logging Service interface.

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.ibm.able.platform.AgentLoggingService

COLUMN_NAMES, COLUMN_TYPES, HISTORY_LOG_MAX, SERVICE_TYPE

Constructor Summary

RmiAgentLoggingServiceProxy(RmiAgentLoggingService theDelegate, java.rmi.registry.Registry theRegistry, java.lang.String theAddress)
Creates a proxy over the specified RMI reference to an Agent Logging Service.

Method Summary

void	addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Adds a service event listener to this service.
void	answerAgentRequest(AbleAgentSituationReport theAgentSituationReport, 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	getAblePlatformServiceEventListeners() Gets a collection of all service event listeners registered with this service event generator.
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.
javax.agent.service.ServiceProperties	getServiceProperties() Retrieve the service properties of the underlying service.
int	getState() Returns the state of this service.
void	logAgentSituationReport(AbleAgentSituationReport theAgentSituationReport, AbleSecureKey theSecureKey) Logs an AgentSituationReport to the AgentLoggingService, and notifies all interested listeners about the added entry.
void	removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Removes a service event listener from this service.
void	removeAgentLogs(javax.agent.AgentName theAgentName, AbleSecureKey theSecureKey) Removes all of the AgentSituationReports that belong to the specified agent.
void	removeAgentSituationReports(java.util.Vector theAgentSituationReports, AbleSecureKey theSecureKey) Removes AgentSituationReports from the AgentLoggingService, and notifies all interested listeners about these removals.
java.util.Vector	search(AbleAgentSituationReport theAgentSituationReport) Returns a list of all AgentSituationReports that match the criteria supplied in the specified AgentSituationReport.
void	setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties) Set the service properties of the underlying service.
void	terminateService(AbleSecureKey theSecureKey) Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.
java.lang.String	toString() Retrieve a string describing (the contents of) the object.
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 class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RmiAgentLoggingServiceProxy

public RmiAgentLoggingServiceProxy(RmiAgentLoggingService theDelegate,
                                   java.rmi.registry.Registry theRegistry,
                                   java.lang.String theAddress)

Creates a proxy over the specified RMI reference to an Agent Logging Service.

Parameters:

theDelegate - A reference to an RMI version of an Agent Logging Service.

theRegistry - The RMI registry at which the above Agent Logging Service is registered.

theAddress - The RMI address at which the above Agent Logging Service is registered.

Method Detail

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Adds a service event listener to this service.

Specified by:

addAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

theListener - Any object interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be added is null, or on any error.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Removes a service event listener from this service.

Specified by:

removeAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

theListener - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be removed is null, or on any error.

getAblePlatformServiceEventListeners

public java.util.Vector getAblePlatformServiceEventListeners()
                                                      throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Gets a collection of all service event listeners registered with this service event generator.

Specified by:

getAblePlatformServiceEventListeners in interface AblePlatformServiceEventGenerator

Returns:

All registered AblePlatformServiceEventListener objects.

Throws:

AbleException - On any error.

terminateService

public void terminateService(AbleSecureKey theSecureKey)
                      throws AbleException,
                             javax.agent.service.naming.NamingException

Description copied from interface: AblePlatformService

Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.

Specified by:

terminateService in interface AblePlatformService

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 - On any remote error or Able error.

getState

public int getState()
             throws AbleException

Description copied from interface: AblePlatformService

Returns the state of this service.

Specified by:

getState in interface AblePlatformService

Returns:

The state of this service.

Throws:

AbleException - On any remote error or Able error.

logAgentSituationReport

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

Description copied from interface: AgentLoggingService

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.

Specified by:

logAgentSituationReport in interface AgentLoggingService

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

Description copied from interface: AgentLoggingService

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.

Specified by:

updateAgentSituationReport in interface AgentLoggingService

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 theAgentSituationReports,
                                        AbleSecureKey theSecureKey)
                                 throws AgentLoggingException

Description copied from interface: AgentLoggingService

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.

Specified by:

removeAgentSituationReports in interface AgentLoggingService

Parameters:

theAgentSituationReports - 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

Description copied from interface: AgentLoggingService

Returns a list of all AgentSituationReports.

Specified by:

getAllLogs in interface AgentLoggingService

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

Description copied from interface: AgentLoggingService

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

Specified by:

getAllProblems in interface AgentLoggingService

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

Description copied from interface: AgentLoggingService

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.

Specified by:

getAgentHistory in interface AgentLoggingService

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

Description copied from interface: AgentLoggingService

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

Specified by:

getAgentProblems in interface AgentLoggingService

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 theAgentSituationReport,
                               AbleSecureKey theSecureKey)
                        throws AbleException,
                               AgentLoggingException

Description copied from interface: AgentLoggingService

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.

Specified by:

answerAgentRequest in interface AgentLoggingService

Parameters:

theAgentSituationReport - 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

Description copied from interface: AgentLoggingService

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.

Specified by:

removeAgentLogs in interface AgentLoggingService

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 theAgentSituationReport)
                        throws AgentLoggingException

Description copied from interface: AgentLoggingService

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.

Specified by:

search in interface AgentLoggingService

Parameters:

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

getServiceProperties

public javax.agent.service.ServiceProperties getServiceProperties()

Retrieve the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; null is always returned.

Specified by:

getServiceProperties in interface javax.agent.service.Service

Returns:

null at all times.

setServiceProperties

public void setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties)

Set the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; the call is simply ignored.

Specified by:

setServiceProperties in interface javax.agent.service.Service

Parameters:

theServiceProperties - The service properties to be used by the service.

toString

public java.lang.String toString()

Retrieve a string describing (the contents of) the object.

Returns:

A String containing the current contents of the object.