JoeSNMP API 0.3.3

org.opennms.protocols.snmp
Class SnmpSession

java.lang.Object
  extended by 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_RUNTIME
          This is the command passed to the SnmpHandler if an unexpected runtime exception was generated when attempting to send an SnmpPduRequest message
static int ERROR_TIMEOUT
          This is the command passed to the SnmpHandler if a timeout occurs.
private static int EXPIRED_REQUEST_CLEANUP_FREQUENCY
           
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.Map m_requestsMap
          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  SnmpTimer m_timer
          The timer object used to schedule the SnmpRequest timeouts.
 
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.
SnmpSession(SnmpPeer peer, int threadPoolSize, int receiveBuffer, int sendBuffer)
           
 
Method Summary
 void cancel(int requestId)
          Cancels the current outstanding reqeust as defined by the SnmpPduPacket's requestId method.
private  void cleanupExpiredRequests()
           
 void close()
          Used to close the session.
private  SnmpSession.ByteArrayInfo encode(SnmpPduTrap pdu)
          This method is used to encode the passed protocol data unit and return the encoding.
private  SnmpSession.ByteArrayInfo encode(SnmpPeer peer, SnmpPduPacket pdu)
          This method is used to encode the passed protocol data unit and return the encoding.
 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.
static void registerSyntaxObject(SnmpSyntax object)
          Allows library users to register new ASN.1 types with the SNMP library.
 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 snmpInternalError(SnmpRequest request, int errorCode)
           
 void snmpTimeoutError(SnmpRequest request)
           
(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

ERROR_RUNTIME

public static final int ERROR_RUNTIME
This is the command passed to the SnmpHandler if an unexpected runtime exception was generated when attempting to send an SnmpPduRequest message

See Also:
SnmpHandler, Constant Field Values

m_requestsMap

private java.util.Map m_requestsMap
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


EXPIRED_REQUEST_CLEANUP_FREQUENCY

private static final int EXPIRED_REQUEST_CLEANUP_FREQUENCY
See Also:
Constant Field Values
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

SnmpSession

public SnmpSession(SnmpPeer peer,
                   int threadPoolSize,
                   int receiveBuffer,
                   int sendBuffer)
            throws java.net.SocketException
Throws:
java.net.SocketException
Method Detail

encode

private SnmpSession.ByteArrayInfo encode(SnmpPeer peer,
                                         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 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.

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. This method is called by SnmpRequest.

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

snmpInternalError

void snmpInternalError(SnmpRequest request,
                       int errorCode)

snmpTimeoutError

public void snmpTimeoutError(SnmpRequest request)

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.

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

cleanupExpiredRequests

private void cleanupExpiredRequests()

JoeSNMP API 0.3.3

Generated by builder on ${TODAY} ${TSTAMP}.