Overview | Package | Class | Tree | Deprecated | Index | Help
| SNMP Stack 5_1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
  - 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,
                            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
  - IPv4 only interfaces, use address "0.0.0.0"
  - IPv6 only interfaces, use address "::"
  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()`

Overview | Package | Class | Tree | Deprecated | Index | Help
| SNMP Stack 5_1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD