This document does not explain SNMP (Simple Network Management Protocol) itself. The reader is assumed to have basic knowledge of the protocol. If you want to learn more, see the Reading section.

The target applications are small applets, for that reason the stack has remained tiny. We wanted something lighter that we could just pop in a (Netscape) frame and leave there all day. It has no MIB (Management Information Base) browsing capabilities, you have to know the OID (Object Identifier) of what you want to monitor. There are many other packages that do MIB browsing and general network management.

The Westhawk Java SNMP stack comes with generated (javadoc) documentation. Check that documentation for the description of all methods that are not mentioned in this document or for the description of the method parameters.

The file snmp<version>.zip contains the SNMP stack. The distribution can be downloaded from the Westhawk's SNMP page. The contents of the zip file is:

snmp<version>.jar

The jar file with the core of the SNMP stack classes. It contains the precompiled uk.westhawk.snmp.X packages. This jar file does not contain any examples or beans.

javadoc/

The directory with the javadoc files.

stubs/

The directory with experimental software to auto generate a Java source file of a PDU or bean out off a MIB file, using smidump (libsmi)

uk/co/westhawk/

The source of the SNMP stack

uk/co/westhawk/examplev1/

The directory with the source of examples how to use the stack for SNMPv1.

uk/co/westhawk/examplev2c/

The directory with the source of examples how to use the stack for SNMPv2c.

uk/co/westhawk/examplev3/

The directory with the source of examples how to use the stack for SNMPv3.

uk/co/westhawk/nothread/

The directory with the source of example how to use the stack in environments where thread creation is unwanted, e.g. database JVMs such as Oracle ™ JServer.

uk/co/westhawk/snmp/beans/

The directory with the source of the different beans that come with the stack.

uk/co/westhawk/snmp/pdu/

The directory with the source of the different PDUs (among other things the BlockPdu) that come with the stack.

uk/co/westhawk/snmp/stack/

The directory with the source of the context and ASN functionality of the stack.

• Using the beans
• Using the PDUs
• Using the blocking calls

Our beans gather specific MIB information, i.e. the OID (Object Identifier) is hard coded. The beans should be easy enough to understand, and with little effort you can write a bean for your own purpose. The beans SNMPBean and SNMPRunBean contain some general information about the beans as well. The coding examples will show you how to use the beans as well.

The package uk.co.westhawk.snmp.pdu contains all the public accessible PDUs. All the Pdus (well, except for the BlockPdu) extend abstract uk.co.westhawk.snmp.stack.Pdu. The PDUs are non blocking and work via the java.util.Observer/java.util.Observable mechanism.

The idea is that for each class of problem you should subclass the abstract uk.co.westhawk.snmp.stack.Pdu class. You will have to implement the protected void new_value(int n, varbind res) and the protected void tell_them() methods. As example look at the uk.co.westhawk.snmp.pdu.OneIntPdu class or any other class in that package.

In order to use a PDU do the following:

1. Create a context, giving it the host name and port number of your SNMP agent. If this is run in an applet then you can only connect back to that server!
2. Create a PDU, passing it the context; OneGetPdu pdu = new OneGetPdu(context).
3. Add the OIDs you are interested in with pdu.add_oid(oid).
4. Add an observer with pdu.addObserver(observer). The argument is the object that wishes to be notified when the new value arrives. It must implement java.util.Observer, that is it must have a public void update(java.util.Observable obs, java.lang.Object obj) method. This method will get called when the value arrives. If you are using Swing, don't forget to use javax.swing.SwingUtilities.invokeLater(java.lang.Runnable) if you want to do any screen updates.
5. Call pdu.send().
6. Sleep, or do something else. Your update method will get called automatically when the data has arrived. Both the context and PDU objects spawn their own threads, so there is nothing further to do.

The coding examples will show you how to use the PDUs as well.

As the title suggests, the BlockPdu sends the request and waits for the response. We suggest that you only use this class if you have to; Because the pdu blocks, you can not do anything else on that thread while it is waiting for a reply. If that thread is driving a UI, then the user may see a sluggish interface. If you can, use the beans or the PDUs.

There are four methods that send the request, wait for the response and return the variables or variable bindings. They throw the uk.co.westhawk.snmp.stack.PduException exception:

• AsnObject getResponseVariable()
• AsnObject [ ] getResponseVariables()
• varbind getResponseVariableBinding()
• varbind [ ] getResponseVariableBindings()

The OIDs that are added via addOid method for the request will not be replaced by the OIDs from the response. This means that every request will result in the same answer and that the GetNext does not walk the MIB

The next section explains the use of the type of socket.

This SNMP stack provides three contexts for SNMPv1:

• uk.co.westhawk.snmp.stack.SnmpContext
• uk.co.westhawk.snmp.stack.SnmpContextPool
• uk.co.westhawk.snmp.stack.PassiveSnmpContext

The SnmpContextPool contains a pool of SnmpContext and will share any context that it can share. This results in a reduced number of threads and other resources.

The PassiveSnmpContextPool contains the SNMP v1 context that is needed by a Pdu to send a SNMP v1 request in environments where thread creation is unwanted, see the nothread notes.

The next section explains the use of the type of socket.

This SNMP stack provides three contexts for SNMPv2c:

• uk.co.westhawk.snmp.stack.SnmpContextv2c
• uk.co.westhawk.snmp.stack.SnmpContextv2cPool
• uk.co.westhawk.snmp.stack.PassiveSnmpContextv2c

The SnmpContextv2cPool contains a pool of SnmpContextv2c and will share any context that it can share. This results in a reduced number of threads and other resources.

The PassiveSnmpContextv2c contains the SNMP v2c context that is needed by a Pdu to send a SNMP v2c request in environments where thread creation is unwanted, see the nothread notes.

The socket type

The caller needs to use the NETSCAPE_SOCKET socket type when this stack is used in an applet that is running in Netscape 4.X and when the jar files needs to be signed. For more documentation on this subject see Introduction to the capabilities classes.

• Receive traps for all hosts
• Receive traps from a specific host
• Receive unhandled traps

• Create or reuse a context with the host name and parameters of your SNMP agent. The port number will be ignored in this case.
• Add a trap listener with context.addTrapListener(listener). The argument is the object that wishes to be notified when the traps arrives. It must implement uk.co.westhawk.snmp.event.TrapListener, that is it must have a public void trapReceived(uk.co.westhawk.snmp.event.TrapEvent evt) method. This method will get called when the trap is received.

Unhandled traps are traps that are received (see traps for all hosts) but do not match any of the contexts (see traps from a specific host):

• Get the instance of the class with DefaultTrapContext trapContext = DefaultTrapContext.getInstance(port, typeSocket)
• Add a trap listener with trapContext.addUnhandledTrapListener(listener). The argument is the object that wishes to be notified when unhandled traps are received. It must implement uk.co.westhawk.snmp.event.TrapListener, that is it must have a public void trapReceived(uk.co.westhawk.snmp.event.TrapEvent evt) method. This method will get called when the trap is received and remains unhandled.

• The decoded trap event where a trap pdu is passed
• The undecoded trap event where the raw bytes of the message are passed

Decoded trap events are fired by the SnmpContext classes when receiving traps from a specific host. In this case the uk.co.westhawk.snmp.event.TrapEvent will contain one of the two trap PDUs:

• uk.co.westhawk.snmp.stack.TrapPduv1 - The Trap PDU for SNMPv1
• uk.co.westhawk.snmp.stack.TrapPduv2 - The Trap PDU for SNMPv2c and SNMPv3

Undecoded trap events are fired by the DefaultTrapContext class when receiving traps for all hosts and/or receiving unhandled traps. In this case the uk.co.westhawk.snmp.event.TrapEvent will contain the following:

• version - The SNMP version number of the trap
• host address - The IP host address of the host where the trap came from
• message - The trap in bytes

To decode an undecoded trap event, you create a context on the fly and call Pdu trapPdu = context.processIncomingTrap(byte[ ] message). The context should contain all the parameters needed to decode the message. For SNMPv3 this is not so obvious.

The scripts to run these examples are explained in the next section. If this example is not sufficient, check if the other examples do what you are looking for.

This example requests sysContact with the BlockPdu. The complete example can be found in uk.co.westhawk.examplev1.OneBlockOperation

private void createContext(String host, int port, String comm, 
      String socketType)
{
    if (context != null)
    {
        context.destroy();
    }
    try
    {
        context = new SnmpContextPool(host, port, socketType);
        context.setCommunity(comm);
    }
    catch (java.io.IOException exc)
    {
        // give the user feedback
        exc.printStackTrace();
    }
}


private void sendGetRequest(String oid)
{
    pdu = new BlockPdu(context);
    pdu.setPduType(BlockPdu.GET);
    pdu.addOid(oid);
    sendRequest(pdu);
}

private void sendRequest(BlockPdu pdu)
{
    try
    {
        varbind var = pdu.getResponseVariableBinding();
        AsnObjectId oid = var.getOid();
        AsnObject res = var.getValue();
        if (res != null)
        {
            // print or display the answer
        }
        else
        {
            // Received no answer
        }
    }
    catch (PduException exc)
    {
        // give the user feedback
        exc.printStackTrace();
    }
    catch (java.io.IOException exc)
    {
        // give the user feedback
        exc.printStackTrace();
    }
}

C:\> cd <to where the applications live>
C:\> runapplication OneBlockOperation

% cd <to where the applications live>
% ./runapplication.sh OneBlockOperation

% cd <to where the applications live>
% ./runapplication.sh OneBlockOperation

% cd <to where the applications live>
% ./runapplication.sh OneBlockOperation OneBlockOperation.properties

Our article on Simple Times (issue Dec 2001) explains the history and design decisions of the stack.

The SimpleWeb provides links and information on network management, including software, RFCs and tutorials. The focus is on SNMP and Internet management.

For more background on SNMP we recommend the following books:

• The Simple Book by Marshall T. Rose (Prentice Hall, 1994)
• SNMP, SNMPv2, SNMPv3 and RMON 1 and 2 by William Stallings (Addison-Wesley, 1999), ISBN 0-201-48534-6

• XML parser for Java from IBM
• Xalan XSLT from Apache
• Java Servlets from Sun Microsystems

libsmi is used in the stubs directory. It is available for Linux, Win, Mac.