com.adventnet.snmp.beans
Class SnmpTrapReceiver

java.lang.Object
  |
  +--com.adventnet.snmp.beans.SnmpTrapReceiver

All Implemented Interfaces:

java.io.Serializable, SnmpClient

public class SnmpTrapReceiver

extends java.lang.Object

implements SnmpClient, java.io.Serializable

Receives SNMP Traps from SNMP Agents. Generate a TrapEvent for each trap received. This class can be used with beans, applications and applets. It supports event generation as per the JDK 1.1 event model.

To use in an application, simply instantiate, specify the port, and register to receive traps. For example,

   SnmpTrapReceiver receiver = new SnmpTrapReceiver();
   
   TrapListener listener = new TrapListener() {
       public void receivedTrap(TrapEvent trap) {
           System.err.println("Got a trap from: "+trap.getRemoteHost());
       }
   };
 

   receiver.addTrapListener(listener);
   
   try {
      receiver.setPortWithExceptionMsg(162);
   }
   catch(SnmpException e) {
       System.err.println(e.getMessage());
   }
   
 

The resources used by this class are automatically garbage collected after removing all the registered listeners. No need to close sessions, or other cleanup by the user.

Supply the applet in the constructor if using applets and may need to use SAS.

See Also:

Serialized Form

Constructor Summary

SnmpTrapReceiver()
Use this constructor for applications.

SnmpTrapReceiver(java.applet.Applet applet)
Use this constructor for applets.

SnmpTrapReceiver(int protocol, ProtocolOptions options)
Use this constructor for applications while using generic transportprovider.

Method Summary

void	addLogClient(LogInterface client) add the Log client for which the trapreceiver has to redirect the log messages
void	addTrapListener(TrapListener l) Adds a listener for events from this target.
boolean	authenticate(SnmpPDU pdu, java.lang.String community) Authenticates the received Trap PDU.
boolean	callback(SnmpSession session, SnmpPDU pdu, int requestID) this is the method that processes and forward the trap.
void	cleanup() Deprecated. Replaced by stop() method.
void	createUserEntry(byte[] engineID, byte secLevel) Creates a usm user entry with the given EngineID and Security Level, in the USM Table.
void	debugPrint(java.lang.String debugOutput) This is the SnmpClient method implementation that redirects the log message to standard output or to client directly if it implements LogInterface.
protected void	finalize() This cleans up the common connection if no one is using
java.lang.String	getAuthPassword() Gets authentication password.
int	getAuthProtocol() Gets the Authentication Protocol.
java.lang.String	getCharacterEncoding() Get the Character Encoding being used.
java.lang.String	getCommunity() Gets the SNMP Community.
java.lang.String	getcontextID() Deprecated. Replaced with getContextID()
java.lang.String	getContextID() Gets the SNMP V3 contextID
java.lang.String	getContextName() Gets the SNMP V3 Context name
java.lang.String[]	getLocalAddresses() Gets the local addresses to listen on.
java.lang.String	getMibModules() Gets the MIBs loaded in this applet/application - a white-space separated list of mib files.
MibOperations	getMibOperations() Gets the MibOperations object reference.
java.lang.String	getMibPath() Gets the search Path in which the Mib Parser will search for the MIB modules.
int	getPort() Gets the local SNMP port number to listen on.
int	getPortWithExceptionMsg() Gets the local SNMP port number to listen on.
java.lang.String	getPrincipal() Gets Principal ie userName
java.lang.String	getPrivPassword() Gets the SNMPv3 privacy password.
int	getReceiveBufferSize() This method returns the buffer size of this SnmpTrapReceiver.
int	getSecurityModel() Gets the SNMP V3 securityModel
java.lang.Object	getSecurityTable(int secModel) Gets the SecurityModelTable as an object for a given security Model.
int	getSnmpVersion() Gets the SNMP Version
USMUserTable	getUSMTable() Gets the USMUserTable reference.
void	initJdbcParams(java.lang.String driverName, java.lang.String URL, java.lang.String userName, java.lang.String passWord) If you need to use database support for mibs, this method should be invoked to initialize the Jdbc Parameters.
void	initSecurityProvider() Initializes the SecurityProvider by reading from the file securityProvider.config.
boolean	isLoadMibsFromDatabase() Gets the loadFromDataBase boolean
boolean	isOverwriteMibsInDatabase() Gets the overwrite mibs in DataBase boolean.
boolean	isSetAutoInformResponse() High level API method to check if the automatic response flag for the Inform Request is set.
boolean	isSupportedSecurityModel(int secModel) Specifies if a particular security model is supported or not.
boolean	isTrapAuthEnable() To Check whether SNMPV3 traps are authenticated.
void	loadMibs(java.lang.String mibs) Load the mibs specified by white-space separated list of mibs.
void	releaseResources() Though the resources will be cleaned up by the garbage collector, if the application is no more using the SnmpTrapReceiver bean instances, this method can be used to immediately release the resources.
void	removeTrapListener(TrapListener l) Removes a listener for events from this target.
void	setAuthPassword(java.lang.String password) Sets authentication password for SNMPv3 authentication.
void	setAuthProtocol(int protocol) Sets the Authentication Protocol.
void	setAutoInformResponse(boolean flag) High-level API method to set the automatic response flag for the Inform Request.
void	setCallbackthread(boolean flag) Enable or disable if the user wants the callback to be called from a seperate thread.
void	setCharacterEncoding(java.lang.String enc) Set the Character Encoding to be used.
void	setCommunity(java.lang.String s) Sets the SNMP Community.
void	setcontextID(byte[] ctxtID) Deprecated. Replaced with setContextID(byte[] ctxtID)
void	setContextID(byte[] ctxtID) Sets the SNMP V3 contextID
void	setContextName(java.lang.String cName) Sets the SNMP V3 Context name
void	setDebug(boolean debug) Determines if debug output will be printed
void	setLoadMibsFromDatabase(boolean flag) Defines whether to load mib from DataBase.
void	setLocalAddresses(java.lang.String[] addresses) Sets the local SNMP port number to listen on.
void	setMibModules(java.lang.String mibs) Sets the MIB loaded in this applet/application.
void	setMibPath(java.lang.String searchPath) Sets the search path in which the Mib Parser will search for the MIB modules.
void	setOverwriteMibsInDatabase(boolean overWrite) Defines whether to overwrite the MIB in the DataBase.
void	setPort(int i) Sets the local SNMP port number to listen on.
void	setPortWithExceptionMsg(int i) Sets the local SNMP port number to listen on and throws SnmpException in case of BindException.
void	setPrincipal(java.lang.String userName) Sets the Principal or authentication user name.
void	setPrivPassword(java.lang.String password) Sets the privacy password.
void	setReceiveBufferSize(int size) This method sets the buffer size of this SnmpTrapReceiver.
void	setSecurityModel(int securityModel) Sets the SNMP V3 SecurityModel
void	setSnmpVersion(int version) Sets the SNMP Version
void	setTrapAuthEnable(boolean isAuth) Specify whether traps should be authenticated while receiving SNMPV3 trap messages.
void	stop() Stops receiving traps.

Methods inherited from class java.lang.Object

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

Constructor Detail

SnmpTrapReceiver

public SnmpTrapReceiver()

Use this constructor for applications. Use for applets only if you want to prevent the use of SAS. MIB loading from applets may fail from this SnmpTrapReceiver instance if you use this constructor. This matters only for the first SnmpTrapReceiver instance, and subsequent instances will use the same SNMP mechanisms for the same port.

Invoke setPortWithExpMesg(int) method to start receiving trap on the specified port.

stop() method can be used to stop receiving traps.

SnmpTrapReceiver

public SnmpTrapReceiver(int protocol,
                        ProtocolOptions options)

Use this constructor for applications while using generic transportprovider.

SnmpTrapReceiver

public SnmpTrapReceiver(java.applet.Applet applet)

Use this constructor for applets. Applets will try and use SAS, and if unsuccessful will use local sockets. MIB loading from applets may fail from this SnmpTrapReceiver instance if you use this constructor. This matters only for the first SnmpTrapReceiver instance, and subsequent instances will use the same SNMP mechanisms for the same port.

Invoke setPortWithExpMesg(int) method to start receiving trap on the specified port.

stop() method can be used to stop receiving traps.

Method Detail

loadMibs

public void loadMibs(java.lang.String mibs)
              throws MibException,
                     java.io.IOException,
                     java.io.FileNotFoundException

Load the mibs specified by white-space separated list of mibs. If first SnmpTrapReceiver has been opened with applet parameter, then URLs will be used. MIB loading applies across all beans in this package, i.e. MIBs can be loaded in any of the bean instances, and will be available across all beans in this package, across the VM.

Throws:

MibException - is thrown when parse error occurs.

java.io.IOException - is thrown when IO error occurs.

java.io.FileNotFoundException - is thrown if the file is not found.

setMibPath

public void setMibPath(java.lang.String searchPath)

Sets the search path in which the Mib Parser will search for the MIB modules. Multiple paths can be specified using the pipe (|) as a seperator.

Parameters:

searchPath- - String specifying the search path, for multiple paths seperate the paths by the pipe

getMibPath

public java.lang.String getMibPath()

Gets the search Path in which the Mib Parser will search for the MIB modules.

Returns:

String containing the path which will be searched for the MIBs. Null if the searchPath has not been set previously

addTrapListener

public void addTrapListener(TrapListener l)

Adds a listener for events from this target. The listener listens for events from any or all SNMP requests.

removeTrapListener

public void removeTrapListener(TrapListener l)

Removes a listener for events from this target.

getMibOperations

public MibOperations getMibOperations()

Gets the MibOperations object reference. This allows using additonal MibOperations functions if needed.

setDebug

public void setDebug(boolean debug)

Determines if debug output will be printed

getMibModules

public java.lang.String getMibModules()

Gets the MIBs loaded in this applet/application - a white-space separated list of mib files.

setMibModules

public void setMibModules(java.lang.String mibs)

Sets the MIB loaded in this applet/application.

authenticate

public boolean authenticate(SnmpPDU pdu,
                            java.lang.String community)

Authenticates the received Trap PDU.

Specified by:

authenticate in interface SnmpClient

Returns:

true if SnmpPDU is null or the community (incase of v1 and v2c) matches . The PDU will be null if an ASN.1 or BER error occurs while decoding. Therefore, in case of SNMPV3 a Trap received with bad privacy password will result in a null PDU. So in this case an event is generated with TrapPDU as null. If the community doesn't match this method returns false and the PDU is dropped. In case of SNMPV3 if the authentication module fails and the value returned by isTrapAuthEnable() is true, then the TrapPDU is dropped.

See Also:

isTrapAuthEnable(), setTrapAuthEnable()

callback

public boolean callback(SnmpSession session,
                        SnmpPDU pdu,
                        int requestID)

this is the method that processes and forward the trap.

Specified by:

callback in interface SnmpClient

debugPrint

public void debugPrint(java.lang.String debugOutput)

This is the SnmpClient method implementation that redirects the log message to standard output or to client directly if it implements LogInterface.

Specified by:

debugPrint in interface SnmpClient

addLogClient

public void addLogClient(LogInterface client)

add the Log client for which the trapreceiver has to redirect the log messages

Parameters:

id- - client id

initJdbcParams

public void initJdbcParams(java.lang.String driverName,
                           java.lang.String URL,
                           java.lang.String userName,
                           java.lang.String passWord)

If you need to use database support for mibs, this method should be invoked to initialize the Jdbc Parameters.

Parameters:

URL - URL pointing to the DataBase file name

userName - userName

passWord - password

setLoadMibsFromDatabase

public void setLoadMibsFromDatabase(boolean flag)

Defines whether to load mib from DataBase. The Jdbc Parameters should be set, using the initJdbcParams(), before calling this method. This flag should be set before loading the MIBs (By default it is set to false). If this flag is set to true, it will parse the mibs,and store it in the database. For ex: RMON2-MIB is loaded, it will parse the mib and store it in the database.

Parameters:

flag - boolean

See Also:

initJdbcParams(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

setOverwriteMibsInDatabase

public void setOverwriteMibsInDatabase(boolean overWrite)

Defines whether to overwrite the MIB in the DataBase. NOTE: This applies only when the setLoadFromDataBase is set to true.

isOverwriteMibsInDatabase

public boolean isOverwriteMibsInDatabase()

Gets the overwrite mibs in DataBase boolean. NOTE: This applies only when the setLoadFromDataBase is set to true.

isLoadMibsFromDatabase

public boolean isLoadMibsFromDatabase()

Gets the loadFromDataBase boolean

finalize

protected void finalize()
                 throws java.lang.Throwable

This cleans up the common connection if no one is using

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - in case of finalization of errors

releaseResources

public void releaseResources()

Though the resources will be cleaned up by the garbage collector, if the application is no more using the SnmpTrapReceiver bean instances, this method can be used to immediately release the resources. Close the session and api if number of targets sharing it becomes zero. Otherwise decrement the targets count for that session and api. This cleans up the common connection if no one is using the resources.

cleanup

public void cleanup()

Deprecated. Replaced by stop() method.

This cleans up the common connection.

stop

public void stop()

Stops receiving traps. Invokes setPortWithExpMsg(int) method to restart.

Since:

Release 3.0

getLocalAddresses

public java.lang.String[] getLocalAddresses()

Gets the local addresses to listen on.

setLocalAddresses

public void setLocalAddresses(java.lang.String[] addresses)

Sets the local SNMP port number to listen on.

getPort

public int getPort()

Gets the local SNMP port number to listen on.

setPort

public void setPort(int i)

Sets the local SNMP port number to listen on.

getPortWithExceptionMsg

public int getPortWithExceptionMsg()

Gets the local SNMP port number to listen on.

setPortWithExceptionMsg

public void setPortWithExceptionMsg(int i)
                             throws SnmpException

Sets the local SNMP port number to listen on and throws SnmpException in case of BindException. This will allow the api users to catch the exception and dispaly a message.

Throws:

SnmpException - if the socket could not be opened, or the socket could not bind to the specified local port.

Since:

Release 2.2

getCommunity

public java.lang.String getCommunity()

Gets the SNMP Community. The default value is null.

Returns:

The community of this SnmpTrapReceiver.

setCommunity

public void setCommunity(java.lang.String s)

Sets the SNMP Community. The default value is null.

Parameters:

s - The community value to be set on this SnmpTrapReceiver.

setCallbackthread

public void setCallbackthread(boolean flag)

Enable or disable if the user wants the callback to be called from a seperate thread. By default it is diabled.

Parameters:

flag - true flag enables the callbcak thread.

getSnmpVersion

public int getSnmpVersion()

Gets the SNMP Version

setSnmpVersion

public void setSnmpVersion(int version)

Sets the SNMP Version

isTrapAuthEnable

public boolean isTrapAuthEnable()

To Check whether SNMPV3 traps are authenticated. If true, the received SNMPV3 traps are authenticated. If false, the received SNMPV3 traps are not authenticated.

Returns:

true or false.

setTrapAuthEnable

public void setTrapAuthEnable(boolean isAuth)

Specify whether traps should be authenticated while receiving SNMPV3 trap messages. Default value is false.

Parameters:

isAuth - sets this to true if traps should be authenticated while receiving SNMPV3 trap messages. False otherwise.

getContextName

public java.lang.String getContextName()

Gets the SNMP V3 Context name

setContextName

public void setContextName(java.lang.String cName)

Sets the SNMP V3 Context name

getcontextID

public java.lang.String getcontextID()

Deprecated. Replaced with getContextID()

Gets the SNMP V3 contextID

setcontextID

public void setcontextID(byte[] ctxtID)

Deprecated. Replaced with setContextID(byte[] ctxtID)

Sets the SNMP V3 contextID

getContextID

public java.lang.String getContextID()

Gets the SNMP V3 contextID

setContextID

public void setContextID(byte[] ctxtID)

Sets the SNMP V3 contextID

getSecurityModel

public int getSecurityModel()

Gets the SNMP V3 securityModel

setSecurityModel

public void setSecurityModel(int securityModel)

Sets the SNMP V3 SecurityModel

getPrincipal

public java.lang.String getPrincipal()

Gets Principal ie userName

setPrincipal

public void setPrincipal(java.lang.String userName)

Sets the Principal or authentication user name.

Parameters:

user - name.

getAuthProtocol

public int getAuthProtocol()

Gets the Authentication Protocol.

setAuthProtocol

public void setAuthProtocol(int protocol)

Sets the Authentication Protocol. The MD5 protocol is 21 and for SHA protocol is 22.

Parameters:

the - number of the protocol.

getAuthPassword

public java.lang.String getAuthPassword()

Gets authentication password.

Returns:

authentication passowrd as string.

setAuthPassword

public void setAuthPassword(java.lang.String password)

Sets authentication password for SNMPv3 authentication.

getPrivPassword

public java.lang.String getPrivPassword()

Gets the SNMPv3 privacy password. The privacy password contains only the password and not the localised key.

Returns:

privacy password.

setPrivPassword

public void setPrivPassword(java.lang.String password)

Sets the privacy password.

initSecurityProvider

public void initSecurityProvider()
                          throws SnmpException

Initializes the SecurityProvider by reading from the file securityProvider.config. It will register all the security models specified in the securityProvider.config file.

Throws:

SnmpException - - if the file could not be found or if the security model could not be registered.

getSecurityTable

public java.lang.Object getSecurityTable(int secModel)

Gets the SecurityModelTable as an object for a given security Model. SecurityModelTable is an abstract class which contains a list of SecurityModelEntry objects belonging to a particular securityModel.

Returns:

The SecurityModelTable as an object. Null if the SecurityModelTable is not created.

isSupportedSecurityModel

public boolean isSupportedSecurityModel(int secModel)

Specifies if a particular security model is supported or not.

Parameters:

m - - The security model number which needs to be checked if it is supported.

Returns:

True if the specified securityModel is supported. False otherwise.

getUSMTable

public USMUserTable getUSMTable()

Gets the USMUserTable reference.

Returns:

USM User Table.

createUserEntry

public void createUserEntry(byte[] engineID,
                            byte secLevel)

Creates a usm user entry with the given EngineID and Security Level, in the USM Table.

Parameters:

engineID - - Engine ID of the usm user entry to be created.

secLevel - - Security Level.

isSetAutoInformResponse

public boolean isSetAutoInformResponse()

High level API method to check if the automatic response flag for the Inform Request is set. The default value is true.

Returns:

boolean value of the Inform Request response flag.

setAutoInformResponse

public void setAutoInformResponse(boolean flag)

High-level API method to set the automatic response flag for the Inform Request. If this flag is set to true, then the SNMP stack automatically sends a Get Reponse message back to the sender. The default value is true.

Parameters:

flag - boolean value of the flag to be set.

setCharacterEncoding

public void setCharacterEncoding(java.lang.String enc)

Set the Character Encoding to be used. The encoding specified will be used internally to convert String <--> byte[]. The Default value is ISO8859_1.

Parameters:

enc - The name of a character encoding. All the string encoding will be done based on this encoding.

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Get the Character Encoding being used. This encoding scheme will be used internally to convert String <--> byte[]. The Default value is ISO8859_1.

Returns:

enc The character encoding used.

setReceiveBufferSize

public void setReceiveBufferSize(int size)

This method sets the buffer size of this SnmpTrapReceiver. This method SHOULD be called only when jdk1.2 and higher version is used.

Parameters:

size - the size of the buffer.

getReceiveBufferSize

public int getReceiveBufferSize()

This method returns the buffer size of this SnmpTrapReceiver. This method SHOULD be called only when jdk1.2 and higher version is used.

Returns:

the buffer size of this receiver.