SNMP Stack 5_1

uk.co.westhawk.snmp.stack
Class ListeningContext

java.lang.Object
  |
  +--uk.co.westhawk.snmp.stack.ListeningContext
All Implemented Interfaces:
ListeningContextFace, java.lang.Runnable
Direct Known Subclasses:
DefaultTrapContext

public class ListeningContext
extends java.lang.Object
implements ListeningContextFace, java.lang.Runnable

The ListeningContext class will enable this stack to receive packets. This class replaces the deprecated DefaultTrapContext class. The context will only start receiving (or listen for) packets when there is at least one listener registered.

Two kind of listeners can be added; the normal and unhandled PDU listeners. The normal PDU listeners are added via the addRawPduListener() method, the unhandled PDU listeners are added via the addUnhandledRawPduListener(). Both these listeners provide undecoded events.

The SnmpContext classes provide functionality for decoded PDU and trap events. These classes will register themselves via the addRawPduListener() to the ListeningContext object and only pass the (decoded) event on if it matches their configuration.

On UNIX and Linux operating systems the default port where PDUs and traps are sent (i.e. 161 and 162) can only be opened as root.

Only one process can listen on a certain port. To prevent more than one ListeningContext listening on the same port, use the ListeningContextPool class.

Since:
4_14
Version:
$Revision: 3.6 $ $Date: 2006/02/09 14:30:19 $
Author:
Birgit Arkesteijn
See Also:
ListeningContextPool, AbstractSnmpContext.addTrapListener(uk.co.westhawk.snmp.event.TrapListener), AbstractSnmpContext.addRequestPduListener(uk.co.westhawk.snmp.event.RequestPduListener)

Field Summary
protected  java.lang.String bindAddr
           
protected  int hostPort
           
protected  int maxRecvSize
           
protected  java.lang.String typeSocket
           
 
Fields inherited from interface uk.co.westhawk.snmp.stack.ListeningContextFace
DEFAULT_TRAP_PORT, version_id
 
Constructor Summary
ListeningContext(int port)
          Constructor, using the Standard socket type.
ListeningContext(int port, java.lang.String bindAddress)
          Constructor, using the Standard socket type.
ListeningContext(int port, java.lang.String bindAddress, java.lang.String typeSocketA)
          Constructor.
 
Method Summary
 void addRawPduListener(RawPduListener listener)
          Adds the specified PDU listener to receive the undecoded PDUs.
 void addUnhandledRawPduListener(RawPduListener listener)
          Adds the specified PDU listener to receive the undecoded PDUs when it was not handled (i.e. not consumed) by any of the PDU listeners in addRawPduListener().
 void destroy()
          This method will stop the thread listening for packets.
 java.lang.String getBindAddress()
          Returns the local address the server will bind to When the address is null, the socket accepts connections on any/all local addresses.
 int getMaxRecvSize()
          Returns the maximum number of bytes this context will read from the socket.
 int getPort()
          Returns the port number.
 java.lang.String getTypeSocket()
          Returns the type of socket.
protected  void processIncomingMessage(java.lang.String hostAddress, int port, byte[] bu)
          Processes an incoming packet.
 void removeRawPduListener(RawPduListener listener)
          Removes the specified PDU listener.
 void removeUnhandledRawPduListener(RawPduListener listener)
          Removes the specified unhandled PDU listener.
 void run()
          We wait for any incoming PDUs and fire a rawpdu received (undecoded) event if we do.
 void setMaxRecvSize(int no)
          Sets the maximum number of bytes this context will read from the socket.
protected  void startListening()
          Creates the socket and starts listening for PDUs if we didn't do so already.
 java.lang.String toString()
          Returns a string representation of the object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

maxRecvSize

protected int maxRecvSize

typeSocket

protected java.lang.String typeSocket

hostPort

protected int hostPort

bindAddr

protected java.lang.String bindAddr
Constructor Detail

ListeningContext

public ListeningContext(int port)
Constructor, using the Standard socket type.

Parameters:
port - The local port where packets are received
See Also:
SnmpContextBasisFace.STANDARD_SOCKET

ListeningContext

public ListeningContext(int port,
                        java.lang.String bindAddress)
Constructor, using the Standard socket type. If bindAddress is null, it will accept connections on any/all local addresses. If you want to listen to

Parameters:
port - The local port where packets are received
bindAddress - The local address the server will bind to
See Also:
SnmpContextBasisFace.STANDARD_SOCKET

ListeningContext

public ListeningContext(int port,
                        java.lang.String bindAddress,
                        java.lang.String typeSocketA)
Constructor. If bindAddress is null, it will accept connections on any/all local addresses. If you want to listen to The typeSocket will indicate which type of socket to use. This way different handlers can be provided for Netscape or Standard JVM. The Netscape implementation will make the necessary security calls to access connections that are not the applet's webserver. The KVM version will be for small device support (e.g. Palm Pilot).

Note, the TCP_SOCKET does not provide functionality to send a response back. Listening on such a socket is only useful when listening for traps.

Parameters:
port - The local port where packets are received
bindAddress - The local address the server will bind to
typeSocketA - The type of socket to use.
See Also:
SnmpContextBasisFace.STANDARD_SOCKET, SnmpContextBasisFace.TCP_SOCKET, SnmpContextBasisFace.NETSCAPE_SOCKET, SnmpContextBasisFace.KVM_SOCKET
Method Detail

getPort

public int getPort()
Description copied from interface: ListeningContextFace
Returns the port number.

Specified by:
getPort in interface ListeningContextFace
Returns:
The port no

getBindAddress

public java.lang.String getBindAddress()
Description copied from interface: ListeningContextFace
Returns the local address the server will bind to When the address is null, the socket accepts connections on any/all local addresses.

Specified by:
getBindAddress in interface ListeningContextFace
Returns:
The bind address

getTypeSocket

public java.lang.String getTypeSocket()
Description copied from interface: ListeningContextFace
Returns the type of socket.

Specified by:
getTypeSocket in interface ListeningContextFace
Returns:
The type of socket
See Also:
SnmpContextBasisFace.STANDARD_SOCKET, SnmpContextBasisFace.TCP_SOCKET, SnmpContextBasisFace.NETSCAPE_SOCKET, SnmpContextBasisFace.KVM_SOCKET

getMaxRecvSize

public int getMaxRecvSize()
Description copied from interface: ListeningContextFace
Returns the maximum number of bytes this context will read from the socket. By default this will be set to MSS (i.e. 1300).

Specified by:
getMaxRecvSize in interface ListeningContextFace
Returns:
The number
See Also:
SnmpContextBasisFace.MSS, ListeningContextFace.setMaxRecvSize(int), AbstractSnmpContext.setMaxRecvSize(int)

setMaxRecvSize

public void setMaxRecvSize(int no)
Description copied from interface: ListeningContextFace
Sets the maximum number of bytes this context will read from the socket. By default this will be set to MSS (i.e. 1300).

Specified by:
setMaxRecvSize in interface ListeningContextFace
Parameters:
no - The new size
See Also:
SnmpContextBasisFace.MSS, AbstractSnmpContext.getMaxRecvSize()

destroy

public void destroy()
This method will stop the thread listening for packets. All transmitters, PDUs in flight and traplisteners will be removed when run() finishes.

It closes the socket. The thread will actually stop/finish when the run() finishes. Since the socket is closed, the run() will fall through almost instantly.

Note that by calling this method the whole stack will stop listening for packets on this particular port! The listeners added via the SnmpContext classes are affected as well.

When you add a new listener, the context will start listening again.

Note: The thread(s) will not die immediately; this will take about half a minute.

Specified by:
destroy in interface ListeningContextFace

run

public void run()
We wait for any incoming PDUs and fire a rawpdu received (undecoded) event if we do.

The undecoded events are fired to all normal listeners (added via addRawPduListener()), until one of them consumes it. The SnmpContext classes will consume the event if it matches their configuration.

If none of them consume the event, the undecoded events are fired to all unhandled PDU listeners (added via addUnhandledRawPduListener()), until one of them consumes it.

Specified by:
run in interface java.lang.Runnable
See Also:
RawPduReceivedSupport.fireRawPduReceived(int, java.lang.String, int, byte[]), addRawPduListener(RawPduListener), addUnhandledRawPduListener(RawPduListener)

addRawPduListener

public void addRawPduListener(RawPduListener listener)
                       throws java.io.IOException
Description copied from interface: ListeningContextFace
Adds the specified PDU listener to receive the undecoded PDUs. When a PDU is received the PDU received event is fired to all listeners, until one of them consumes it.

All the SnmpContext objects use this method to listen for PDUs. When a SnmpContext object decodes the PDU succesfully, it will consume it.

Only when a listener is added will this context create a listening socket.

Specified by:
addRawPduListener in interface ListeningContextFace
Parameters:
listener - The listener object
Throws:
java.io.IOException - Thrown when creating a listening socket fails
See Also:
RawPduReceivedSupport.fireRawPduReceived(int, java.lang.String, int, byte[]), AbstractSnmpContext.addTrapListener(uk.co.westhawk.snmp.event.TrapListener), AbstractSnmpContext.addRequestPduListener(uk.co.westhawk.snmp.event.RequestPduListener), ListeningContextFace.addUnhandledRawPduListener(RawPduListener)

removeRawPduListener

public void removeRawPduListener(RawPduListener listener)
Description copied from interface: ListeningContextFace
Removes the specified PDU listener. When there are no more listeners, calls destroy().

Specified by:
removeRawPduListener in interface ListeningContextFace
Parameters:
listener - The listener object

addUnhandledRawPduListener

public void addUnhandledRawPduListener(RawPduListener listener)
                                throws java.io.IOException
Description copied from interface: ListeningContextFace
Adds the specified PDU listener to receive the undecoded PDUs when it was not handled (i.e. not consumed) by any of the PDU listeners in addRawPduListener().

Only when a listener is added will this context create a listening socket.

Specified by:
addUnhandledRawPduListener in interface ListeningContextFace
Throws:
java.io.IOException - Thrown when creating a listening socket fails
See Also:
ListeningContextFace.addRawPduListener(RawPduListener)

removeUnhandledRawPduListener

public void removeUnhandledRawPduListener(RawPduListener listener)
Description copied from interface: ListeningContextFace
Removes the specified unhandled PDU listener. When there are no more listeners, calls destroy().

Specified by:
removeUnhandledRawPduListener in interface ListeningContextFace

startListening

protected void startListening()
                       throws java.io.IOException
Creates the socket and starts listening for PDUs if we didn't do so already. This method is called in addRawPduListener() and addUnhandledRawPduListener().

Throws:
java.io.IOException - Thrown when the socket cannot be created.
See Also:
addRawPduListener(uk.co.westhawk.snmp.event.RawPduListener), addUnhandledRawPduListener(uk.co.westhawk.snmp.event.RawPduListener)

toString

public java.lang.String toString()
Returns a string representation of the object.

Overrides:
toString in class java.lang.Object
Returns:
The string

processIncomingMessage

protected void processIncomingMessage(java.lang.String hostAddress,
                                      int port,
                                      byte[] bu)
                               throws DecodingException,
                                      java.io.IOException
Processes an incoming packet.

DecodingException
java.io.IOException
See Also:
run()

SNMP Stack 5_1