uk.co.westhawk.snmp.stack
Class AbstractSnmpContext

java.lang.Object
  |
  +--uk.co.westhawk.snmp.stack.AbstractSnmpContext

All Implemented Interfaces:

java.util.EventListener, java.lang.Runnable, SnmpContextBasisFace, TrapListener

Direct Known Subclasses:

SnmpContext, SnmpContextv3

public abstract class AbstractSnmpContext

extends java.lang.Object

implements SnmpContextBasisFace, java.lang.Runnable, TrapListener

This class contains the abstract SNMP context that is needed by every Pdu to send a SNMP v1, v2c or v3 request. The context also provides functionality to receive traps.

destroy() should be called when the context is no longer used. This is the only way the threads will be stopped and garbage collected.

Version:

$Revision: 3.21 $ $Date: 2002/11/06 11:28:19 $

Author:

Tim Panton

See Also:

SnmpContext, SnmpContextv2c, SnmpContextv3

Field Summary

protected java.lang.String	hostAddr
protected int	hostPort
protected boolean	isDestroyed
protected int	maxRecvSize
protected java.lang.String	typeSocket

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

DEFAULT_PORT, KVM_SOCKET, MAXPDU, MSS, NETSCAPE_SOCKET, STANDARD_SOCKET, version_id

Fields inherited from interface uk.co.westhawk.snmp.event.TrapListener

version_id

Constructor Summary

protected	AbstractSnmpContext(java.lang.String host, int port) Constructor.
protected	AbstractSnmpContext(java.lang.String host, int port, java.lang.String typeSocketA) Constructor.

Method Summary

protected void	activate() Creates and starts the Receive thread that allows this context to receive packets.
boolean	addPdu(Pdu p) Adds a pdu.
void	addTrapListener(TrapListener l) Adds the specified trap listener to receive traps from the host that matches this context.
void	destroy() This method will stop the thread.
abstract byte[]	encodePacket(byte msg_type, int rId, int errstat, int errind, java.util.Enumeration ve) Encodes a packet.
java.lang.String	getDebugString() Returns the thread usage of the AbstractSnmpContext.
java.lang.String	getHost() Returns the host
java.lang.String	getHostAddress() Returns the IP address string "%d.%d.%d.%d" of the host.
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 socket
abstract int	getVersion() Return the SNMP version of this context.
protected abstract void	ProcessIncomingMessage(uk.co.westhawk.snmp.stack.AsnDecoder rpdu, java.io.ByteArrayInputStream in) Processes an incoming response.
abstract Pdu	processIncomingTrap(byte[] message) Processes an incoming trap.
boolean	removePdu(int rid) Removes a pdu.
void	removeTrapListener(TrapListener l) Removes the specified trap listener.
void	run() We wait for any incoming packets.
void	sendPacket(byte[] p) Pass a correctly encoded SNMP packet, and we'l send it...
void	setMaxRecvSize(int no) Sets the maximum number of bytes this context will read from the socket.
void	stop() Deprecated. As of version 4_12, should use destroy()
void	trapReceived(TrapEvent evt) Invoked when an undecoded trap is received.

Methods inherited from class java.lang.Object

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

Field Detail

typeSocket

protected java.lang.String typeSocket

hostAddr

protected java.lang.String hostAddr

hostPort

protected int hostPort

maxRecvSize

protected int maxRecvSize

isDestroyed

protected boolean isDestroyed

Constructor Detail

AbstractSnmpContext

protected AbstractSnmpContext(java.lang.String host,
                              int port)
                       throws java.io.IOException

Constructor. The Standard socket type will be used.

Parameters:

host - The host to which the Pdu will send

port - The port where the SNMP server will be

See Also:

SnmpContextBasisFace.STANDARD_SOCKET

AbstractSnmpContext

protected AbstractSnmpContext(java.lang.String host,
                              int port,
                              java.lang.String typeSocketA)
                       throws java.io.IOException

Constructor. 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 hosts that are not the applet's webserver. The KVM version will be for small device support (e.g. Palm Pilot).

Parameters:

host - The host to which the Pdu will send

port - The port where the SNMP server will be

typeSocketA - The type of socket to use.

See Also:

SnmpContextBasisFace.STANDARD_SOCKET, SnmpContextBasisFace.NETSCAPE_SOCKET, SnmpContextBasisFace.KVM_SOCKET

Method Detail

ProcessIncomingMessage

protected abstract void ProcessIncomingMessage(uk.co.westhawk.snmp.stack.AsnDecoder rpdu,
                                               java.io.ByteArrayInputStream in)
                                        throws DecodingException,
                                               java.io.IOException

Processes an incoming response. Has to be overload by each context.

See Also:

run()

encodePacket

public abstract byte[] encodePacket(byte msg_type,
                                    int rId,
                                    int errstat,
                                    int errind,
                                    java.util.Enumeration ve)
                             throws java.io.IOException,
                                    EncodingException

Encodes a packet. Has to be overload by each context.

Specified by:

encodePacket in interface SnmpContextBasisFace

Following copied from interface: uk.co.westhawk.snmp.stack.SnmpContextBasisFace

Returns:

The encoded packet

processIncomingTrap

public abstract Pdu processIncomingTrap(byte[] message)
                                 throws DecodingException,
                                        java.io.IOException

Processes an incoming trap. Has to be overload by each context.

Specified by:

processIncomingTrap in interface SnmpContextBasisFace

See Also:

trapReceived(uk.co.westhawk.snmp.event.TrapEvent)

getVersion

public abstract int getVersion()

Return the SNMP version of this context. Has to be overload by each context.

Specified by:

getVersion in interface SnmpContextBasisFace

Following copied from interface: uk.co.westhawk.snmp.stack.SnmpContextBasisFace

Returns:

The version

activate

protected void activate()

Creates and starts the Receive thread that allows this context to receive packets. Subclasses may override this to adjust the threading behaviour.

See Also:

PassiveSnmpContext.activate(), PassiveSnmpContextv2c.activate()

getHost

public java.lang.String getHost()

Returns the host

Specified by:

getHost in interface SnmpContextBasisFace

Returns:

The host

getHostAddress

public java.lang.String getHostAddress()

Returns the IP address string "%d.%d.%d.%d" of the host.

Returns:

The IP address of the host

See Also:

InetAddress.getHostAddress()

getPort

public int getPort()

Returns the port number

Specified by:

getPort in interface SnmpContextBasisFace

Returns:

The port no

getTypeSocket

public java.lang.String getTypeSocket()

Returns the type socket

Specified by:

getTypeSocket in interface SnmpContextBasisFace

Returns:

The type socket

getMaxRecvSize

public int getMaxRecvSize()

Returns the maximum number of bytes this context will read from the socket. By default this will be set to MSS (i.e. 1300).

Returns:

The number

Since:

4_12

See Also:

SnmpContextBasisFace.MSS, setMaxRecvSize(int)

setMaxRecvSize

public void setMaxRecvSize(int no)

Sets the maximum number of bytes this context will read from the socket. By default this will be set to MSS (i.e. 1300). The default size seems a reasonable size. The problem usually occurs when sending Bulk requests.

If a packet arrives that is bigger than the maximum size of received bytes, the stack will try to decode it nevertheless. The usual error that will occur is:

 Error message: "Incorrect packet. No of bytes received less than packet length."
 

Although UDP datagrams can be fragmented (fragmentation is part of the network layer (IP), not the transport layer (UDP/TCP)), some firewalls reject incoming fragments. Therefor it is best not to set maxRecvSize higher than the largest packet size you can get through your network topology.

Thanks to Pete Kazmier (pete@kazmier.com) for the suggestion.

Note, this property is NOT supported in any of the SNMPContextXXPool classes.

Parameters:

no - The new number

Since:

4_12

See Also:

SnmpContextBasisFace.MSS, getMaxRecvSize()

getDebugString

public java.lang.String getDebugString()

Returns the thread usage of the AbstractSnmpContext. It returns a String in the form of =PO=QR--------------0.

The String represents the array of transmitters. Each character represents a transmitter slot. The transmitters form a thread pool of a maximum size, MAXPDU. Each transmitter is used to wait for one PDU response at a given moment in time. When the response is received the transmitter will stop running, but is not destroyed. It will be reused.

Meaning of each character:

• - a transmitter slot has not yet been allocated a thread
• = there is a thread but it is idle
• A->Z the thread is transmitting a Pdu
• The last character represents the context's recv thread:
  • 0 there isn't one
  • 1 it exists but isn't running
  • 2 it exists and is alive.

Returns:

The thread usage of the AbstractSnmpContext

Since:

4_12

destroy

public void destroy()

This method will stop the thread. All transmitters, pdus in flight and traplisteners will be removed when run() finishes.

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

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

Specified by:

destroy in interface SnmpContextBasisFace

stop

public void stop()

Deprecated. As of version 4_12, should use destroy()

This method will stop the thread. All transmitters, pdus in flight and traplisteners will be removed when run() finishes.

It does NOT close the socket. The tread will actually stop/finish when the run() finishes. That is when a packet arrives on the socket or when the socket times out.

We have deprecated this method since there is no point in stopping the context, but not destroying it. The context cannot start again anyway. The difference between destroy() and stop() was not very clear.

See Also:

destroy()

run

public void run()

We wait for any incoming packets. After receiving one, decode the packet into an Pdu. The Pdu will notify the observers waiting for an response.

Specified by:

run in interface java.lang.Runnable

sendPacket

public void sendPacket(byte[] p)

Pass a correctly encoded SNMP packet, and we'l send it...

Specified by:

sendPacket in interface SnmpContextBasisFace

Following copied from interface: uk.co.westhawk.snmp.stack.SnmpContextBasisFace

Parameters:

packet - The encoded packet

removePdu

public boolean removePdu(int rid)

Removes a pdu.

Specified by:

removePdu in interface SnmpContextBasisFace

Parameters:

rid - the Pdu request id

Returns:

whether the pdu has been successfully removed

addPdu

public boolean addPdu(Pdu p)
               throws java.io.IOException,
                      PduException

Adds a pdu. A transmitter is allocated to this pdu as well.

Specified by:

addPdu in interface SnmpContextBasisFace

Parameters:

pdu - the Pdu

Returns:

whether the pdu has been successfully added

addTrapListener

public void addTrapListener(TrapListener l)
                     throws java.io.IOException

Adds the specified trap listener to receive traps from the host that matches this context.

The DefaultTrapContext class will do the actual listening for traps. This context will add itself to the DefaultTrapContext object and will only pass the event to its listeners if the trap matches this context. Note that the portnumber of this class is ignored. Unless there already exists a DefaultTrapContext object, the DEFAULT_TRAP_PORT is used.

Specified by:

addTrapListener in interface SnmpContextBasisFace

See Also:

DefaultTrapContext.getInstance(int, String), DefaultTrapContext.addTrapListener(TrapListener), DefaultTrapContext.DEFAULT_TRAP_PORT

removeTrapListener

public void removeTrapListener(TrapListener l)
                        throws java.io.IOException

Removes the specified trap listener.

Specified by:

removeTrapListener in interface SnmpContextBasisFace

trapReceived

public void trapReceived(TrapEvent evt)

Invoked when an undecoded trap is received. First the version and the hostaddress are checked, if correct an attempt is made to decode the trap. When successful the original event is consumed and a decoded trap event is passed on the listeners.

Specified by:

trapReceived in interface TrapListener

See Also:

TrapReceivedSupport.fireTrapReceived(Pdu)