ipworksssnmp
Class Snmptrapmgr

java.lang.Object
  |
  +--ipworksssnmp.Snmptrapmgr

public class Snmptrapmgr

extends java.lang.Object

The SNMPTrapMgr bean provides a listening point for SNMP traps.

The SNMPTrapMgr bean provides a listening point for SNMP traps and informs as specified by the SNMP RFCs. The bean supports v1, v2c, and v3 traps.

The bean provides both encoding/decoding and transport capabilities, making the task of developing a custom SNMP Trap manager as simple as setting a few key properties and handling a few events. SNMP data, such as for instance SNMP object id-s (OID-s) are exchanged as text strings, thus further simplifying the task of handling them.

The bean is activated/deactivated by setting the Active property. This property enables or disables sending and receiving.

Messages are received through events such as Trap , InformRequest , or DiscoveryRequest .

SNMP OIDs, types, and values are provided in arrays such as ObjId , ObjType , and ObjValue , for both sent and received packets. ObjCount provides the number of elements in each of the arrays.

SNMPv3 USM security passwords are requested through the GetUserPassword event, and event parameters such as User and SecurityLevel provide information about the security attributes of received requests, and enable granular decision capability about what to provide and what not to provide.

The AddUser , RemoveUser , ShowCache , ClearCache , AddEngine , and RemoveEngine methods are used to manage an internal authentication cache. This internal cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

Field Summary

static int	otCounter32
static int	otCounter64
static int	otEndOfMibView
static int	otGauge32
static int	otInteger
static int	otIPAddress
static int	otNoSuchInstance
static int	otNoSuchObject
static int	otNSAP
static int	otNull
static int	otObjectId
static int	otOctetString
static int	otOpaque
static int	otTimeTicks
static int	otUnsignedInteger32

Constructor Summary

Snmptrapmgr()

Method Summary

void	addEngine(byte[] engineId, int engineBoots, int engineTime) Adds the engine specified by EngineId to the internal authentication cache.
void	addSnmptrapmgrEventListener(SnmptrapmgrEventListener l)
void	addUser(java.lang.String user, byte[] engineId, java.lang.String authenticationPassword, java.lang.String encryptionPassword) Adds a user for the engine specified by EngineId to the internal authentication cache.
void	clearCache() Clears the internal authentication database.
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	doEvents() Processes events from the internal message queue.
byte[]	getLocalEngineId() The Engine Id (for SNMPv3).
java.lang.String	getLocalHost() The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
int	getLocalPort() The UDP port in the local host where the bean is bound to.
int	getObjCount() Number of objects in the current request.
java.lang.String	getObjId(int objIndex) Array of OIDs encoded as strings.
int	getObjType(int objIndex) Array of object types.
byte[]	getObjValue(int objIndex) Array of object values.
int	getRequestId() The request-id to mark outgoing packets with.
void	hashPasswords() Hashes all passwords in the cache.
boolean	isAcceptData() Enables or disables data reception.
boolean	isActive() Enables or disables sending and receiving of SNMP packets.
void	removeEngine(byte[] engineId) Removes the engine specified by EngineId from the internal authentication cache.
void	removeSnmptrapmgrEventListener(SnmptrapmgrEventListener l)
void	removeUser(java.lang.String user, byte[] engineId) Removes the user specified by User of the engine specified by EngineId from the internal authentication cache.
void	reset() Clears the object arrays.
void	setAcceptData(boolean acceptData) Enables or disables data reception.
void	setActive(boolean active) Enables or disables sending and receiving of SNMP packets.
void	setLocalEngineId(byte[] localEngineId) The Engine Id (for SNMPv3).
void	setLocalHost(java.lang.String localHost) The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
void	setLocalPort(int localPort) The UDP port in the local host where the bean is bound to.
void	setObjCount(int objCount) Number of objects in the current request.
void	setObjId(int objIndex, java.lang.String objId) Array of OIDs encoded as strings.
void	setObjType(int objIndex, int objType) Array of object types.
void	setObjValue(int objIndex, byte[] objValue) Array of object values.
void	setRequestId(int requestId) The request-id to mark outgoing packets with.
void	showCache() Lists all entries in the internal user and engine database.
java.lang.String	value(java.lang.String OID) Returns the value corresponding to an OID.

Methods inherited from class java.lang.Object

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

Field Detail

otInteger

public static final int otInteger

See Also:

Constant Field Values

otOctetString

public static final int otOctetString

See Also:

Constant Field Values

otNull

public static final int otNull

See Also:

Constant Field Values

otObjectId

public static final int otObjectId

See Also:

Constant Field Values

otIPAddress

public static final int otIPAddress

See Also:

Constant Field Values

otCounter32

public static final int otCounter32

See Also:

Constant Field Values

otGauge32

public static final int otGauge32

See Also:

Constant Field Values

otTimeTicks

public static final int otTimeTicks

See Also:

Constant Field Values

otOpaque

public static final int otOpaque

See Also:

Constant Field Values

otNSAP

public static final int otNSAP

See Also:

Constant Field Values

otCounter64

public static final int otCounter64

See Also:

Constant Field Values

otUnsignedInteger32

public static final int otUnsignedInteger32

See Also:

Constant Field Values

otNoSuchObject

public static final int otNoSuchObject

See Also:

Constant Field Values

otNoSuchInstance

public static final int otNoSuchInstance

See Also:

Constant Field Values

otEndOfMibView

public static final int otEndOfMibView

See Also:

Constant Field Values

Constructor Detail

Snmptrapmgr

public Snmptrapmgr()

Method Detail

isAcceptData

public boolean isAcceptData()

Enables or disables data reception.

Setting the property to False temporarily disables data reception. Setting the property to True re-enables data reception.

setAcceptData

public void setAcceptData(boolean acceptData)
                   throws IPWorksSSNMPException

Enables or disables data reception.

Setting the property to False temporarily disables data reception. Setting the property to True re-enables data reception.

IPWorksSSNMPException

isActive

public boolean isActive()

Enables or disables sending and receiving of SNMP packets.

The Active property must be set to True before any SNMP requests or traps are sent or received.

setActive

public void setActive(boolean active)
               throws IPWorksSSNMPException

Enables or disables sending and receiving of SNMP packets.

The Active property must be set to True before any SNMP requests or traps are sent or received.

IPWorksSSNMPException

getLocalEngineId

public byte[] getLocalEngineId()

The Engine Id (for SNMPv3).

This property is necessary for properly handling InformRequest packets.

setLocalEngineId

public void setLocalEngineId(byte[] localEngineId)
                      throws IPWorksSSNMPException

The Engine Id (for SNMPv3).

This property is necessary for properly handling InformRequest packets.

IPWorksSSNMPException

getLocalHost

public java.lang.String getLocalHost()

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksSSNMPException

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

IPWorksSSNMPException

getLocalPort

public int getLocalPort()

The UDP port in the local host where the bean is bound to.

The LocalPort property must be set before the bean is activated ( Active is set to True). It instructs the bean to bind to a specific port (or communication endpoint) in the local machine.

The default port is 162 (standard trap port). If that port is busy, an error will be returned, unless theForceLocalPortconfiguration setting is set to False, in which case a random port will be chosen.

LocalPort cannot be changed once the bean is Active . Any attempt to set the LocalPort property when the bean is Active will generate an error.

setLocalPort

public void setLocalPort(int localPort)
                  throws IPWorksSSNMPException

The UDP port in the local host where the bean is bound to.

The LocalPort property must be set before the bean is activated ( Active is set to True). It instructs the bean to bind to a specific port (or communication endpoint) in the local machine.

The default port is 162 (standard trap port). If that port is busy, an error will be returned, unless theForceLocalPortconfiguration setting is set to False, in which case a random port will be chosen.

LocalPort cannot be changed once the bean is Active . Any attempt to set the LocalPort property when the bean is Active will generate an error.

IPWorksSSNMPException

getObjCount

public int getObjCount()

Number of objects in the current request.

The ObjCount property provides the number of elements in the various Obj arrays ( ObjId , ObjType , ObjValue ).

The arrays may be cleared at any time by setting the ObjCount to 0.

setObjCount

public void setObjCount(int objCount)
                 throws IPWorksSSNMPException

Number of objects in the current request.

The ObjCount property provides the number of elements in the various Obj arrays ( ObjId , ObjType , ObjValue ).

The arrays may be cleared at any time by setting the ObjCount to 0.

IPWorksSSNMPException

getObjId

public java.lang.String getObjId(int objIndex)
                          throws IPWorksSSNMPException

Array of OIDs encoded as strings.

The object id-s are encoded as strings of numbers separated by "."-s, for instance: "1.3.6.1.2.1.1.1.0" (OID for "system description").

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create outgoing SNMP packets.

The corresponding object type and value (if any) are specified by the ObjType and ObjValue property arrays.

Example

 SNMPControl.ObjCount = 2
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjID(2) = "1.3.6.1.2.1.1.2.0" 

IPWorksSSNMPException

setObjId

public void setObjId(int objIndex,
                     java.lang.String objId)
              throws IPWorksSSNMPException

Array of OIDs encoded as strings.

The object id-s are encoded as strings of numbers separated by "."-s, for instance: "1.3.6.1.2.1.1.1.0" (OID for "system description").

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create outgoing SNMP packets.

The corresponding object type and value (if any) are specified by the ObjType and ObjValue property arrays.

Example

 SNMPControl.ObjCount = 2
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjID(2) = "1.3.6.1.2.1.1.2.0" 

IPWorksSSNMPException

getObjType

public int getObjType(int objIndex)
               throws IPWorksSSNMPException

Array of object types.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called. The default type is NULL (5).

The corresponding object id and value are specified by the ObjId and ObjValue property arrays.

Possible object type values include:

otInteger (2)

2

otOctetString (4)

4

otNull (5)

5

otObjectID (6)

6

otIPAddress (64)

64

otCounter32 (65)

65

otGauge32 (66)

66

otTimeTicks (67)

67

otOpaque (68)

68

otNSAP (69)

69

otCounter64 (70)

70

otUnsignedInteger32 (71)

71

The bean also supports the following artificial object values used to designate error conditions:

otNoSuchObject (128)

No such object error.

otNoSuchInstance (129)

No such instance error.

otEndOfMibView (130)

End of MIB View error.

IPWorksSSNMPException

setObjType

public void setObjType(int objIndex,
                       int objType)
                throws IPWorksSSNMPException

Array of object types.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called. The default type is NULL (5).

The corresponding object id and value are specified by the ObjId and ObjValue property arrays.

Possible object type values include:

otInteger (2)

2

otOctetString (4)

4

otNull (5)

5

otObjectID (6)

6

otIPAddress (64)

64

otCounter32 (65)

65

otGauge32 (66)

66

otTimeTicks (67)

67

otOpaque (68)

68

otNSAP (69)

69

otCounter64 (70)

70

otUnsignedInteger32 (71)

71

The bean also supports the following artificial object values used to designate error conditions:

otNoSuchObject (128)

No such object error.

otNoSuchInstance (129)

No such instance error.

otEndOfMibView (130)

End of MIB View error.

IPWorksSSNMPException

getObjValue

public byte[] getObjValue(int objIndex)
                   throws IPWorksSSNMPException

Array of object values.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called.

The corresponding object id and type are specified by the ObjId and ObjType property arrays.

Example

 SNMPControl.ObjCount = 1
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjValue(1) = "New Value" 

IPWorksSSNMPException

setObjValue

public void setObjValue(int objIndex,
                        byte[] objValue)
                 throws IPWorksSSNMPException

Array of object values.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called.

The corresponding object id and type are specified by the ObjId and ObjType property arrays.

Example

 SNMPControl.ObjCount = 1
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjValue(1) = "New Value" 

IPWorksSSNMPException

getRequestId

public int getRequestId()

The request-id to mark outgoing packets with.

If a custom value is needed for RequestId , the property must be set before sending the request. The bean increments RequestId automatically after sending each packet.

setRequestId

public void setRequestId(int requestId)
                  throws IPWorksSSNMPException

The request-id to mark outgoing packets with.

If a custom value is needed for RequestId , the property must be set before sending the request. The bean increments RequestId automatically after sending each packet.

IPWorksSSNMPException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksSSNMPException

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksSSNMPException

addEngine

public void addEngine(byte[] engineId,
                      int engineBoots,
                      int engineTime)
               throws IPWorksSSNMPException

Adds the engine specified by EngineId to the internal authentication cache.

The internal authentication cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

The ShowCache method is used to show the contents of the internal authentication cache.

The ClearCache method can be used to completely clear the cache.

IPWorksSSNMPException

addUser

public void addUser(java.lang.String user,
                    byte[] engineId,
                    java.lang.String authenticationPassword,
                    java.lang.String encryptionPassword)
             throws IPWorksSSNMPException

Adds a user for the engine specified by EngineId to the internal authentication cache.

The internal authentication cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

The ShowCache method is used to show the contents of the internal authentication cache.

The ClearCache method can be used to completely clear the cache.

IPWorksSSNMPException

clearCache

public void clearCache()
                throws IPWorksSSNMPException

Clears the internal authentication database.

All user and engine records are removed from the internal authentication cache as a result of this call.

IPWorksSSNMPException

doEvents

public void doEvents()
              throws IPWorksSSNMPException

Processes events from the internal message queue.

When DoEvents is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

IPWorksSSNMPException

hashPasswords

public void hashPasswords()
                   throws IPWorksSSNMPException

Hashes all passwords in the cache.

Forces computation of all passwords hashes in the cache. Used together with the HashPassword event to enable implementations of external password hash storage.

IPWorksSSNMPException

removeEngine

public void removeEngine(byte[] engineId)
                  throws IPWorksSSNMPException

Removes the engine specified by EngineId from the internal authentication cache.

The internal authentication cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

The ShowCache method is used to show the contents of the internal authentication cache.

The ClearCache method can be used to completely clear the cache.

IPWorksSSNMPException

removeUser

public void removeUser(java.lang.String user,
                       byte[] engineId)
                throws IPWorksSSNMPException

Removes the user specified by User of the engine specified by EngineId from the internal authentication cache.

The internal authentication cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

The ShowCache method is used to show the contents of the internal authentication cache.

The ClearCache method can be used to completely clear the cache.

IPWorksSSNMPException

reset

public void reset()
           throws IPWorksSSNMPException

Clears the object arrays.

Clears the object arrays, and sets the trap and error properties to their default values. This is useful for reinitializing all the properties that are used to create outgoing packets before building a new packet.

IPWorksSSNMPException

showCache

public void showCache()
               throws IPWorksSSNMPException

Lists all entries in the internal user and engine database.

A CacheEntry event is fired for every record in the database.

IPWorksSSNMPException

value

public java.lang.String value(java.lang.String OID)
                       throws IPWorksSSNMPException

Returns the value corresponding to an OID.

If the OID does not exist in the ObjId array, a trappable error is generated.

Please refer to the ObjId and ObjValue properties for more information.

IPWorksSSNMPException

addSnmptrapmgrEventListener

public void addSnmptrapmgrEventListener(SnmptrapmgrEventListener l)
                                 throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeSnmptrapmgrEventListener

public void removeSnmptrapmgrEventListener(SnmptrapmgrEventListener l)