com.veraxsystems.icmp.ping
Class Ping

java.lang.Object
  extended by com.veraxsystems.icmp.ping.Ping

public class Ping
extends java.lang.Object

Ping is the class implementing the ICMP Echo request known as network "ping" functionality. Class is defined as static and requires initialization before it can be used init(). The ICMP communication is performed via IcmpJniBridge object that is created during initialization (only one such object is used for all echo requests). Class uses two internal threads for its activity. One reads ICMP application issued requests and sends ICMP echo messages while the second one reads responses and handles requests timeouts. At the end of using the release() method must be called to release resources especially ICMP socket. ICMP echo requests (pings) are sent asynchronously. Requests are issued by echo() method that has provided result handler executed either on request response or processing error. Obtaining error as result of operation means that either fatal error occurred or Ping class has been released. In such case further processing is not possible and Ping class must be re-initialized. All methods are synchronized to avoid sending echo during class initialization/releasing.


Constructor Summary
Ping()
           
 
Method Summary
static PingResult[] echo(java.net.InetAddress[] addresses, byte[] dataToSend, int timeout)
          Send the set of ICMP echo requests.
static PingResult[] echo(java.net.InetAddress[] addresses, int dataLength, int timeout)
          Send the set of default ICMP echo requests.
static int echo(java.net.InetAddress address, byte[] dataToSend, int timeoutVal, PingResponseHandler handler)
          Send ICMP echo request.
static int echo(java.net.InetAddress address, int dataLength, int timeoutVal, PingResponseHandler handler)
          Send default ICMP echo request.
static void init()
          Initialize Ping class.
static void release()
          Release resources allocated in init() method.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Ping

public Ping()
Method Detail

init

public static void init()
                 throws PingErrorException
Initialize Ping class. Three is created ICMP socket and started two processing threads - one for sending ICMP requests and second for receiving responses and timeouts handling. To release resources the release() method must be used. Without it allocated resources are not released.

Throws:
PingErrorException - issued when either initialization already has been done or other fatal error occurs (with socket creation or thread starting)

release

public static void release()
Release resources allocated in init() method. Method always succeeds. Eventual internal exceptions are either properly handled or logged using Logger.


echo

public static int echo(java.net.InetAddress address,
                       byte[] dataToSend,
                       int timeoutVal,
                       PingResponseHandler handler)
                throws PingErrorException
Send ICMP echo request. Operation is executed asynchronously and result is propagated using handler object. Because handled is invoked by separate thread (receiving thread) a handler must be properly synchronized. Ping class guarantees that for each request sent the handler will be called either on received response, on timeout or in case of error. The only error (exception) reported by method is issued when Ping class is not initialized.

Parameters:
address - IP address of host to send ICMP echo request
dataToSend - data to be send as part of ICMP message
timeoutVal - expressed in milliseconds time to wait for echo response
handler - asynchronous result handler
Returns:
identifier of echo message to be sent (the unique value on computer)
Throws:
PingErrorException - issued if Ping class is not initialized

echo

public static int echo(java.net.InetAddress address,
                       int dataLength,
                       int timeoutVal,
                       PingResponseHandler handler)
                throws PingErrorException
Send default ICMP echo request. Operation is executed asynchronously and result is propagated using handler object. Because handled is invoked by separate thread (receiving thread) a handler must be properly synchronized. Ping class guarantees that for each request sent the handler will be called either on received response, on timeout or in case of error. The only error (exception) reported by method is issued when Ping class is not initialized. Default data construction is based on Windows ping command behavior and contains string: "abc...w".

Parameters:
address - IP address of host to send ICMP echo request
dataLength - the length of default data to be sent
timeoutVal - expressed in milliseconds time to wait for echo response
handler - asynchronous result handler
Returns:
identifier of echo message to be sent (the unique value on computer)
Throws:
PingErrorException - issued if Ping class is not initialized

echo

public static PingResult[] echo(java.net.InetAddress[] addresses,
                                byte[] dataToSend,
                                int timeout)
                         throws PingErrorException
Send the set of ICMP echo requests. Method is executed synchronously and waits until all echo requests are finished. Internally, echo requests are send asynchronously - it means all requests are send immediately without waiting for responses (those, are handled in separate thread). Next, method waits until either all echo responses are received or timeouts occurs.

Each echo result is placed in array of results corresponding to addresses parameter (it means for each input host the result is placed in corresponding element of result array).

Each request timeout is calculated separately - it means that its calculation starts in the moment when request is sent (not when echo method is called). Such behavior leads to situation that echo execution lasts slightly longer than timeout specified.

Method reports exception when either Ping is not initialized or current thread is interrupted.

Parameters:
addresses - array of host addresses send ICMP echo requests
dataToSend - data to be send as part of ICMP message
timeout - expressed in milliseconds time to wait for echo response
Returns:
the array of results
Throws:
PingErrorException - issued if Ping class is not initialized or thread is interrupted

echo

public static PingResult[] echo(java.net.InetAddress[] addresses,
                                int dataLength,
                                int timeout)
                         throws PingErrorException
Send the set of default ICMP echo requests. Method is executed synchronously and waits until all echo requests are finished. Internally, echo requests are send asynchronously - it means all requests are send immediately without waiting for responses (those, are handled in separate thread). Next, method waits until either all echo responses are received or timeouts occurs.

Each echo result is placed in array of results corresponding to addresses parameter (it means for each input host the result is placed in corresponding element of result array).

Each request timeout is calculated separately - it means that its calculation starts in the moment when request is sent (not when echo method is called). Such behavior leads to situation that echo execution lasts slightly longer than timeout specified.

Method reports exception when either Ping is not initialized or current thread is interrupted. Default data construction is based on Windows ping command behavior and contains string: "abc...w".

Parameters:
addresses - array of host addresses send ICMP echo requests
dataLength - the length of default data to be sent
timeout - expressed in milliseconds time to wait for echo response
Returns:
the array of results
Throws:
PingErrorException - issued if Ping class is not initialized or thread is interrupted