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() Deprecated. use the method getPort() instead.
java.lang.String	getPrincipal() Gets Principal ie userName
java.lang.String	getPrivPassword() Gets the SNMPv3 privacy password.
int	getPrivProtocol() Gets the privacy protocol.
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.
java.text.SimpleDateFormat	getSimpleDateFormat() Gets the SimpleDateFormat for this class.
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	isCommunityAuthEnabled() To check whether the v1/v2 traps are authenticated with their community name and received If true, the received traps are authenticated.
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 traps are authenticated.
boolean	isV3AuthEnabled() To check whether the v3 traps are authenticated and received If true, the received 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	setCommunityAuthEnable(boolean commauth) Specify whether the community name should be authenticated or not for v1/v2 traps By default the authentication is enabled
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 addresses 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 an SnmpException in case of a 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	setPrivProtocol(int protocol) Sets the privacy protocol.
void	setReceiveBufferSize(int size) This method sets the buffer size of this SnmpTrapReceiver.
void	setSecurityModel(int securityModel) Sets the SNMP V3 SecurityModel
void	setSimpleDateFormat(java.text.SimpleDateFormat sdf) Sets the SimpleDateFormat for this class.
void	setSnmpVersion(int version) Sets the SNMP Version
void	setTrapAuthEnable(boolean isAuth) Specify whether traps should be authenticated while receiving it.
void	setV3AuthEnable(boolean v3auth) Specify whether the v3 trap should be authenticated or not.
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 setPortWithExceptionMsg(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 setPortWithExceptionMsg(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 separator.

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 additional 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 (in case 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

setSimpleDateFormat

public void setSimpleDateFormat(java.text.SimpleDateFormat sdf)

Sets the SimpleDateFormat for this class. When the debug is on, the time stamp will be printed along with the packet dumps. The format of this timestamp can be changed using this method.

See Also:

getSimpleDateFormat()

getSimpleDateFormat

public java.text.SimpleDateFormat getSimpleDateFormat()

Gets the SimpleDateFormat for this class.

Returns:

the SimpleDateFormat used by this class. This method will return a non-null value, only when
1. The SimpleDateFormat is previously set using setSimpleDateFormat(SimpleDateFormat)OR
2. When the debug mode is on and atleast one packet has been printed.

See Also:

setSimpleDateFormat(SimpleDateFormat)

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

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. Invoke 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 addresses to listen on. The trap receiver will bind to the first successful address in the list and will ignore the rest.

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

Deprecated. use the method getPort() instead.

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 an SnmpException in case of a BindException. This will allow the api users to catch the exception and display a message.

Throws:

SnmpException - if the socket could not be opened, or if 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 public.

Returns:

The community of this SnmpTrapReceiver.

setCommunity

public void setCommunity(java.lang.String s)

Sets the SNMP Community. The default value is public.

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 traps are authenticated. If true, the received traps are authenticated. If false, the received traps are not authenticated.

Returns:

true or false.

setV3AuthEnable

public void setV3AuthEnable(boolean v3auth)

Specify whether the v3 trap should be authenticated or not. By default the authentication is enabled

Parameters:

v3auth - set this to False if v3 traps should be received without authentication. True otherwise.

Since:

AdventNet SNMP API 4 SP2 ( Release 4.0.2 )

setCommunityAuthEnable

public void setCommunityAuthEnable(boolean commauth)

Specify whether the community name should be authenticated or not for v1/v2 traps By default the authentication is enabled

Parameters:

commauth - set this to False if v1/v2 traps should be received without authentication. True otherwise.

Since:

AdventNet SNMP API 4 SP2 ( Release 4.0.2 )

isV3AuthEnabled

public boolean isV3AuthEnabled()

To check whether the v3 traps are authenticated and received If true, the received traps are authenticated. If false, the received traps are not authenticated.

Returns:

true or false.

Since:

AdventNet SNMP API 4 SP2 ( Release 4.0.2 )

isCommunityAuthEnabled

public boolean isCommunityAuthEnabled()

To check whether the v1/v2 traps are authenticated with their community name and received If true, the received traps are authenticated. If false, the received traps are not authenticated.

Returns:

true or false.

Since:

AdventNet SNMP API 4 SP2 ( Release 4.0.2 )

setTrapAuthEnable

public void setTrapAuthEnable(boolean isAuth)

Specify whether traps should be authenticated while receiving it. In v3 case when set to false, authentication for v3 traps will not be done and all the traps will be received.Authentication will be done otherwise and un-authenticated traps will be dropped. In v1 or v2 case if set to false the authentication for the community name will not be done and all the traps will be received. Authentication for community name will be done otherwise and un-authenticated traps will be dropped.The default value is True.

Parameters:

isAuth - set this to False if traps should be received without authentication. True 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.

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.

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.

setPrivProtocol

public void setPrivProtocol(int protocol)

Sets the privacy protocol. Support either CFB_AES_128 or CBC_DES. Supply integer should either of SnmpServer.CFB_AES_128 or SnmpServer.CBC_DES. If anything other than these will take SnmpServer.CBC_DES as default.

Parameters:

protocol - - should be SnmpServer.CFB_AES_128 or SnmpServer.CBC_DES or SnmpServer.CFB_AES_192 or SnmpServer.CFB_AES_256 or SnmpServer.CBC_3DES.

Since:

AdventNet SNMP API 4 SP4 ( Release 4.0.4 )

getPrivProtocol

public int getPrivProtocol()

Gets the privacy protocol.

Since:

AdventNet SNMP API 4 SP4 ( Release 4.0.4 )

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.

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.

The user entry created is used for receiving

• v3 Traps that are sent on behalf of this user, if the engineID argument is not null.
• v3 Inform requests that are sent on behalf of this user, if the engineID argument is null.

Parameters:

engineID - EngineID of the usm user entry to be created, for receiving v3 Traps. Should be null, for receiving v3 Inform requests on behalf of this user.

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.