OpenNMS API 1.2.9

## org.opennms.protocols.snmp
Class SnmpSession

    java.lang.Object
      org.opennms.protocols.snmp.SnmpSession

public class SnmpSession
extends java.lang.Object

The SnmpSession is the main connection between the SNMP manager and the SNMP Agent. All the request flow through this class. To use the SnmpSession class a SnmpHandler class must be defined to process any errors or responses through the library.

Once the session is created the creator must call close() to ensure an orderly release of threads and resources.

Version:
  1.1.1.1 2001/11/11 17:27:22
Author:
  Brian Weaver , OpenNMS
See Also:
  `SnmpHandler`, `SnmpPacketHandler`, `SnmpPortal`

Nested Class Summary
`private static class` `SnmpSession.ByteArrayInfo` Encapsulates a byte array and the number of bytes of valid data in the array.
`private class` `SnmpSession.CleanupRequest` This class is used to periodically cleanup the outstanding request that have expired.
`private class` `SnmpSession.SessionHandler` Inner class SessionHandler implements the interface SnmpPacketHandler to handle callbacks from the SnmpPortal

Field Summary
`static int` `ERROR_ENCODING` This is the command passed to the SnmpHandler if an encoding exception is generated when attempting to send an SnmpPduRequest message
`static int` `ERROR_IOEXCEPTION` This is the command passed to the SnmpHandler if an IOException occurs while attempting to transmit the request
`static int` `ERROR_TIMEOUT` This is the command passed to the SnmpHandler if a timeout occurs.
`private SnmpHandler` `m_defHandler` The default SNMP callback handler.
`(package private) AsnEncoder` `m_encoder` ASN encoder
`private SnmpPeer` `m_peer` The SNMP peer to whom this session will communicate with.
`private SnmpPortal` `m_portal` the receiver thread
`private java.util.LinkedList` `m_requests` Used to contain a list of outstanding request for the session.
`private boolean` `m_stopRun` If the boolean variable is set then the destroy() method must have been called
`private java.lang.Object` `m_sync` Provides a synchronization point
`private boolean` `m_threadException` If this boolean value is set then the receiver thread is terminated due to an exception that was generated in either a handler or a socket error.
`private SnmpTimer` `m_timer` The timer object used to schedule the SnmpRequest timeouts.
`private java.lang.Throwable` `m_why` This is the saved fatal excetion that can be rethrown by the application

Constructor Summary
`SnmpSession(java.net.InetAddress peer)` The default SnmpSession constructor.
`SnmpSession(java.net.InetAddress peer, SnmpParameters params)` Constructs the SnmpSession with the specific parameters.
`SnmpSession(SnmpPeer peer)` Constructs the SnmpSession with the specific SnmpPeer.

Method Summary
`(package private) void` `addRequest(SnmpRequest req)` Adds an outstanding request to the session.
`void` `cancel(int requestId)` Cancels the current outstanding reqeust as defined by the SnmpPduPacket's requestId method.
`void` `close()` Used to close the session.
`private SnmpSession.ByteArrayInfo` `encode(SnmpPduPacket pdu)` This method is used to encode the passed protocol data unit and return the encoding.
`private SnmpSession.ByteArrayInfo` `encode(SnmpPduTrap pdu)` This method is used to encode the passed protocol data unit and return the encoding.
`(package private) SnmpRequest` `findRequest(SnmpPduPacket pdu)` Finds the first matching request in the list of outstanding request and returns it to the caller.
`AsnEncoder` `getAsnEncoder()` Gets the AsnEncoder for the session.
`SnmpHandler` `getDefaultHandler()` Gets the default SnmpHandler for the session.
`int` `getOutstandingCount()` Returns the number of outstanding request for the agent.
`SnmpPeer` `getPeer()` Gets the current peer object.
`(package private) SnmpTimer` `getTimer()` Returns the internal timer object for the SNMP Session.
`boolean` `isClosed()` Returns true if the `close` method has been called.
`void` `raise()` If an exception occurs in the SNMP receiver thread then raise() will rethrow the exception.
`static void` `registerSyntaxObject(SnmpSyntax object)` Allows library users to register new ASN.1 types with the SNMP library.
`(package private) void` `removeRequest(SnmpRequest req)` Removes an outstanding request from the session.
`int` `send(SnmpPduPacket pdu)` Sends the SNMP PDU to the remote agent and uses the default SnmpHandler to process the request.
`int` `send(SnmpPduPacket pdu, SnmpHandler handler)` Send the SNMP PDU to the remote agent and invokes the specified handler when the packet is recieve.
`int` `send(SnmpPduTrap pdu)` Sends the SNMP PDU Trap to the remote agent.
`int` `send(SnmpPduTrap pdu, SnmpHandler handler)` Send the SNMP PDU Trap to the remote agent.
`void` `setAsnEncoder(AsnEncoder encoder)` Sets the default encoder.
`void` `setDefaultHandler(SnmpHandler hdl)` Sets the default SnmpHandler.
`void` `setPeer(SnmpPeer peer)` Sets the passed SnmpPeer object to the one used for all new SNMP communications.
`(package private) void` `transmit(SnmpRequest req)` Transmits the specified SnmpRequest to the SnmpPeer defined by the session.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ERROR_TIMEOUT

    public static final int ERROR_TIMEOUT

  This is the command passed to the SnmpHandler if a timeout occurs. All errors are less than zero.

  See Also:
    `SnmpHandler`, Constant Field Values

### ERROR_IOEXCEPTION

    public static final int ERROR_IOEXCEPTION

  This is the command passed to the SnmpHandler if an IOException occurs while attempting to transmit the request

  See Also:
    `SnmpHandler`, Constant Field Values

### ERROR_ENCODING

    public static final int ERROR_ENCODING

  This is the command passed to the SnmpHandler if an encoding exception is generated when attempting to send an SnmpPduRequest message

  See Also:
    `SnmpHandler`, Constant Field Values

### m_requests

    private java.util.LinkedList m_requests

  Used to contain a list of outstanding request for the session. The list should only contain SnmpRequest objects!

### m_peer

    private SnmpPeer m_peer

  The SNMP peer to whom this session will communicate with. The peer contains the parameters also.

  See Also:
    `SnmpParameters`

### m_timer

    private SnmpTimer m_timer

  The timer object used to schedule the SnmpRequest timeouts. It is also used to schedule the cleanup of the m_requests list.

  See Also:
    `SnmpSession.CleanupRequest`, `SnmpRequest`

### m_defHandler

    private SnmpHandler m_defHandler

  The default SNMP callback handler. If this is not set and it is needed then an SnmpHandlerNotDefinedException is thrown.

### m_encoder

    AsnEncoder m_encoder

  ASN encoder

### m_sync

    private java.lang.Object m_sync

  Provides a synchronization point

### m_stopRun

    private boolean m_stopRun

  If the boolean variable is set then the destroy() method must have been called

### m_portal

    private SnmpPortal m_portal

  the receiver thread

### m_threadException

    private boolean m_threadException

  If this boolean value is set then the receiver thread is terminated due to an exception that was generated in either a handler or a socket error. This is considered a fatal exception.

### m_why

    private java.lang.Throwable m_why

  This is the saved fatal excetion that can be rethrown by the application

Constructor Detail

### SnmpSession

    public SnmpSession(java.net.InetAddress peer)
                throws java.net.SocketException

  The default SnmpSession constructor. The object is constructed with a default SnmpPeer object.

Parameters:
  `peer` - The peer agent
Throws:
  `java.net.SocketException` - If thrown it is from the creation of a DatagramSocket.
See Also:
  `SnmpPeer`

### SnmpSession

    public SnmpSession(SnmpPeer peer)
                throws java.net.SocketException

  Constructs the SnmpSession with the specific SnmpPeer.

Parameters:
  `peer` - The SnmpPeer used to configure this session
Throws:
  `java.net.SocketException` - If thrown it is from the creation of a DatagramSocket.
See Also:
  `SnmpPeer`

### SnmpSession

    public SnmpSession(java.net.InetAddress peer,
                       SnmpParameters params)
                throws java.net.SocketException

  Constructs the SnmpSession with the specific parameters. The parameters are associated with the default SnmpPeer object.

Parameters:
  `peer` - The peer address for agent
  `params` - The SnmpParameters to configure with this session
Throws:
  `java.net.SocketException` - If thrown it is from the creation of a DatagramSocket.
See Also:
  `SnmpPeer`, `SnmpParameters`

Method Detail

### encode

    private SnmpSession.ByteArrayInfo encode(SnmpPduPacket pdu)
                                      throws SnmpPduEncodingException,
                                             AsnEncodingException

  This method is used to encode the passed protocol data unit and return the encoding. The encoding is performed using the default encoder for the session and limits the size to a 16K buffer.

  Parameters:
    `pdu` - The pdu to encode
  Returns:
    The encoded pdu request
  Throws:
    `SnmpPduEncodingException` - Thrown if an encoding exception occurs at the session level
    `AsnEncodingException` - Thrown if an encoding exception occurs in the AsnEncoder object.

### encode

    private SnmpSession.ByteArrayInfo encode(SnmpPduTrap pdu)
                                      throws SnmpPduEncodingException,
                                             AsnEncodingException

  This method is used to encode the passed protocol data unit and return the encoding. The encoding is performed using the default encoder for the session and limits the size to a 16K buffer.

  Parameters:
    `pdu` - The pdu to encode
  Returns:
    The encoded pdu request
  Throws:
    `SnmpPduEncodingException` - Thrown if an encoding exception occurs at the session level
    `AsnEncodingException` - Thrown if an encoding exception occurs in the AsnEncoder object.

### addRequest

    void addRequest(SnmpRequest req)

  Adds an outstanding request to the session. The access to the list is synchronized on the actual list of request. This is done to allow synchronization between addRequest(), removeRequest(), and findRequest()

  Parameters:
    `req` - The request reference to add (not cloned)

### removeRequest

    void removeRequest(SnmpRequest req)

  Removes an outstanding request from the session. The method uses the Object.equals() to find a matching request. If the SnmpRequest object does not override the equals() method the a "by reference" equality is used.

  Parameters:
    `req` - The request to remove. All matching request are removed.

### findRequest

    SnmpRequest findRequest(SnmpPduPacket pdu)

  Finds the first matching request in the list of outstanding request and returns it to the caller. The matching is done by means using the SNMP Protocol Data Unit's request id. If no match is found then a null is returned

  Parameters:
    `pdu` - The source pdu for the search.
  Returns:
    Returns a SnmpRequest if a match is found. Otherwise a null is returned.

### getTimer

    SnmpTimer getTimer()

  Returns the internal timer object for the SNMP Session.

  Returns:
    The internal timer object

### transmit

    void transmit(SnmpRequest req)
            throws SnmpPduEncodingException,
                   AsnEncodingException,
                   java.io.IOException

  Transmits the specified SnmpRequest to the SnmpPeer defined by the session. First the SnmpPdu contained within the request is encoded using the session AsnEncoder, as defined by the SnmpParameters. Once the packet is encoded it is transmitted to the agent defined by SnmpPeer. If an error occurs an appropiate exception is generated.

  Parameters:
    `req` - The SnmpRequest to transmit
  Throws:
    `SnmpPduEncodingException` - Thrown if an encoding exception occurs at the session level
    `AsnEncodingException` - Thrown if an encoding exception occurs in the AsnEncoder object.
    `java.io.IOException` - Thrown if an error occurs sending the encoded datagram
  See Also:
    `SnmpRequest`, `SnmpParameters`, `SnmpPeer`

### getDefaultHandler

    public SnmpHandler getDefaultHandler()

  Gets the default SnmpHandler for the session. If the handler has never been set via the setDefaultHandler() method then a null will be returned.

  Returns:
    The default SnmpHandler, a null if one has never been registered.

### setDefaultHandler

    public void setDefaultHandler(SnmpHandler hdl)

  Sets the default SnmpHandler.

  Parameters:
    `hdl` - The new default handler

### getPeer

    public SnmpPeer getPeer()

  Gets the current peer object.

  Returns:
    The current SnmpPeer object

### setPeer

    public void setPeer(SnmpPeer peer)

  Sets the passed SnmpPeer object to the one used for all new SNMP communications. This includes any outstanding retries.

  Parameters:
    `peer` - The SnmpPeer object for the sesison

### getOutstandingCount

    public int getOutstandingCount()

  Returns the number of outstanding request for the agent. An outstanding request is one that has no yet responded to the query.

  Returns:
    The number of outstanding request
  Throws:
    `java.lang.IllegalStateException` - Throw if the session has been closed.

### cancel

    public void cancel(int requestId)

  Cancels the current outstanding reqeust as defined by the SnmpPduPacket's requestId method.

  Parameters:
    `requestId` - The request to cancel
  Throws:
    `java.lang.IllegalStateException` - Throw if the session has been closed.
  See Also:
    `SnmpPduPacket`

### send

    public int send(SnmpPduPacket pdu,
                    SnmpHandler handler)

  Send the SNMP PDU to the remote agent and invokes the specified handler when the packet is recieve. This is a non-blocking call.

  Parameters:
    `pdu` - The pdu to encode and send
    `handler` - The handler object for this request
  Returns:
    The request identifier for the newly sent PDU.
  Throws:
    `SnmpHandlerNotDefinedException` - Thrown if the handler is null
    `java.lang.IllegalStateException` - Thrown if the session has been closed.

### send

    public int send(SnmpPduPacket pdu)

  Sends the SNMP PDU to the remote agent and uses the default SnmpHandler to process the request. This is a non-blocking call

  Parameters:
    `pdu` - The pdu to encode and send
  Returns:
    The request identifier for the newly sent PDU.
  Throws:
    `SnmpHandlerNotDefinedException` - Thrown if the handler is null
    `java.lang.IllegalStateException` - Thrown if the session has been closed.

### send

    public int send(SnmpPduTrap pdu,
                    SnmpHandler handler)

  Send the SNMP PDU Trap to the remote agent. This is a non-blocking call.

  Parameters:
    `pdu` - The pdu to encode and send
    `handler` - The handler object for this request
  Returns:
    The request identifier for the newly sent PDU.
  Throws:
    `SnmpHandlerNotDefinedException` - Thrown if the handler is null
    `java.lang.IllegalStateException` - Thrown if the session has been closed.

### send

    public int send(SnmpPduTrap pdu)

  Sends the SNMP PDU Trap to the remote agent. This is a non-blocking call

  Parameters:
    `pdu` - The pdu to encode and send
  Returns:
    The request identifier for the newly sent PDU.
  Throws:
    `SnmpHandlerNotDefinedException` - Thrown if the handler is null
    `java.lang.IllegalStateException` - Thrown if the session has been closed.

### isClosed

    public boolean isClosed()

  Returns true if the `close` method has been called. The session cannot be used to send request after `close` has been executed.

### close

    public void close()

  Used to close the session. Once called the session should be considered invalid and unusable.

  Throws:
    `java.lang.IllegalStateException` - Thrown if the session has already been closed by another thread.

### raise

    public void raise()
               throws java.lang.Throwable

  If an exception occurs in the SNMP receiver thread then raise() will rethrow the exception.

  Throws:
    `java.lang.Throwable` - The base for thrown exceptions.

### setAsnEncoder

    public void setAsnEncoder(AsnEncoder encoder)

  Sets the default encoder.

  Parameters:
    `encoder` - The new encoder

### getAsnEncoder

    public AsnEncoder getAsnEncoder()

  Gets the AsnEncoder for the session.

  Returns:
    the AsnEncoder

### registerSyntaxObject

    public static void registerSyntaxObject(SnmpSyntax object)

  Allows library users to register new ASN.1 types with the SNMP library. The object must support all methods of the SnmpSyntax interface. The object is registered globally with the library and is visible to all session after it is registered.

  Parameters:
    `object` - The new SnmpSyntax object to register

OpenNMS API 1.2.9

Generated by ranger on May 19 2007 2335.