com.amx.duet.tools.net.snmp
Class SNMPConnection

java.lang.Object
  extended bycom.amx.duet.tools.net.snmp.SNMPConnection
All Implemented Interfaces:
java.lang.Runnable

public class SNMPConnection
extends java.lang.Object
implements java.lang.Runnable

The SNMPConnection class is a wrapper around all of the basic SNMP operations. It can be used to perform operations such as GET, GETNEXT, and SET. Each operation runs in its own thread, but the class itself has been throttled back to work as if each thread were one. In otherwords, the class will not allow you to perform another operation until the previous operation is complete. The reason behind this is because each SNMP operation performs its request and response action in a single instance. Thus, the request is not complete until the agent has finished responding, which stalls all other processes on the master.

 // This is an example of how to create the connection object
 connection = new SNMPConnection("10.0.0.10", "1.3.6.1.4", "public", this);
 connection.setDebugState(DEBUG);
 
 // Here is an operation example using the connection object
 if (!connection.isBusy())
 {
 	// Get object at "1.3.6.1.4.1.9.3.3.1"
 	connection.getMIBEntry("1.9.3.3.1");
 }
 
 // This is an example of how to handle the response in the implementing listener 
 public void handleSNMPReceive(SNMPObjectIdentifier itemID, SNMPObject snmpValue)
 {
 	String OID = "";
 	if (itemID != null)
 	{
 		OID = "." + itemID.toString();
 		if (OID.startsWith(connection.getEnterpriseID()))
 		{
 			// Remove "1.3.6.1.4" (Enterprise OID) from OID string
 		}
 	}
 
 	try
 	{
 		String data = snmpValue.toString();
 		this.processPassBackEvent(new ModuleComponentEvent(this, itemID + "," + data, 1));
 		if (OID.equals("1.9.3.3.1"))
 		{
 			// Do feedback processing...
 		}
 	}
 }
 


Field Summary
static int CLOSED
           
static int CONNECTED
           
static int DT_COUNTER32
           
static int DT_COUNTER64
           
static int DT_GAUGE
           
static int DT_INTEGER
           
static int DT_IPADDRESS
           
static int DT_MACADDRESS
           
static int DT_MIBTABLE
           
static int DT_OBJECTID
           
static int DT_OCTETSTRING
           
static int DT_TIMETICKS
           
static int DT_UINTEGER32
           
static int FAILED_CONNECT
           
static int FAILED_GET
           
static int FAILED_SET
           
static int INFINITE
           
static int INVALID_HOST
           
static int INVALID_OID
           
static int NONE
           
static int OP_GET
           
static int OP_GETNEXT
           
static int OP_SET
           
static int TIMEOUT
           
static int UNKNOWN_ERROR
           
 
Constructor Summary
SNMPConnection()
          Default constructor
SNMPConnection(java.net.InetAddress hostAddress, java.lang.String deviceMakeOID, java.lang.String community, SNMPConnectionListener listener)
          Setup the SNMP connection with initial values using the default SNMP version (latest supported).
SNMPConnection(int version, java.net.InetAddress hostAddress, java.lang.String deviceMakeOID, java.lang.String community, SNMPConnectionListener listener)
          Setup the SNMP connection with all initial values.
SNMPConnection(int version, java.lang.String hostAddress, java.lang.String deviceMakeOID, java.lang.String community, SNMPConnectionListener listener)
          Setup the SNMP connection with initial values using a String IP address.
SNMPConnection(java.lang.String hostAddress, java.lang.String deviceMakeOID, java.lang.String community, SNMPConnectionListener listener)
          Setup the SNMP connection with initial values using the default SNMP version (latest supported) and a String IP address.
 
Method Summary
static java.lang.String dataTypeToString(int dataType)
          Converts a data type constant to it's equivalent string representation.
 void dispose()
          Cleans up the connection.
 int getDebugState()
          Gets the current diagnostic state.
 java.lang.String getEnterpriseID()
          Retrieves the device's company Object Identifier in a String object.
 void getMIBEntry(java.lang.String itemID)
          This operation is used to retrieve the value of an object instance from an SNMP agent (device).
 void getMIBEntry(java.lang.String[] itemIDs)
          This operation is used to retrieve the value of an object instance from an SNMP agent (device).
 void getNextMIBEntry(java.lang.String itemID)
          This operation is used to retrieve the NEXT value of an object instance, after a GET was called, from an SNMP agent (device).
 void getNextMIBEntry(java.lang.String[] itemIDs)
          This operation is used to retrieve the NEXT value of an object instance, after a GET was called, from an SNMP agent (device).
 void initConnection(int version, java.net.InetAddress hostAddress, java.lang.String deviceMakeOID, java.lang.String community, SNMPConnectionListener listener)
          Use this method to initialize the SNMP connection with initial values if created using the default constructor.
 void initConnection(int version, java.lang.String hostAddress, java.lang.String deviceMakeOID, java.lang.String community, SNMPConnectionListener listener)
          Use this method to initialize the SNMP connection with initial values if created using the default constructor.
 boolean isBusy()
          Checks to see if an operation is currently in progress.
static java.lang.String oidToString(SNMPObjectIdentifier oid)
          Converts an SNMPObjectIdentifier to a String object.
static java.lang.String[] oidToString(SNMPObjectIdentifier[] oids)
          Converts an array SNMPObjectIdentifier to an array of String objects.
static java.lang.String operationToString(int oper)
          Converts an operation type constant to it's equivalent string representation.
 void run()
           
 void setCommunityAccess(java.lang.String community)
          Defines the access environment for a group of Network Management Systems.
 void setCounter64Value(java.lang.String itemID, long value)
          This operation is used to set the 64 BIT COUNTER value of an object instance on an SNMP agent (device).
 void setCounterValue(java.lang.String itemID, long value)
          This operation is used to set the 32 BIT COUNTER value of an object instance on an SNMP agent (device).
 void setDebug(boolean bState)
          Deprecated. Do not use this method; use setDebugState instead
 void setDebugState(int nState)
          Puts the class into a debug diagnostic state.
 boolean setEnterpriseID(java.lang.String makeOID)
          Defines the device's company Object Identifier.
 void setGuageValue(java.lang.String itemID, long value)
          This operation is used to set the GUAGE value of an object instance on an SNMP agent (device).
 void setHostAddress(java.net.InetAddress hostAddress)
          Sets the internet address for the host you are trying to connect to.
 void setHostAddress(java.lang.String hostAddress)
          Sets the internet address for the host you are trying to connect to.
 void setIntValue(java.lang.String itemID, int value)
          This operation is used to set the INTEGER value of an object instance on an SNMP agent (device).
 void setIntValue(java.lang.String itemID, long value)
          This operation is used to set the INTEGER value of an object instance on an SNMP agent (device).
 void setIPAddressValue(java.lang.String itemID, java.lang.String value)
          This operation is used to set the IP ADDRESS value of an object instance on an SNMP agent (device).
 void setMACAddressValue(java.lang.String itemID, java.lang.String value)
          This operation is used to set the MAC ADDRESS value of an object instance on an SNMP agent (device).
 void setMIBEntry(java.lang.String[] itemIDs, SNMPObject[] newValues, int dataType)
          This operation is used to set the value of an object instance on an SNMP agent (device).
 void setMIBEntry(java.lang.String itemID, SNMPObject newValue, int dataType)
          This operation is used to set the value of an object instance on an SNMP agent (device).
 void setMIBEntry(java.lang.String itemID, java.lang.String value, int dataType)
          This operation is used to set the value of an object instance on an SNMP agent (device).
 void setSNMPVersion(int version)
          Set the current SNMP version to use for communications
 void setStringValue(java.lang.String itemID, java.lang.String value)
          This operation is used to set the OCTET STRING value of an object instance on an SNMP agent (device).
 void setTimeTicksValue(java.lang.String itemID, long value)
          This operation is used to set the TIME TICK value of an object instance on an SNMP agent (device).
 void setUIntValue(java.lang.String itemID, long value)
          This operation is used to set the UNSIGNED INTEGER value of an object instance on an SNMP agent (device).
static int stringToDataType(java.lang.String str)
          Converts a data type string representation to its equivalent contant value.
 java.lang.String validateOID(java.lang.String oid)
          Validates the OID string passed in.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONNECTED

public static final int CONNECTED
See Also:
Constant Field Values

TIMEOUT

public static final int TIMEOUT
See Also:
Constant Field Values

CLOSED

public static final int CLOSED
See Also:
Constant Field Values

INVALID_HOST

public static final int INVALID_HOST
See Also:
Constant Field Values

FAILED_CONNECT

public static final int FAILED_CONNECT
See Also:
Constant Field Values

FAILED_GET

public static final int FAILED_GET
See Also:
Constant Field Values

FAILED_SET

public static final int FAILED_SET
See Also:
Constant Field Values

UNKNOWN_ERROR

public static final int UNKNOWN_ERROR
See Also:
Constant Field Values

INVALID_OID

public static final int INVALID_OID
See Also:
Constant Field Values

INFINITE

public static final int INFINITE
See Also:
Constant Field Values

NONE

public static final int NONE
See Also:
Constant Field Values

OP_GET

public static final int OP_GET
See Also:
Constant Field Values

OP_GETNEXT

public static final int OP_GETNEXT
See Also:
Constant Field Values

OP_SET

public static final int OP_SET
See Also:
Constant Field Values

DT_INTEGER

public static final int DT_INTEGER
See Also:
Constant Field Values

DT_UINTEGER32

public static final int DT_UINTEGER32
See Also:
Constant Field Values

DT_GAUGE

public static final int DT_GAUGE
See Also:
Constant Field Values

DT_COUNTER32

public static final int DT_COUNTER32
See Also:
Constant Field Values

DT_COUNTER64

public static final int DT_COUNTER64
See Also:
Constant Field Values

DT_TIMETICKS

public static final int DT_TIMETICKS
See Also:
Constant Field Values

DT_OCTETSTRING

public static final int DT_OCTETSTRING
See Also:
Constant Field Values

DT_IPADDRESS

public static final int DT_IPADDRESS
See Also:
Constant Field Values

DT_MACADDRESS

public static final int DT_MACADDRESS
See Also:
Constant Field Values

DT_OBJECTID

public static final int DT_OBJECTID
See Also:
Constant Field Values

DT_MIBTABLE

public static final int DT_MIBTABLE
See Also:
Constant Field Values
Constructor Detail

SNMPConnection

public SNMPConnection()
Default constructor


SNMPConnection

public SNMPConnection(int version,
                      java.net.InetAddress hostAddress,
                      java.lang.String deviceMakeOID,
                      java.lang.String community,
                      SNMPConnectionListener listener)
Setup the SNMP connection with all initial values.

Parameters:
version - [1..2] SNMP version
hostAddress - (InetAddress) Address to connect to.
deviceMakeOID - Identifies the type of managed object (Enterprise OID)
community - Defines the access environment for a group of NMSs
listener - Object which will receive SNMP events.

SNMPConnection

public SNMPConnection(int version,
                      java.lang.String hostAddress,
                      java.lang.String deviceMakeOID,
                      java.lang.String community,
                      SNMPConnectionListener listener)
Setup the SNMP connection with initial values using a String IP address.

Parameters:
version - [1..2] SNMP version
hostAddress - (String) Address to connect to.
deviceMakeOID - Identifies the type of managed object (Enterprise OID)
community - Defines the access environment for a group of NMSs
listener - Object which will receive SNMP events.

SNMPConnection

public SNMPConnection(java.net.InetAddress hostAddress,
                      java.lang.String deviceMakeOID,
                      java.lang.String community,
                      SNMPConnectionListener listener)
Setup the SNMP connection with initial values using the default SNMP version (latest supported).

Parameters:
hostAddress - (InetAddress) Address to connect to.
deviceMakeOID - Identifies the type of managed object (Enterprise OID)
community - Defines the access environment for a group of NMSs
listener - Object which will receive SNMP events.

SNMPConnection

public SNMPConnection(java.lang.String hostAddress,
                      java.lang.String deviceMakeOID,
                      java.lang.String community,
                      SNMPConnectionListener listener)
Setup the SNMP connection with initial values using the default SNMP version (latest supported) and a String IP address.

Parameters:
hostAddress - (String) Address to connect to.
deviceMakeOID - Identifies the type of managed object (Enterprise OID)
community - Defines the access environment for a group of NMSs
listener - Object which will receive SNMP events.
Method Detail

initConnection

public void initConnection(int version,
                           java.lang.String hostAddress,
                           java.lang.String deviceMakeOID,
                           java.lang.String community,
                           SNMPConnectionListener listener)
Use this method to initialize the SNMP connection with initial values if created using the default constructor.

Parameters:
version - [1..2] SNMP version
hostAddress - (String) Address to connect to.
deviceMakeOID - Identifies the type of managed object (Enterprise OID)
community - Defines the access environment for a group of NMSs
listener - Object which will receive SNMP events.

initConnection

public void initConnection(int version,
                           java.net.InetAddress hostAddress,
                           java.lang.String deviceMakeOID,
                           java.lang.String community,
                           SNMPConnectionListener listener)
                    throws java.lang.IllegalArgumentException
Use this method to initialize the SNMP connection with initial values if created using the default constructor.

Parameters:
version - [1..2] SNMP version
hostAddress - (InetAddress) Address to connect to.
deviceMakeOID - Identifies the type of managed object (Enterprise OID)
community - Defines the access environment for a group of NMSs
listener - Object which will receive SNMP events.
Throws:
java.lang.IllegalArgumentException

setSNMPVersion

public void setSNMPVersion(int version)
Set the current SNMP version to use for communications

Parameters:
version - [1..2]

setHostAddress

public void setHostAddress(java.lang.String hostAddress)
Sets the internet address for the host you are trying to connect to.

Parameters:
hostAddress - String containing the host address.

setHostAddress

public void setHostAddress(java.net.InetAddress hostAddress)
Sets the internet address for the host you are trying to connect to.

Parameters:
hostAddress - InetAddress containing the host address.

setCommunityAccess

public void setCommunityAccess(java.lang.String community)
Defines the access environment for a group of Network Management Systems. NMSs within the community are said to exist within the same administrative domain. Community names serve as a weak form of authentication because devices that do not know the proper community name are precluded from SNMP operations.

Parameters:
community - String containing message group access.

setEnterpriseID

public boolean setEnterpriseID(java.lang.String makeOID)
Defines the device's company Object Identifier. The company OID should be the prefix used for every OID used in the device's list of managed objects in its MIB hierarchy.

The MIB hierarchy can be depicted as a tree with a nameless root, the levels of which are assigned by different organizations. Vendors usually define private branches that include managed objects for their products. The level prior to the products branch is the company's OID.

Example:

 If the OID to get to a device variable looked like this:
 
 1.3.6.1.4.1.9.3.3.1
 
 The product OID might be:
 
 1.3.6.1.4.1.9.3
 
 And the company OID might be:
 
 1.3.6.1.4
 
 The call should look like this:
 boolean success = setEnterpriseID("1.3.6.1.4");
 
Basically, the company OID is the prefix ID for the product ID and the product ID is the prefix for the variable OID.

Parameters:
makeOID - String containing the company OID.
Returns:
true if the OID was valid; false otherwise.

getEnterpriseID

public java.lang.String getEnterpriseID()
Retrieves the device's company Object Identifier in a String object.

Returns:
String containing the company OID.

getMIBEntry

public void getMIBEntry(java.lang.String itemID)
This operation is used to retrieve the value of an object instance from an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).

getNextMIBEntry

public void getNextMIBEntry(java.lang.String itemID)
This operation is used to retrieve the NEXT value of an object instance, after a GET was called, from an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).

getMIBEntry

public void getMIBEntry(java.lang.String[] itemIDs)
This operation is used to retrieve the value of an object instance from an SNMP agent (device).


getNextMIBEntry

public void getNextMIBEntry(java.lang.String[] itemIDs)
This operation is used to retrieve the NEXT value of an object instance, after a GET was called, from an SNMP agent (device).


setMIBEntry

public void setMIBEntry(java.lang.String itemID,
                        SNMPObject newValue,
                        int dataType)
This operation is used to set the value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
newValue - Value to be updated
dataType - Data type of the value to be updated

setMIBEntry

public void setMIBEntry(java.lang.String itemID,
                        java.lang.String value,
                        int dataType)
This operation is used to set the value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
dataType - Data type of the value to be updated

setIntValue

public void setIntValue(java.lang.String itemID,
                        int value)
This operation is used to set the INTEGER value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setIntValue

public void setIntValue(java.lang.String itemID,
                        long value)
This operation is used to set the INTEGER value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setUIntValue

public void setUIntValue(java.lang.String itemID,
                         long value)
This operation is used to set the UNSIGNED INTEGER value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setGuageValue

public void setGuageValue(java.lang.String itemID,
                          long value)
This operation is used to set the GUAGE value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setCounterValue

public void setCounterValue(java.lang.String itemID,
                            long value)
This operation is used to set the 32 BIT COUNTER value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setCounter64Value

public void setCounter64Value(java.lang.String itemID,
                              long value)
This operation is used to set the 64 BIT COUNTER value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setTimeTicksValue

public void setTimeTicksValue(java.lang.String itemID,
                              long value)
This operation is used to set the TIME TICK value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setStringValue

public void setStringValue(java.lang.String itemID,
                           java.lang.String value)
This operation is used to set the OCTET STRING value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setIPAddressValue

public void setIPAddressValue(java.lang.String itemID,
                              java.lang.String value)
This operation is used to set the IP ADDRESS value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setMACAddressValue

public void setMACAddressValue(java.lang.String itemID,
                               java.lang.String value)
This operation is used to set the MAC ADDRESS value of an object instance on an SNMP agent (device).

Parameters:
itemID - String containing the OID of the data to access (you do not need to include the Enterprise ID).
value - Value to be updated

setMIBEntry

public void setMIBEntry(java.lang.String[] itemIDs,
                        SNMPObject[] newValues,
                        int dataType)
This operation is used to set the value of an object instance on an SNMP agent (device).

Parameters:
dataType - Data type of the values to be updated

validateOID

public java.lang.String validateOID(java.lang.String oid)
Validates the OID string passed in.

Parameters:
oid - String containing the OID to validate.
Returns:
String containing the valid OID; emtpy String otherwise.

oidToString

public static java.lang.String oidToString(SNMPObjectIdentifier oid)
Converts an SNMPObjectIdentifier to a String object.

Parameters:
oid - SNMPObjectIdentifier to be converted
Returns:
String

oidToString

public static java.lang.String[] oidToString(SNMPObjectIdentifier[] oids)
Converts an array SNMPObjectIdentifier to an array of String objects.

Parameters:
oids - SNMPObjectIdentifiers to be converted
Returns:
String[]

dispose

public void dispose()
Cleans up the connection.


isBusy

public boolean isBusy()
Checks to see if an operation is currently in progress.

Returns:
TRUE if the connection is busy; FALSE otherwise.

run

public void run()
Specified by:
run in interface java.lang.Runnable

setDebug

public void setDebug(boolean bState)
Deprecated. Do not use this method; use setDebugState instead

Parameters:
bState -

setDebugState

public void setDebugState(int nState)
Puts the class into a debug diagnostic state.

Parameters:
nState -

getDebugState

public int getDebugState()
Gets the current diagnostic state.

Returns:

operationToString

public static java.lang.String operationToString(int oper)
Converts an operation type constant to it's equivalent string representation.

Parameters:
oper - Operation type to be converted.
Returns:
String

dataTypeToString

public static java.lang.String dataTypeToString(int dataType)
Converts a data type constant to it's equivalent string representation.

Parameters:
dataType - Data type to be converted.
Returns:
String

stringToDataType

public static int stringToDataType(java.lang.String str)
Converts a data type string representation to its equivalent contant value.

Parameters:
str - String to be converted.
Returns:
int


Copyright © 2008 AMX LLC. All Rights Reserved.