OpenNMS API 1.2.8

org.opennms.netmgt.poller.nsclient
Class NsclientManager

java.lang.Object
  extended byorg.opennms.netmgt.poller.nsclient.NsclientManager

public class NsclientManager
extends java.lang.Object

This class is designed to be used by plugins, services and programs to perform checks against an NSClient service.

To use it you must first create an instance of the manager with the host, port and/or password. Then you can set the timeout for the socket, if you want to override DEFAULT_SOCKET_TIMEOUT. Once you have set up the manager, you call the init() method to connect to the service. Once connected you use the processCheckCommand() method to receive a NsclientPacket object containing the response and the result code. Here's an example of using this manager: NsclientCheckParams params = new NsclientCheckParams(critPerc, warnPerc, parameter); NsclientManager client = new NsclientManager(host.getHostAddress(), port); client.init(); NsclientPacket pack=client.processCheckCommand(NsclientManager.convertStringToType(command), params);

Author:
Matt Raykowski , OpenNMS

Field Summary
static short CHECK_CLIENTVERSION
          The ID for checking the remote client version.
static short CHECK_COUNTER
          The ID for checking the value of a remote Perfmon counter.
static short CHECK_CPULOAD
          The ID for checking the remote CPU usage.
static short CHECK_FILEAGE
          The ID for checking the age of a remote file.
static short CHECK_INSTANCES
          This check type is used by the NSClient developers as a utility for an easy remote method of looking up potential COUNTER instances.
static short CHECK_MEMUSE
          The ID for checking the state of the remote memory usage.
static short CHECK_NONE
          Default check type.
static short CHECK_PROCSTATE
          The ID for checking the state of a remote process.
static short CHECK_SERVICESTATE
          The ID for checking the state of a remote service.
static short CHECK_UPTIME
          The ID for checking the remote uptime.
static short CHECK_USEDDISKSPACE
          The ID for checking the remote used disk space.
static java.util.HashMap CheckStrings
          Stores the String -> CHECK_ id mappings for lookups.
static int DEFAULT_PORT
          The default NSClient TCP port.
static int DEFAULT_SOCKET_TIMEOUT
          The default socket timeout.
private  java.io.BufferedInputStream m_BufInStream
          This is used for receiving input from the server.
private  java.io.ByteArrayOutputStream m_ByteArrayOutStream
           
private  java.lang.String m_HostName
          Stores the host name the manager is connect(ing/ed) to.
private  java.lang.String m_Password
          The password to use when requesting a check.
private  int m_PortNumber
          Stores the port the manager is connect(ing/ed) to.
private  java.net.Socket m_Socket
          Stores the socket used to connect to the service.
private  int m_Timeout
           
 
Constructor Summary
private NsclientManager()
          Constructor.
  NsclientManager(java.lang.String host)
          Constructor.
  NsclientManager(java.lang.String host, int port)
          Constructor.
  NsclientManager(java.lang.String host, int port, java.lang.String pass)
          Constructor.
  NsclientManager(java.lang.String host, java.lang.String pass)
          Constructor.
 
Method Summary
private  NsclientPacket checkClientVersion(NsclientCheckParams param)
          This method performs a check of the client version on the remote service.
private  NsclientPacket checkCpuLoad(NsclientCheckParams param)
          This method is used to perform a check of the CPU percent in use it higher than the warning and critical percent thresholds.
private  NsclientPacket checkFileAge(NsclientCheckParams param)
          This method performs a check of a file's age as defined by the 'parameter' string.
private  NsclientPacket checkMemoryUsage(NsclientCheckParams param)
          This method performs a check of the memory space used on the remote server.
private  NsclientPacket checkPerfCounter(NsclientCheckParams param)
          This method performs a check of a perfmon object as defined by the 'parameter' string.
private  NsclientPacket checkProcState(NsclientCheckParams param)
          This method performs a check of the state of NT process on the remote service.
private  NsclientPacket checkServiceState(NsclientCheckParams param)
          This method performs a check of the state of NT services on the remote service.
private  NsclientPacket checkUptime(NsclientCheckParams param)
          This method simply performs a check of the uptime from the remove service and returns the results.
private  NsclientPacket checkUsedDiskSpace(NsclientCheckParams param)
          This method performs a check of the disk space available on the drive specified in the 'parameter' string.
 void close()
          Closes the socket.
static short convertStringToType(java.lang.String type)
          This method uses the CheckStrings HashMap to convert from a string to a short value.
static java.lang.String convertTypeToString(short type)
          This method uses CheckStrings to convert from a short value such as CHECK_CLIENTVERSION to the a string, for example "CLIENTVERSION"
 java.lang.String getHostName()
          Returns the host name being used to connect to the remote service.
 int getPortNumber()
          Returns the port being used to connect to the remote service.
 int getTimeout()
          Returns the TCP socket timeout used when connecting to the remote service.
 void init()
          This method creates a new socket and attempts to connect to the remote service.
private  java.lang.String prepList(java.lang.String list)
           
 NsclientPacket processCheckCommand(short type, NsclientCheckParams param)
          This method determines which check method to call to create a request, send to the server and process the results.
private  NsclientPacket sendCheckRequest(java.lang.String request)
          This method sends the request string to the remote service.
 void setHostName(java.lang.String host)
          This method is used to set the host name to connect to for performing remote service checks.
 void setPassword(java.lang.String pass)
          This method is used for setting the password used to perform service checks.
 void setPortNumber(int port)
          This method is used for overriding the port that is used to connect to the remote service.
 void setTimeout(int timeout)
          This method is used to set the TCP socket timeout to be used when connecting to the remote service.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_SOCKET_TIMEOUT

public static int DEFAULT_SOCKET_TIMEOUT
The default socket timeout.


DEFAULT_PORT

public static int DEFAULT_PORT
The default NSClient TCP port.


m_HostName

private java.lang.String m_HostName
Stores the host name the manager is connect(ing/ed) to.


m_PortNumber

private int m_PortNumber
Stores the port the manager is connect(ing/ed) to. Set to DEFAULT_PORT.


m_Password

private java.lang.String m_Password
The password to use when requesting a check. Default is "None"


m_Socket

private java.net.Socket m_Socket
Stores the socket used to connect to the service.


m_BufInStream

private java.io.BufferedInputStream m_BufInStream
This is used for receiving input from the server.


m_ByteArrayOutStream

private java.io.ByteArrayOutputStream m_ByteArrayOutStream

m_Timeout

private int m_Timeout

CHECK_NONE

public static final short CHECK_NONE
Default check type. Not supported.

See Also:
Constant Field Values

CHECK_CLIENTVERSION

public static final short CHECK_CLIENTVERSION
The ID for checking the remote client version.

See Also:
Constant Field Values

CHECK_CPULOAD

public static final short CHECK_CPULOAD
The ID for checking the remote CPU usage.

See Also:
Constant Field Values

CHECK_UPTIME

public static final short CHECK_UPTIME
The ID for checking the remote uptime.

See Also:
Constant Field Values

CHECK_USEDDISKSPACE

public static final short CHECK_USEDDISKSPACE
The ID for checking the remote used disk space.

See Also:
Constant Field Values

CHECK_SERVICESTATE

public static final short CHECK_SERVICESTATE
The ID for checking the state of a remote service.

See Also:
Constant Field Values

CHECK_PROCSTATE

public static final short CHECK_PROCSTATE
The ID for checking the state of a remote process.

See Also:
Constant Field Values

CHECK_MEMUSE

public static final short CHECK_MEMUSE
The ID for checking the state of the remote memory usage.

See Also:
Constant Field Values

CHECK_COUNTER

public static final short CHECK_COUNTER
The ID for checking the value of a remote Perfmon counter.

See Also:
Constant Field Values

CHECK_FILEAGE

public static final short CHECK_FILEAGE
The ID for checking the age of a remote file.

See Also:
Constant Field Values

CHECK_INSTANCES

public static final short CHECK_INSTANCES
This check type is used by the NSClient developers as a utility for an easy remote method of looking up potential COUNTER instances. This check type is not currently supported by this manager.

See Also:
Constant Field Values

CheckStrings

public static java.util.HashMap CheckStrings
Stores the String -> CHECK_ id mappings for lookups.

Constructor Detail

NsclientManager

public NsclientManager(java.lang.String host)
Constructor.

Parameters:
host - sets the host name to connect to.

NsclientManager

public NsclientManager(java.lang.String host,
                       int port)
Constructor. The password defaults to "None"

Parameters:
host - sets the host name to connect to.
port - sets the port number to connect using.

NsclientManager

public NsclientManager(java.lang.String host,
                       int port,
                       java.lang.String pass)
Constructor.

Parameters:
host - sets the host name to connect to.
port - sets the port number to connect using.
pass - sets the password to use when performing checks.

NsclientManager

public NsclientManager(java.lang.String host,
                       java.lang.String pass)
Constructor. The port number defaults to DEFAULT_PORT.

Parameters:
host - sets the host name to connect to.
pass - sets the password to use when performing checks.

NsclientManager

private NsclientManager()
Constructor. Made private to prevent construction without parameters.

Method Detail

convertTypeToString

public static java.lang.String convertTypeToString(short type)
This method uses CheckStrings to convert from a short value such as CHECK_CLIENTVERSION to the a string, for example "CLIENTVERSION"

Parameters:
type - the CHECK_ type to look up in the CheckStrings map.
Returns:
a string containing "NONE" if the short is not found in the map, or the string in the map that corresponds to type.
See Also:
CheckStrings, convertStringToType

convertStringToType

public static short convertStringToType(java.lang.String type)
This method uses the CheckStrings HashMap to convert from a string to a short value. For example if you passed "CLIENTVERSION" you would receive the value of CHECK_CLIENTVERSION in return.

Parameters:
type - A string to look up a CHECK_ value from the CheckStrings HashMap.
Returns:
a short id corresponding to the CHECK_ value that matches the string.
See Also:
CheckStrings, convertTypeToString

setPassword

public void setPassword(java.lang.String pass)
This method is used for setting the password used to perform service checks.

Parameters:
pass - the password to use when performing service checks.

setPortNumber

public void setPortNumber(int port)
This method is used for overriding the port that is used to connect to the remote service. This method must be called before calling the init() method or it will have no effect.

Parameters:
port - the remote service port.

getPortNumber

public int getPortNumber()
Returns the port being used to connect to the remote service.

Returns:
the port being used to connect to the remote service.
See Also:
init

setHostName

public void setHostName(java.lang.String host)
This method is used to set the host name to connect to for performing remote service checks. This method must be called before calling the init() method or it will have no effect.

Parameters:
host - the host name to connect to.
See Also:
init

getHostName

public java.lang.String getHostName()
Returns the host name being used to connect to the remote service.

Returns:
the host name being used to connect to the remote service.

setTimeout

public void setTimeout(int timeout)
This method is used to set the TCP socket timeout to be used when connecting to the remote service. This must be called before calling init or it will have no effect.

Parameters:
timeout - the TCP socket timeout.

getTimeout

public int getTimeout()
Returns the TCP socket timeout used when connecting to the remote service.

Returns:
the tcp socket timeout.

init

public void init()
          throws NsclientException
This method creates a new socket and attempts to connect to the remote service. The input and output streams are created after the socket is connected.

Throws:
NsclientException - if the hostname is unknown if the connection is refused if there is no route to the host if the host did not respond if there was an unexpected IO error. The thrown exception contains the causing exception.

close

public void close()
Closes the socket.


sendCheckRequest

private NsclientPacket sendCheckRequest(java.lang.String request)
                                 throws NsclientException
This method sends the request string to the remote service.

Parameters:
request - the request string to be sent to the remote service
Returns:
a NsclientPacket containing the response from the remote service.
Throws:
NsclientException - is thrown if there is an IO error with send/receiving to/from the socket.

processCheckCommand

public NsclientPacket processCheckCommand(short type,
                                          NsclientCheckParams param)
                                   throws NsclientException
This method determines which check method to call to create a request, send to the server and process the results. It merely determines the method to be called based on the type param.

Parameters:
type - the short ID of the type of check to be processed.
param - the object containing the parameters for performing checks on the respones from the remote service.
Returns:
the NsclientPacket as processed by the check command method that is called.
Throws:
NsclientException - this method rethrows NsclientExceptions caused by the check commands.

checkClientVersion

private NsclientPacket checkClientVersion(NsclientCheckParams param)
                                   throws NsclientException
This method performs a check of the client version on the remote service. From the NsclientCheckParams object passed to this method only the 'parameter' string is used, this contains the four digit version number which should be formatted like: 2.0.1.0 If the parameter does not contain for period delimited digits, the check will return the packet with with NsclientPacket.RES_STATE_UNKNOWN for a result code.

Parameters:
param - The param string member of this value contains the minimum client version.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkCpuLoad

private NsclientPacket checkCpuLoad(NsclientCheckParams param)
                             throws NsclientException
This method is used to perform a check of the CPU percent in use it higher than the warning and critical percent thresholds.

Parameters:
param - The param warning and critical percent members are used for validating CPU load results.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkUptime

private NsclientPacket checkUptime(NsclientCheckParams param)
                            throws NsclientException
This method simply performs a check of the uptime from the remove service and returns the results. No response validation is performed.

Parameters:
param - The param member is not currently in use.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkServiceState

private NsclientPacket checkServiceState(NsclientCheckParams param)
                                  throws NsclientException
This method performs a check of the state of NT services on the remote service. The services to check are contained in the 'parameter' string in a comma delimited format (that is prepared to the client format using the prepList method.) The default result code is NsclientPacket.RES_STATE_OK unless one of the services responds as 'Stopped' - in which case the result code is set to NsclientPacket.RES_STATE_CRIT

Parameters:
param - The param string member should contain a comma delimited list of NT services on the remote service.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkProcState

private NsclientPacket checkProcState(NsclientCheckParams param)
                               throws NsclientException
This method performs a check of the state of NT process on the remote service. The processes to check are contained in the 'parameter' string in a comma delimited format (that is prepared to the client format using the prepList method.) The default result code is NsclientPacket.RES_STATE_OK unless one of the processes responds as 'not running' - in which case the result code is set to NsclientPacket.RES_STATE_CRIT

Parameters:
param - The param string member should contain a comma delimited list of NT processes on the remote service.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkUsedDiskSpace

private NsclientPacket checkUsedDiskSpace(NsclientCheckParams param)
                                   throws NsclientException
This method performs a check of the disk space available on the drive specified in the 'parameter' string. The warning and critical thresholds defined by 'warningPercent' and 'criticalPercent' are used to validate the percent of used disk space.

Parameters:
param - The param string should contain a drive letter, warning and critical should contain non-zero percentages.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkMemoryUsage

private NsclientPacket checkMemoryUsage(NsclientCheckParams param)
                                 throws NsclientException
This method performs a check of the memory space used on the remote server. The warning and critical thresholds defined by 'warningPercent' and 'criticalPercent' are used to validate the percent of used memory.

Parameters:
param - The params warning and critical should contain non-zero percentages.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkPerfCounter

private NsclientPacket checkPerfCounter(NsclientCheckParams param)
                                 throws NsclientException
This method performs a check of a perfmon object as defined by the 'parameter' string. An example of this string would be: \Memory(_Total)\Pool Paged Bytes - the warning and crtical members of param will define thresholds used to validate the perfmon object value.

Parameters:
param - The param string should contain a perfmon OID, warning and critical should contain non-zero values.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

checkFileAge

private NsclientPacket checkFileAge(NsclientCheckParams param)
                             throws NsclientException
This method performs a check of a file's age as defined by the 'parameter' string.

Parameters:
param - The param string should contain a full path to a file, warning and critical should contain non-zero ages in minutes.
Returns:
the processed NsclientPacket.
Throws:
NsclientException - this method rethrows the exception thrown by sendCheckRequest

prepList

private java.lang.String prepList(java.lang.String list)

OpenNMS API 1.2.8

Generated by eevans on June 12 2006 2128.