org.opennms.protocols.snmp

Class SnmpPortal

java.lang.Object

org.opennms.protocols.snmp.SnmpPortal

public class SnmpPortal
extends java.lang.Object

Abstracts the communication related details from the SnmpSession and SnmpTrapSession.

Author:

Brian Weaver, Sowmya Nataraj, OpenNMS, Dimitris Andreadis,

See Also:

SnmpSession, SnmpTrapSession, DatagramSocket

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	SnmpPortal.Executor Defines the inner class, Executor threas, which will be part of thread pool that is used for handling the packet
private class	SnmpPortal.Receiver Defines the inner class that monitors the datagram socket and receives all the PDU responses.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	bSocketSoTimeoutRequired Set to true if it is necessary to set the socket timeout value via the Socket.setSoTimeout() method in order to keep from blocking indefinitely on a socket I/O call.
static int	DATAGRAM_SOCKET_BUFFER_SIZE
static int	DEFAULT_RECEIVE_BUFFER_SIZE
static int	DEFAULT_SEND_BUFFER_SIZE
static int	DEFAULT_THREADPOOL_SIZE
private java.net.DatagramSocket	m_comm The datagram socket used to send and receive SNMP messages.
private AsnEncoder	m_encoder ASN.1 encoder used to decode the SNMP messages.
private SnmpPacketHandler	m_handler The packet handler that is used to process received SNMP packets and invalid datagrams.
private boolean	m_isClosing When set the portal object's close method has been invoked.
private int	m_numOfExecutorThreads the number of executor threads in the thread pool specified during construction of SnmpPortal
private SnmpPortal.Receiver	m_recvThread the receiver thread that runs the inner class Receiver.
private java.util.Vector	m_threadPool The thread pool that holds the executor threads
private java.util.LinkedList	m_usedBuffers Cache used bufferes
static int	MAXIMUM_THREADPOOL_SIZE
private static java.lang.String	PROP_SOCKET_TIMEOUT_PERIOD Identifies the system property that may be used to specify the number of milliseconds to use for the socket timeout.
private static java.lang.String	PROP_SOCKET_TIMEOUT_REQUIRED Identifies the system property that may be used to specify whether or not a timeout value is set on the SNMP trap socket.
private static java.lang.Class	THREAD_CATEGORY_CLASS

Constructor Summary

Constructors

Modifier	Constructor and Description
private	SnmpPortal() Private constructor used to disallow the default constructor.
(package private)	SnmpPortal(SnmpPacketHandler handler, AsnEncoder encoder, int port) The SnmpPortal constructor.
(package private)	SnmpPortal(SnmpPacketHandler handler, AsnEncoder encoder, int port, java.net.InetAddress laddr) The SnmpPortal constructor.
(package private)	SnmpPortal(SnmpPacketHandler handler, AsnEncoder encoder, int port, java.net.InetAddress laddr, int numOfThreads)
(package private)	SnmpPortal(SnmpPacketHandler handler, AsnEncoder encoder, int port, java.net.InetAddress laddr, int numOfThreads, int receiveBufferSize, int sendBufferSize) The SnmpPortal constructor.

Method Summary

Methods

Modifier and Type	Method and Description
(package private) void	cacheBuffer(byte[] buffer)
(package private) void	close() Used to close the session.
private static java.lang.Class	findThreadCategoryClass()
(package private) AsnEncoder	getAsnEncoder() Gets the AsnEncoder for the session.
(package private) byte[]	getBuffer()
(package private) SnmpPacketHandler	getPacketHandler() Gets the default SnmpPacketHandler for the session.
private void	handlePkt(java.net.DatagramPacket pkt) Recovers a SnmpPduPacket or SnmpPduTrap from the passed datagram and calls the appropriate method in the handler.
(package private) void	invokeHandlePkt(java.net.DatagramPacket pkt) Wrapper for invoking the handlePkt method and handling the necessary exceptions.
(package private) boolean	isClosed() Returns true if this portal has had it's close method called.
(package private) void	send(SnmpPeer peer, byte[] buf) Transmits the passed buffer to the respective peer agent.
(package private) void	send(SnmpPeer peer, byte[] buf, int length) Transmits the passed buffer to the respective peer agent.
(package private) void	setAsnEncoder(AsnEncoder encoder) Sets the default encoder.
(package private) void	setPacketHandler(SnmpPacketHandler hdl) Sets the default SnmpPacketHandler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_THREADPOOL_SIZE

public static final int DEFAULT_THREADPOOL_SIZE

See Also:

Constant Field Values

MAXIMUM_THREADPOOL_SIZE

public static final int MAXIMUM_THREADPOOL_SIZE

See Also:

Constant Field Values

DEFAULT_RECEIVE_BUFFER_SIZE

public static final int DEFAULT_RECEIVE_BUFFER_SIZE

See Also:

Constant Field Values

DEFAULT_SEND_BUFFER_SIZE

public static final int DEFAULT_SEND_BUFFER_SIZE

See Also:

Constant Field Values

DATAGRAM_SOCKET_BUFFER_SIZE

public static final int DATAGRAM_SOCKET_BUFFER_SIZE

See Also:

Constant Field Values

m_handler

private SnmpPacketHandler m_handler

The packet handler that is used to process received SNMP packets and invalid datagrams. The handler must also process any exceptions that occurs in the receiving thread.

m_comm

private java.net.DatagramSocket m_comm

The datagram socket used to send and receive SNMP messages.

m_recvThread

private SnmpPortal.Receiver m_recvThread

the receiver thread that runs the inner class Receiver.

m_numOfExecutorThreads

private int m_numOfExecutorThreads

the number of executor threads in the thread pool specified during construction of SnmpPortal

m_threadPool

private java.util.Vector m_threadPool

The thread pool that holds the executor threads

m_usedBuffers

private java.util.LinkedList m_usedBuffers

Cache used bufferes

m_encoder

private AsnEncoder m_encoder

ASN.1 encoder used to decode the SNMP messages. If the decoded fails to decode the specific messages the is should throw and appropiate ASN.1 exception

m_isClosing

private volatile boolean m_isClosing

When set the portal object's close method has been invoked. This is needed since the internal receiver thread will block on the communication channel. To "wake" the thread the close() method on the comm channel is performed. This will cause an exception to be genereated in the receiver thread. If the value of m_isClosing is true then the exception is ignored.

bSocketSoTimeoutRequired

private boolean bSocketSoTimeoutRequired

Set to true if it is necessary to set the socket timeout value via the Socket.setSoTimeout() method in order to keep from blocking indefinitely on a socket I/O call. This value is configurable at runtime via the system property "org.opennms.joeSNMP.vmhacks.socketSoTimeoutRequired". If this property is set to 'no', the bSocketSoTimeoutRequired variable will be set to false and the SNMP trap socket timeout will not be set. If this property is set to 'yes' or the property does not exist, the bSocketSoTimeoutRequired variable will be set to true. and the socket timeout will be set. Default value is true.

PROP_SOCKET_TIMEOUT_REQUIRED

private static final java.lang.String PROP_SOCKET_TIMEOUT_REQUIRED

Identifies the system property that may be used to specify whether or not a timeout value is set on the SNMP trap socket. Valid values are 'yes' and 'no'.

See Also:

Constant Field Values

PROP_SOCKET_TIMEOUT_PERIOD

private static final java.lang.String PROP_SOCKET_TIMEOUT_PERIOD

Identifies the system property that may be used to specify the number of milliseconds to use for the socket timeout.

See Also:

Constant Field Values

THREAD_CATEGORY_CLASS

private static final java.lang.Class THREAD_CATEGORY_CLASS

Constructor Detail

SnmpPortal

private SnmpPortal()
            throws java.lang.UnsupportedOperationException

Private constructor used to disallow the default constructor.

Throws:

java.lang.UnsupportedOperationException - Always thrown!

SnmpPortal

SnmpPortal(SnmpPacketHandler handler,
          AsnEncoder encoder,
          int port)
     throws java.net.SocketException

The SnmpPortal constructor. The constructor is used to build a portal on the specified port, and forward messages to the defined handler. All messages are decoded using the encoder specified during construction.

Parameters:

handler - The SNMP packet handler.

encoder - The ASN.1 codec object.

port - The port to send and receive datagram from.

Throws:

java.net.SocketException - Thrown if an error occurs setting up the communication channel.

java.lang.IllegalArgumentException - Thrown if any of the parameters are null or invalid.

SnmpPortal

SnmpPortal(SnmpPacketHandler handler,
          AsnEncoder encoder,
          int port,
          java.net.InetAddress laddr)
     throws java.net.SocketException

The SnmpPortal constructor. The constructor is used to build a portal on the specified port, and forward messages to the defined handler. All messages are decoded using the encoder specified during construction.

Parameters:

handler - The SNMP packet handler.

encoder - The ASN.1 codec object.

port - The port to send and receive datagram from.

laddr - The local address to bind.

Throws:

java.net.SocketException - Thrown if an error occurs setting up the communication channel.

java.lang.IllegalArgumentException - Thrown if any of the parameters are null or invalid.

SnmpPortal

SnmpPortal(SnmpPacketHandler handler,
          AsnEncoder encoder,
          int port,
          java.net.InetAddress laddr,
          int numOfThreads)
     throws java.net.SocketException

Throws:

java.net.SocketException

SnmpPortal

SnmpPortal(SnmpPacketHandler handler,
          AsnEncoder encoder,
          int port,
          java.net.InetAddress laddr,
          int numOfThreads,
          int receiveBufferSize,
          int sendBufferSize)
     throws java.net.SocketException

The SnmpPortal constructor. The constructor is used to build a portal on the specified port, and forward messages to the defined handler. All messages are decoded using the encoder specified during construction.

Parameters:

handler - The SNMP packet handler.

encoder - The ASN.1 codec object.

port - The port to send and receive datagram from.

laddr - The local address to bind.

numOfThreads - The number of Executor threads in pool.

receiveBufferSize - Sets the SO_RCVBUF option to the specified value for this DatagramSocket

sendBufferSize - Sets the SO_SNDBUF option to the specified value for this DatagramSocket.

Throws:

java.net.SocketException - Thrown if an error occurs setting up the communication channel.

java.lang.IllegalArgumentException - Thrown if any of the parameters are null or invalid.

Method Detail

findThreadCategoryClass

private static java.lang.Class findThreadCategoryClass()

invokeHandlePkt

void invokeHandlePkt(java.net.DatagramPacket pkt)

Wrapper for invoking the handlePkt method and handling the necessary exceptions.

Parameters:

pkt - The datagram packet to be decoded

Throws:

none

See Also:

handlePkt

getBuffer

byte[] getBuffer()

cacheBuffer

void cacheBuffer(byte[] buffer)

handlePkt

private void handlePkt(java.net.DatagramPacket pkt)
                throws SnmpPduEncodingException,
                       AsnDecodingException

Recovers a SnmpPduPacket or SnmpPduTrap from the passed datagram and calls the appropriate method in the handler. If an error occurs recovering the packet then an exception is generated. The pdu can be one of SnmpPduRequest or SnmpPduBulk. The internal session AsnEncoder defined in the SnmpParameters is used to recover the pdu.

Parameters:

pkt - The datagram packet to be decoded

Throws:

SnmpPduEncodingException - Thrown if a pdu or session level error occurs

AsnDecodingException - Thrown if the AsnEncoder encounters an error

See Also:

SnmpPduTrap, SnmpPduPacket, SnmpPduRequest, SnmpPduBulk, SnmpParameters, AsnEncoder

send

void send(SnmpPeer peer,
        byte[] buf,
        int length)
    throws java.io.IOException

Transmits the passed buffer to the respective peer agent. If a failure occurs then an IOException is thrown.

Parameters:

peer - The SNMP peer destination

buf - The buffer to transmit.

length - The valid length of the buffer

Throws:

java.lang.IOException - For more details see java.net.DatagramSocket.

java.io.IOException

See Also:

DatagramSocket

send

void send(SnmpPeer peer,
        byte[] buf)
    throws java.io.IOException

Transmits the passed buffer to the respective peer agent. If a failure occurs then an IOException is thrown.

Parameters:

peer - The SNMP peer destination

buf - The buffer to transmit.

Throws:

java.lang.IOException - For more details see java.net.DatagramSocket.

java.io.IOException

See Also:

DatagramSocket

setPacketHandler

void setPacketHandler(SnmpPacketHandler hdl)

Sets the default SnmpPacketHandler.

Parameters:

hdl - The new handler

getPacketHandler

SnmpPacketHandler getPacketHandler()

Gets the default SnmpPacketHandler for the session.

Returns:

the SnmpPacketHandler

setAsnEncoder

void setAsnEncoder(AsnEncoder encoder)

Sets the default encoder.

Parameters:

encoder - The new encoder

getAsnEncoder

AsnEncoder getAsnEncoder()

Gets the AsnEncoder for the session.

Returns:

the AsnEncoder

isClosed

boolean isClosed()

Returns true if this portal has had it's close method called.

close

void close()

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