Java SNMP Package

Java SNMP Package

See:
Description

Packages

snmp	The snmp package defines classes used to communicate with SNMP devices.

Java SNMP Package

This package is an open-source implementation of the SNMP protocol as a Java package. It provides support for basic SNMP operations as defined in SNMP versions 1 and 2 (excluding the security model proposed as part of SNMP version 2, which was never widely accept or deployed). The package provides a mechanism for "getting and setting" SNMP object identifier (OID) values through a simple communication interface, and represents SNMP structures and datatypes as corresponding Java objects. The package assumes familiarity with the SNMP v1 and v2c protocol, as detailed in the relevant RFCs; however, some simple examples are provided which illustrate its use for simple get/set operations.

The complete API documentation for the package is provided through JavaDoc documentation. This introduction is intended to provide an overview of the package, with particular focus on the classes an end user will need to directly interface with to incorporate the package into a project.

Main Interface: the SNMPv1CommunicationInterface Class

Much of the top-level user functionality is provided by the class SNMPv1CommunicationInterface. This constructor for this class opens a datagram socket to a specified host for SNMP communication on the standard port (192). Several methods of the class then provide a means to retrieve and set the value of SNMP variables on the remote device by supplying a string specifying an object identifier and an appropriate SNMP object for set operations. The example program listed below (Example 1 ) illustrates the use of the communication interface class to open a connection to a remote device, get the value of two variables corresponding to OIDs 1.3.6.1.2.1.1.1.0 and 1.3.6.1.2.1.1.3.0, and set the value of a third variable. The source code for the SNMP Inquisitor shows the use of the package in a general-purpose utility which permits SNMP querying and modification of a remote device.

The constructor for the SNMPv1CommunicationInterface takes three parameters: an integer giving the SNMP version in use (generally always 0), the remote device address supplied as an InetAddress object, and a string giving the SNMP community to be used for the operations.

Getting and Setting Variable Values

Once the communication interface has been created to communicate with a device, the values of SNMP variables can be retrieved with calls to the getMIBEntry() method. This takes as argument a string with the variable's OID; the return value is somewhat complex, due to SNMP's ability to query multiple variables in a single message (though this particular method retrieves only one value at a time). The return value is of type SNMPVarBindList, a subclass of SNMPSequence which holds a sequence of (OID, value) pairs. Thus the retrieved SNMP value is accessed as follows:

• the first (and only) element is extracted from the SNMPVarBindList using the getSNMPObjectAt( ) method with argument 0
• the extracted element is typecast to type SNMPSequence - it's an (OID, value) pair, i.e., an SNMP sequence
• the second element - the value - is extracted from the pair using the getSNMPObjectAt( ) method with argument 1

The result of this (protracted) process is an SNMPObject subclass. The class of the returned value depends on the OID which was requested, and can be determined with the getClass( ) method defined in the Java Object universal base class (though generally the return class will be known in advance from knowledge of the OID being retrieved).

The internal Java value can be retrieved from the SNMPObject subclass using the getValue( ) method, which returns a subclass of java.lang.Object that is appropriate to represent the value. The internal Java Object subclass which stores the internal value in each SNMPObject subclass is given in Table 1 .

The process of setting the value of an SNMP variable uses the setMIBValue( ) method of the communication interface. This takes as arguments a String specifying the OID of the variable whose value is to be set, and an appropriate SNMPObject (of appropriate subclass) with the new value. The SNMP object can be constructed using an appropriate constructor for the object type.

The code in Example 1 illustrates the above get and set operations.


Exceptions

The Java SNMP package defines a number of exceptions to indicate problems with SNMP object constrcution, retrieval, and setting.

Example 1: SampleSNMP.java source code

import snmp.*;
import java.util.*;
import java.math.*;
import java.net.*;



public class SampleSNMP
{

public static void main(String args[])
{

try
{

// create a communications interface to a remote SNMP-capable device;
// need to provide the remote host's InetAddress and the community
// name for the device; in addition, need to supply the version number
// for the SNMP messages to be sent (the value 0 corresponding to SNMP
// version 1)
InetAddress hostAddress = InetAddress.getByName("10.0.1.1");
String community = "public";
int version = 0; // SNMPv1

SNMPv1CommunicationInterface comInterface = new SNMPv1CommunicationInterface(version, hostAddress, community);



// now send an SNMP GET request to retrieve the value of the SNMP variable
// corresponding to OID 1.3.6.1.2.1.1.1.0; this is the OID corresponding to
// the device identifying string, and the type is thus SNMPOctetString
String itemID = "1.3.6.1.2.1.1.1.0";

System.out.println("Retrieving value corresponding to OID " + itemID);

// the getMIBEntry method of the communications interface returns an SNMPVarBindList
// object; this is essentially a Vector of SNMP (OID,value) pairs. In this case, the
// returned Vector has just one pair inside it.
SNMPVarBindList newVars = comInterface.getMIBEntry(itemID);

// extract the (OID,value) pair from the SNMPVarBindList; the pair is just a two-element
// SNMPSequence
SNMPSequence pair = (SNMPSequence)(newVars.getSNMPObjectAt(0));

// extract the object identifier from the pair; it's the first element in the sequence
SNMPObjectIdentifier snmpOID = (SNMPObjectIdentifier)pair.getSNMPObjectAt(0);

// extract the corresponding value from the pair; it's the second element in the sequence
SNMPObject snmpValue = pair.getSNMPObjectAt(1);

// print out the String representation of the retrieved value
System.out.println("Retrieved value: type " + snmpValue.getClass().getName() + ", value " + snmpValue.toString());

// the retrieved value can be obtained from the SNMPObject using the getValue method;
// the return type of the method is the generic base class Object, and must be cast to
// the appropriate actual Java type; in this case, for an SNMPOctetString, the underlying
// Java type is a byte array[]
byte[] javaByteArrayValue = (byte[])snmpValue.getValue();



// now send an SNMP GET request to retrieve the value of the SNMP variable
// corresponding to OID 1.3.6.1.2.1.1.3.0; this is the OID corresponding to
// the uptime of the device, and the return type is thus SNMPTimeTicks
itemID = "1.3.6.1.2.1.1.3.0";

System.out.println("Retrieving value corresponding to OID " + itemID);

// the getMIBEntry method of the communications interface returns an SNMPVarBindList
// object; this is essentially a Vector of SNMP (OID,value) pairs. In this case, the
// returned Vector has just one pair inside it.
newVars = comInterface.getMIBEntry(itemID);

// extract the (OID,value) pair from the SNMPVarBindList; the pair is just a two-element
// SNMPSequence
pair = (SNMPSequence)(newVars.getSNMPObjectAt(0));

// extract the object identifier from the pair; it's the first element in the sequence
snmpOID = (SNMPObjectIdentifier)pair.getSNMPObjectAt(0);

// extract the corresponding value from the pair; it's the second element in the sequence
snmpValue = pair.getSNMPObjectAt(1);

// print out the String representation of the retrieved value
System.out.println("Retrieved value: type " + snmpValue.getClass().getName() + ", value " + snmpValue.toString());

// the retrieved value can be obtained from the SNMPObject using the getValue method;
// the return type of the method is the generic base class Object, and must be cast to
// the appropriate actual Java type; in this case, for SNMPTimeTicks, which is a subclass
// of SNMPInteger, the actual type is BigInteger (which permits arbitrarily large values to
// be represented).
BigInteger javaIntegerValue = (BigInteger)snmpValue.getValue();



// now send an SNMP SET request to set the value of the SNMP variable
// corresponding to OID 1.3.6.1.2.1.1.1.0; this is the OID corresponding to
// the device identifying string, and the type is thus SNMPOctetString;
// to set a new value, a string is supplied
itemID = "1.3.6.1.2.1.1.1.0";

SNMPOctetString newValue = new SNMPOctetString("New device name");

System.out.println("Setting value corresponding to OID " + itemID);
System.out.println("New value: " + newValue.toString());

// the setMIBEntry method of the communications interface returns the SNMPVarBindList
// corresponding to the supplied OID and value
// This call will probably cause an SNMPSetException to be thrown, since the
// community name "public" is probably not the read/write password of the device
newVars = comInterface.setMIBEntry(itemID, newValue);



}
catch(Exception e)
{
System.out.println("Exception during SNMP operation: " + e + "\n");
}

}

}

SNMP Datatypes and Corresponding Java Classes

A number of classes in the Java SNMP package serve to represent the standard SNMP datatypes as Java classes, with each datatype represented by a class which is a subclass of the abstract base class SNMPObject. The data is represented internally by an appropriate Java object, which may be retrieved for inspection or set to a new value. For example, the SNMP Integer datatype is represented by the java.snmp.SNMPInteger class, which stores the value internally in a Java.math.BigInteger object (a BigInteger object is used rather than a regular Integer to correctly address the fact that there is no express upper limit placed on the size of the SNMP Integer datatype). Each concrete subclass defines public functions declared in the abstract base class for getting and setting the internal (Java object) value, getValue and setValue (which throws an SNMPBadValueException if the wrong object type is supplied), as well as appropriate constructors and a toString method which returns a human-readable representation of the object.

The following table lists the Java class corresponding to each standard SNMP datatype, and the class used to represent the value internally. Note that most of the Java classes just use the name of the SNMP type with "SNMP" prefixed.

Table 1: SNMP datatypes, corresponding Java SNMP classes, and internal value representations

SNMP Datatype	Java SNMP Class	Java SNMP Base Class	Internal value representation
Integer	SNMPInteger	SNMPObject	BigInteger
Uinteger32	SNMPUInteger32	SNMPInteger	BigInteger (but value "wraps" at 2^32)
Gauge	SNMPGauge32	SNMPInteger	BigInteger (but value "pegs" at 2^32 - 1)
Counter32	SNMPCounter32	SNMPInteger	BigInteger (but value "wraps" at 2^32)
Counter64	SNMPCounter64	SNMPInteger	BigInteger (but value "wraps" at 2^64)
TimeTicks	SNMPTimeTicks	SNMPInteger	BigInteger
Octet string	SNMPOctetString	SNMPObject	byte[]
IP address	SNMPIPAddress	SNMPOctetString	byte[4]
NSAP address (MAC address)	SNMPNSAPAddress	SNMPOctetString	byte[6]
Object identifier	SNMPObjectIdentifier	SNMPObject	int[] (contains the components of the dotted-integer representation of the OID)
Sequence	SNMPSequence	SNMPObject	Vector
VarBind	SNMPVariablePair	SNMPSequence	Vector
VarBindList	SNMPVarBindList	SNMPSequence	Vector
Null	SNMPNull	SNMPObject