org.opennms.bb.dp.poller.plugins
Class ServiceMonitorICMP

java.lang.Object
  |
  +--org.opennms.bb.dp.poller.plugins.ServiceMonitorICMP
All Implemented Interfaces:
ServiceMonitor

public class ServiceMonitorICMP
extends Object
implements ServiceMonitor

This class is designed to be used by the service poller framework to test the availability of the ICMP service on remote interfaces. The class implements the ServiceMonitor interface that allows it to be used along with other plug-ins by the service poller framework.

The ICMP service monitor relies on the discovery process to generate the actual ICMP 'PING's. This monitor does NOT communicate with the ICMP daemon. The ICMP service monitor sends/receives XML/SOAP encoded poll requests/results to/from discovery via JSDT.

Version:
CVS $Revision: 1.4 $
Author:
OpenNMS

Inner Class Summary
private  class ServiceMonitorICMP.MonitorReplyConsumer
          The MonitorReplyConsumer class is responsible for handling incoming ICMP poll reply messages from discovery.
private static class ServiceMonitorICMP.RequestToSoapDocument
          This static class is used to build a compliant SOAP document that is sent to discovery in order to initiate a ICMP poll.
 
Field Summary
private static int DEFAULT_RETRY
          Default retries.
private static int DEFAULT_TIMEOUT
          Default timeout.
private static String JSDT_CLIENT_DISCOVER_RECEIVER_NAME
          This is the JSDT client name to whom the ICMP service monitor sends ICMP poll requests.
private static String JSDT_CLIENT_RECEIVER_NAME_PREFIX
          This is the prefix of the JSDT client name which will be used to receive ICMP poll results from discovery.
private static String JSDT_CLIENT_SENDER_NAME_PREFIX
          This is the prefix of the JSDT client name which will be used to send ICMP poll requests to discovery.
private  ServiceMonitorICMP.MonitorReplyConsumer m_consumer
          The consumer object is the final endpoint of data sent from the discovery to the service monitor.
private static int m_instanceCounter
          Static class counter which is incremented each time a new service monitor is constructed.
private  int m_instanceID
          Uniquely identifies a particular service monitor instance.
private  List m_interfaceList
          List of NetworkInterface objects associated with outstanding requests.
private  com.sun.media.jsdt.Channel m_replyChannel
          The JSDT channel through which ICMP poll results will be received from discovery.
private  com.sun.media.jsdt.Channel m_requestChannel
          The JSDT channel through which ICMP poll requests will be sent to discovery.
private  PollerClient m_requestClient
          The client that is joined to the monitor request channel of the discovery-monitor JSDT session.
private  com.sun.media.jsdt.Session m_session
          The JSDT session used for service monitor - discovery communication.
private static String SERVICE_NAME
          Name of monitored service.
private static String STATUS_KEY
           Used to store/access the status of the ICMP poll for a particular NetworkInterface.
private static String THREAD_KEY
           Used to store/access the thread object which is waiting on a poll response in the NetworkInterface's attributes.
 
Fields inherited from interface org.opennms.bb.dp.poller.plugins.ServiceMonitor
SERVICE_AVAILABLE, SERVICE_STATUS_MASK, SERVICE_UNAVAILABLE, SURPRESS_EVENT_MASK
 
Constructor Summary
ServiceMonitorICMP()
          Constructs a new ICMP service monitor object.
 
Method Summary
private static long convertTimeToLong(String valueToConvert)
          Converts the passed time string to a time value that is measured in milliseconds.
private static int getNextInstanceID()
          Increments and returns the next instance id value which can be used to distinguish between multiple instances of the service monitor.
 void initialize(ConfigurationProxy proxy, Properties parameters)
          Initialize the service monitor.
 void initialize(NetworkInterface iface)
          Called by the poller framework when an interface is being added to the scheduler.
private  void jsdtConnect()
          Creates JSDT channels for communication with discovery.
 int poll(NetworkInterface iface, EventProxy eproxy, Properties parameters)
          Poll the specified address for ICMP service availability.
 void release()
          Called by the poller framework when the plug-in is being unloaded.
 void release(NetworkInterface iface)
          Called by the poller framework when an interface is being removed from the scheduler.
 String serviceName()
          Returns the name of the service that the plug-in monitors ("ICMP").
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

SERVICE_NAME

private static final String SERVICE_NAME
Name of monitored service.

DEFAULT_RETRY

private static final int DEFAULT_RETRY
Default retries.

DEFAULT_TIMEOUT

private static final int DEFAULT_TIMEOUT
Default timeout. Specifies how long (in milliseconds) to block waiting for data from the monitored interface.

m_session

private com.sun.media.jsdt.Session m_session

The JSDT session used for service monitor - discovery communication.


m_requestChannel

private com.sun.media.jsdt.Channel m_requestChannel

The JSDT channel through which ICMP poll requests will be sent to discovery.


m_replyChannel

private com.sun.media.jsdt.Channel m_replyChannel

The JSDT channel through which ICMP poll results will be received from discovery.


m_requestClient

private PollerClient m_requestClient

The client that is joined to the monitor request channel of the discovery-monitor JSDT session.


JSDT_CLIENT_SENDER_NAME_PREFIX

private static final String JSDT_CLIENT_SENDER_NAME_PREFIX

This is the prefix of the JSDT client name which will be used to send ICMP poll requests to discovery. A numeric identifier which identifies the instance of the service monitor will be appended to make the name unique.


JSDT_CLIENT_RECEIVER_NAME_PREFIX

private static final String JSDT_CLIENT_RECEIVER_NAME_PREFIX

This is the prefix of the JSDT client name which will be used to receive ICMP poll results from discovery. A numeric identifier which identifies the instance of the service monitor will be appended to make the name unique.

WARNING: This value must match the prefix defined in the MonitorPinger class of discovery.

JSDT_CLIENT_DISCOVER_RECEIVER_NAME

private static final String JSDT_CLIENT_DISCOVER_RECEIVER_NAME

This is the JSDT client name to whom the ICMP service monitor sends ICMP poll requests. WARNING: This value must match the name defined in the MonitorRequestReceiver class of discovery.


m_instanceCounter

private static int m_instanceCounter

Static class counter which is incremented each time a new service monitor is constructed.


m_instanceID

private int m_instanceID
Uniquely identifies a particular service monitor instance. This id will be appended to the JSDT_CLIENT_*_NAME_PREFIX values to generate unique client names for each service monitor instance. Discovery will in turn use the JSDT sendToClient() call rather than the sendToOther() call so that only the service monitor that sent a particular poll request will receive the response.


m_consumer

private ServiceMonitorICMP.MonitorReplyConsumer m_consumer

The consumer object is the final endpoint of data sent from the discovery to the service monitor. The consumer receives messages from the session, through the channel. This class extends PollerClient so it is also a JSDT client.


m_interfaceList

private List m_interfaceList

List of NetworkInterface objects associated with outstanding requests. Each NetworkInterface object in the list will have a THREAD_KEY attribute which contains a reference to the blocked thread and a STATUS_KEY attribute which will be set to the result of the ICMP poll for that interface.


THREAD_KEY

private static final String THREAD_KEY

Used to store/access the thread object which is waiting on a poll response in the NetworkInterface's attributes.


STATUS_KEY

private static final String STATUS_KEY

Used to store/access the status of the ICMP poll for a particular NetworkInterface.

Constructor Detail

ServiceMonitorICMP

public ServiceMonitorICMP()
Constructs a new ICMP service monitor object. All the constructor does is obtain the next valid instance ID and assign it to m_instanceID. This value will be used to establish unique send/recv JSDT client names for each instance of the service monitor.
Method Detail

getNextInstanceID

private static int getNextInstanceID()
Increments and returns the next instance id value which can be used to distinguish between multiple instances of the service monitor.

jsdtConnect

private void jsdtConnect()
                  throws com.sun.media.jsdt.JSDTException

Creates JSDT channels for communication with discovery. Establishes in inbound channel with a consumer for handling incoming ICMP poll replies from discover and an outbound channel for sending ICMP poll requests.

If an error occurs then an exception will be thrown from the code. Be aware that this method will wait until a connection or fatal error occurs before returning control to the caller. Callers should make provisions to ensure that any locks that are held prior to calling jsdtConnect will not cause negative deadlock issues.

Throws:
com.sun.media.jsdt.JSDTException - thrown if the JSDT communication channel cannot be established or other error conditions occur.

serviceName

public String serviceName()

Returns the name of the service that the plug-in monitors ("ICMP").

Specified by:
serviceName in interface ServiceMonitor
Returns:
The service that the plug-in monitors.

initialize

public void initialize(ConfigurationProxy proxy,
                       Properties parameters)
                throws ServiceMonitorException

Initialize the service monitor.

Specified by:
initialize in interface ServiceMonitor
Parameters:
proxy - The object that can be used to load/save config information.
parameter - The parameters from the appropiate package(s).
Throws:
ServiceMonitorException - Thrown if an unrecoverable error occurs that prevents the plug-in from functioning.

release

public void release()
             throws ServiceMonitorException

Called by the poller framework when the plug-in is being unloaded. Any resources still being used by the monitor are released.

Specified by:
release in interface ServiceMonitor
Throws:
ServiceMonitorException - Thrown if an error occurs during deallocation.

initialize

public void initialize(NetworkInterface iface)
                throws ServiceMonitorException

Called by the poller framework when an interface is being added to the scheduler. Here we perform any necessary initialization to prepare the NetworkInterface object for polling.

Specified by:
initialize in interface ServiceMonitor
Parameters:
iface - The network interface to be added to the scheduler.
Throws:
ServiceMonitorException - Thrown if an unrecoverable error occurs that prevents the interface from being monitored.

release

public void release(NetworkInterface iface)
             throws ServiceMonitorException

Called by the poller framework when an interface is being removed from the scheduler. Here we free any resources or save any persistent information associated with the interface.

If an exception is thrown during the release the exception will be logged, but the interface will still be discarded for garbage collection.

Specified by:
release in interface ServiceMonitor
Parameters:
iface - The network interface that was being monitored.
Throws:
ServiceMonitorException - Thrown if an unrecoverable error occurs for the interface.

poll

public int poll(NetworkInterface iface,
                EventProxy eproxy,
                Properties parameters)
         throws ServiceMonitorException

Poll the specified address for ICMP service availability.

The ICMP service monitor relies on Discovery for the actual generation of IMCP 'ping' requests. A JSDT session with two channels (send/recv) is utilized for passing poll requests and receiving poll replies from discovery. All exchanges are SOAP/XML compliant.

Specified by:
poll in interface ServiceMonitor
Parameters:
iface - The network interface to test the service on.
eproxy - The event proxy object for sending custom events.
parameters - The package parameters (timeout, retry, etc...) to be used for this poll.
Returns:
The availibility of the interface and if a transition event should be supressed.

convertTimeToLong

private static long convertTimeToLong(String valueToConvert)
                               throws NumberFormatException

Converts the passed time string to a time value that is measured in milliseconds. The following extension are considered when converting the string:

ExtensionConversion Value
usMicroseconds
msMilliseconds
sSeconds
mMinutes
hHours
dDays

A number entered with out any units is considered to be in milliseconds.

Parameters:
valueToConvert - The string to convert to milliseconds.
Returns:
Returns the string converted to a millisecond value.
Throws:
NumberFormatException - Thrown if the string is malformed and a number cannot be extracted from the value.