com.sap.aii.af.service.administration.api.monitoring

Interface MonitoringManager

public interface MonitoringManager

The MonitoringManager interface provides a means to report channel and process state transitions to the Adapter Framework.

An adapter invoking any of the methods in this interface needs to indicate this in advance to the Adapter Framework upon adapter registration by specifying the AdapterCapability.PUSH_CHANNEL_STATUS (for reporting the adapter's channel state through reportChannelStatus) and/or AdapterCapability.PUSH_PROCESS_STATUS (for reporting the adapter's process state through reportProcessStatus). It is perfectly valid to report a state multiple times in succession.

For sender channels, process status information reported via reportProcessStatus and a process state of ProcessState.FATAL will be used to supply alerting with state information. For receiver channels, alert generation is automatically handled by the Adapter Framework once the configurable number of retries has elapsed for a message without a successful delivery. In order to take full advantage of the alerting's capabilities it is recommended to invoke one of the reportProcessStatus variants, which take a ProcessContext container as argument and supply as many information as possible within that container.

If reporting channel state information via reportChannelStatus, an adapter must not register an implementation of the ChannelStatusCallback interface with the Adapter Framework.

An instance of this interface can be obtained using MonitoringManagerFactory.

Status Types
Two different status types can be reported by an adapter: The channel status as well as the process status. While the channel status is intended to provide general information about a channel's health status (i.e., whether the channel is configured correctly and the connection to its backend system is working), the process status is meant to provide a log of status information related to an adapter's message processing (i.e., when it accepts or creates a message, whether it has encountered any errors, etc.).
While currently no history for the channel status is kept by the Adapter Framework, a (limited) in-memory log of process status information is stored by the Adapter Framework. Consequently, it is advisable to provide a certain level of process status related information to the Adapter Framework, so that an end-user can correlate the process status information to the message processing when inspecting a chanel's process status history in the XI monitoring tools.
As a general guideline, a sender adapter should at least report the following process status information:

• start of processing
• message sent
• end of processing
• errors encountered
• polling-related information (polling adapters only)

A receiver adapter should at least report the following process status information:

• message processed
• errors encountered

Please note: For receiver adapters, the "start of processing" as well as "end of processing" events will be automatically reported by the Adapter Framework starting with PI 7.1 SP2; duplicate reporting from within the adapter should be avoided.

Reporting additional status information will make the processing flow more transparent for the end-user, but on the other hand cause older process status entries to be evicted from memory more quickly.

Localization
At the point in time state information is reported to the Adapter Framework via this interface, the display locale of the end user inspecting the status information in the monitoring UI (e.g., the Runtime Workbench) is typically unknown.
To overcome this limitation, the Adapter Framework supports a so-called LocalizationCallback. If the adapter registers an instance of this interface during adapter registration, this callback will be invoked for each string supplied to MonitoringManager before dis-playing it to the user. If using a ResourceBundle-based approach, one would probably supply resource bundle keys with the report(Channel|Process)Status calls and look up the localized text for these keys later during the localization callback's invocation.

Placeholder Substitution
Any textual information provided via the report(Channel|Process)Status methods can contain placeholders that will be filled with values supplied in an extra Object[] array. Any placeholders will be replaced after localization. For details, refer to the java.text.MessageFormat documentation.

Version:

$Id: //tc/xpi.af/710_SP_REL/src/_af_service/psrv/api/com/sap/aii/af/service/administration/api/monitoring/MonitoringManager.java#3 $

See Also:

AdapterCapability, LocalizationCallback, ChannelStatusCallback, MonitoringManagerFactory, ProcessState, MessageFormat

Method Summary

void	reportChannelStatus(String adapterNamespace, String adapterName, Channel[] channels, ChannelState state, String message) Reports a channel state for a set of channels.
void	reportChannelStatus(String adapterNamespace, String adapterName, Channel[] channels, ChannelState state, String message, Object[] messageParams) Reports a channel state for a set of channels.
void	reportChannelStatus(String adapterNamespace, String adapterName, Channel channel, ChannelState state, String message) Reports a channel state for a single channel.
void	reportChannelStatus(String adapterNamespace, String adapterName, Channel channel, ChannelState state, String message, Object[] messageParams) Reports a channel state for a single channel.
void	reportChannelStatus(String adapterNamespace, String adapterName, ChannelDirection direction, ChannelState state, String message) Reports a channel state for all channels of a given direction.
void	reportChannelStatus(String adapterNamespace, String adapterName, ChannelDirection direction, ChannelState state, String message, Object[] messageParams) Reports a channel state for all channels of a given direction.
void	reportProcessStatus(String adapterNamespace, String adapterName, ChannelDirection direction, ProcessState state, String message) Reports a process state.
void	reportProcessStatus(String adapterNamespace, String adapterName, ChannelDirection direction, ProcessState state, String message, Object[] messageParams) Reports a process state.
void	reportProcessStatus(String adapterNamespace, String adapterName, ChannelDirection direction, ProcessState state, String message, Object[] messageParams, ProcessContext context) Reports a process state.
void	reportProcessStatus(String adapterNamespace, String adapterName, ChannelDirection direction, ProcessState state, String message, ProcessContext context) Reports a process state.

Method Detail

reportChannelStatus

void reportChannelStatus(String adapterNamespace,
                         String adapterName,
                         ChannelDirection direction,
                         ChannelState state,
                         String message)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a channel state for all channels of a given direction. The state reported by invoking this method will be applied to all channels of the given direction, even those created in the future. However, the status can be overridden for individual cannels using the reportChannelStatus(String, String, Channel, ChannelState, String) or reportChannelStatus(String, String, Channel[], ChannelState, String) methods.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

direction - the direction identifying the channels affected by the state change

state - the new state

message - a description giving further details about the new state

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_CHANNEL_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_CHANNEL_STATUS

reportChannelStatus

void reportChannelStatus(String adapterNamespace,
                         String adapterName,
                         Channel channel,
                         ChannelState state,
                         String message)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a channel state for a single channel.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

channel - the channel affected by the state change

state - the new state

message - a description giving further details about the new state

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_CHANNEL_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_CHANNEL_STATUS

reportChannelStatus

void reportChannelStatus(String adapterNamespace,
                         String adapterName,
                         Channel[] channels,
                         ChannelState state,
                         String message)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a channel state for a set of channels.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

channels - the set of channels affected by the state change

state - the new state

message - a description giving further details about the new state

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_CHANNEL_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_CHANNEL_STATUS

reportChannelStatus

void reportChannelStatus(String adapterNamespace,
                         String adapterName,
                         ChannelDirection direction,
                         ChannelState state,
                         String message,
                         Object[] messageParams)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a channel state for all channels of a given direction. The state reported by invoking this method will be applied to all channels of the given direction, even those created in the future. However, the status can be overridden for individual cannels using the reportChannelStatus(String, String, Channel, ChannelState, String, Object[]) or reportChannelStatus(String, String, Channel[], ChannelState, String, Object[]) methods.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

direction - the direction identifying the channels affected by the state change

state - the new state

message - a description giving further details about the new state

messageParams - an array of objects that will be replaced in the provided details message following java.text.MessageFormat semantics

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_CHANNEL_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_CHANNEL_STATUS, MessageFormat

reportChannelStatus

void reportChannelStatus(String adapterNamespace,
                         String adapterName,
                         Channel channel,
                         ChannelState state,
                         String message,
                         Object[] messageParams)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a channel state for a single channel.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

channel - the channel affected by the state change

state - the new state

message - a description giving further details about the new state

messageParams - an array of objects that will be replaced in the provided details message following java.text.MessageFormat semantics

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_CHANNEL_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_CHANNEL_STATUS, MessageFormat

reportChannelStatus

void reportChannelStatus(String adapterNamespace,
                         String adapterName,
                         Channel[] channels,
                         ChannelState state,
                         String message,
                         Object[] messageParams)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a channel state for a set of channels.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

channels - the set of channels affected by the state change

state - the new state

message - a description giving further details about the new state

messageParams - an array of objects that will be replaced in the provided details message following java.text.MessageFormat semantics

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_CHANNEL_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_CHANNEL_STATUS, MessageFormat

reportProcessStatus

void reportProcessStatus(String adapterNamespace,
                         String adapterName,
                         ChannelDirection direction,
                         ProcessState state,
                         String message)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a process state.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

direction - the direction (sender or receiver) of the channel during whose processing the state is being reported

state - the new state

message - a description giving further details about the new state

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_PROCESS_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_PROCESS_STATUS

reportProcessStatus

void reportProcessStatus(String adapterNamespace,
                         String adapterName,
                         ChannelDirection direction,
                         ProcessState state,
                         String message,
                         ProcessContext context)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a process state.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

direction - the direction (sender or receiver) of the channel during whose processing the state is being reported

state - the new state

message - a description giving further details about the new state

context - a process context container holding optional details about the adapter's processing operation

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_PROCESS_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_PROCESS_STATUS

reportProcessStatus

void reportProcessStatus(String adapterNamespace,
                         String adapterName,
                         ChannelDirection direction,
                         ProcessState state,
                         String message,
                         Object[] messageParams)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a process state.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

direction - the direction (sender or receiver) of the channel during whose processing the state is being reported

state - the new state

message - a description giving further details about the new state

messageParams - an array of objects that will be replaced in the provided details message following java.text.MessageFormat semantics

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_PROCESS_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_PROCESS_STATUS, MessageFormat

reportProcessStatus

void reportProcessStatus(String adapterNamespace,
                         String adapterName,
                         ChannelDirection direction,
                         ProcessState state,
                         String message,
                         Object[] messageParams,
                         ProcessContext context)
                         throws AdapterNotRegisteredException,
                                AdapterCapabilityMismatchException

Reports a process state.

Parameters:

adapterNamespace - the namespace of the reporting adapter

adapterName - the name of the reporting adapter

direction - the direction (sender or receiver) of the channel during whose processing the state is being reported

state - the new state

message - a description giving further details about the new state

messageParams - an array of objects that will be replaced in the provided details message following java.text.MessageFormat semantics

context - a process context container holding optional details about the adapter's processing operation

Throws:

AdapterNotRegisteredException - if the adapter reporting the state change is not registered with the Adapter Framework

AdapterCapabilityMismatchException - if the adapter reporting the process state change did not specify the AdapterCapability.PUSH_PROCESS_STATUS capability during its registration

See Also:

AdapterCapability.PUSH_PROCESS_STATUS, MessageFormat