Package uk.co.westhawk.snmp.stack

Class ListeningContext

java.lang.Object

uk.co.westhawk.snmp.stack.ListeningContext

All Implemented Interfaces:

Runnable, ListeningContextFace

Direct Known Subclasses:

DefaultTrapContext

public class ListeningContext
extends Object
implements ListeningContextFace, 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.12 $ $Date: 2009/03/05 13:24:00 $

Author:

Birgit Arkesteijn

See Also:

• ListeningContextPool
• AbstractSnmpContext.addTrapListener(uk.co.westhawk.snmp.event.TrapListener)
• AbstractSnmpContext.addRequestPduListener(uk.co.westhawk.snmp.event.RequestPduListener)

Field Summary

Fields inherited from interface uk.co.westhawk.snmp.stack.ListeningContextFace

DEFAULT_TRAP_PORT

Constructor Summary

Constructors

Constructor	Description
ListeningContext(int port)	Constructor, using the Standard socket type.
ListeningContext(int port, String bindAddress)	Constructor, using the Standard socket type.
ListeningContext(int port, String bindAddress, String typeSocketA)	Constructor.

Method Summary

Modifier and Type	Method	Description
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.
void	destroy()	This method will stop the thread listening for packets.
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.
String	getHashKey()	Returns the hash key.
int	getMaxRecvSize()	Returns the maximum number of bytes this context will read from the socket.
int	getPort()	Returns the port number.
String	getTypeSocket()	Returns the type of socket.
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.
String	toString()	Returns a string representation of the object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

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,
 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

• IPv4 only interfaces, use address "0.0.0.0"
• IPv6 only interfaces, use address "::"

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,
 String bindAddress,
 String typeSocketA)

Constructor. If bindAddress is null, it will accept connections on any/all local addresses. If you want to listen to

• IPv4 only interfaces, use address "0.0.0.0"
• IPv6 only interfaces, use address "::"

The typeSocketA will indicate which type of socket to use. This way different handlers can be provided. This parameter should be either STANDARD_SOCKET, TCP_SOCKET or a fully qualified classname.

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

Method Details

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 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 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

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 Runnable

See Also:

• RawPduReceivedSupport.fireRawPduReceived(int, java.lang.String, int, byte[])
• addRawPduListener(RawPduListener)
• addUnhandledRawPduListener(RawPduListener)

addRawPduListener

public void addRawPduListener(RawPduListener listener)
                       throws 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:

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 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

Parameters:

listener - The listener object

Throws:

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

Parameters:

listener - The listener object

getHashKey

public String getHashKey()

Returns the hash key. This key is built out of all properties. It serves as key for the pool of contexts.

Returns:

The hash key

toString

public String toString()

Returns a string representation of the object.

Overrides:

toString in class Object

Returns:

The string