ipworks
Class Snmpagent

java.lang.Object
  |
  +--ipworks.Snmpagent

public class Snmpagent

extends java.lang.Object

The SNMPAgent bean is used to implement SNMP Agent Applications.

The SNMPAgent bean implements a standard SNMP Agent as specified in the SNMP RFCs. The bean supports SNMP v1, v2c, and v3.

The bean provides both encoding/decoding and transport capabilities, making the task of developing a custom SNMP agent as simple as setting a few key properties and handling a few events. SNMP data such as 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.

The bean operates asynchronously. Requests are received through events such as GetRequest , GetBulkRequest , GetNextRequest , etc.. and the corresponding responses are automatically sent when the events return. Traps are sent through the SendTrap method.

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 SendSecureTrap method is used to send authenticated (secure) SNMPv3 traps.

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.

Other packet information is provided through corresponding event parameters, such as Community, or RequestId.

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
static int	snmpverV1
static int	snmpverV2c
static int	snmpverV3

Constructor Summary

Snmpagent()

Method Summary

void	addSnmpagentEventListener(SnmpagentEventListener l)
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 of the SNMP Agent.
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 listens.
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.
int	getSNMPVersion() Version of SNMP used for outgoing requests (traps).
int	getSysUpTime() Time passed since the agent was initialized (in hundredths of a second).
boolean	isAcceptData() Enables or disables data reception.
boolean	isActive() Enables or disables sending and receiving of SNMP packets.
void	removeSnmpagentEventListener(SnmpagentEventListener l)
void	reset() Clears the object arrays.
void	sendSecureTrap(java.lang.String remoteHost, java.lang.String trapOID, java.lang.String user, java.lang.String password) Sends an authenticated SNMPv3 trap.
void	sendTrap(java.lang.String remoteHost, java.lang.String trapOID) Sends an SNMP Trap.
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 of the SNMP Agent.
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 listens.
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	setSNMPVersion(int SNMPVersion) Version of SNMP used for outgoing requests (traps).
void	setSysUpTime(int sysUpTime) Time passed since the agent was initialized (in hundredths of a second).
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

snmpverV1

public static final int snmpverV1

See Also:

Constant Field Values

snmpverV2c

public static final int snmpverV2c

See Also:

Constant Field Values

snmpverV3

public static final int snmpverV3

See Also:

Constant Field Values

Constructor Detail

Snmpagent

public Snmpagent()

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 IPWorksException

Enables or disables data reception.

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

IPWorksException

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 IPWorksException

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.

IPWorksException

getLocalEngineId

public byte[] getLocalEngineId()

The Engine Id of the SNMP Agent.

This property is only used for SNMPv3 packets (when SNMPVersion is 3).

setLocalEngineId

public void setLocalEngineId(byte[] localEngineId)
                      throws IPWorksException

The Engine Id of the SNMP Agent.

This property is only used for SNMPv3 packets (when SNMPVersion is 3).

IPWorksException

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 IPWorksException

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.

IPWorksException

getLocalPort

public int getLocalPort()

The UDP port in the local host where the bean listens.

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 (default 161).

You may also set LocalPort to 0. This allows the TCP/IP stack to choose a port at random. The value chosen is provided via the LocalPort property after the bean is activated through the Active property.

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 IPWorksException

The UDP port in the local host where the bean listens.

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 (default 161).

You may also set LocalPort to 0. This allows the TCP/IP stack to choose a port at random. The value chosen is provided via the LocalPort property after the bean is activated through the Active property.

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.

IPWorksException

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 IPWorksException

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.

IPWorksException

getObjId

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

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" 

IPWorksException

setObjId

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

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" 

IPWorksException

getObjType

public int getObjType(int objIndex)
               throws IPWorksException

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.

IPWorksException

setObjType

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

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.

IPWorksException

getObjValue

public byte[] getObjValue(int objIndex)
                   throws IPWorksException

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" 

IPWorksException

setObjValue

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

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" 

IPWorksException

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 IPWorksException

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.

IPWorksException

getSNMPVersion

public int getSNMPVersion()

Version of SNMP used for outgoing requests (traps).

This property takes one of the following values:

snmpverV1 (1)

SNMP Version 1.

snmpverV2c (2)

SNMP Version 2c.

snmpverV3 (3)

SNMP Version 3.

setSNMPVersion

public void setSNMPVersion(int SNMPVersion)
                    throws IPWorksException

Version of SNMP used for outgoing requests (traps).

This property takes one of the following values:

snmpverV1 (1)

SNMP Version 1.

snmpverV2c (2)

SNMP Version 2c.

snmpverV3 (3)

SNMP Version 3.

IPWorksException

getSysUpTime

public int getSysUpTime()

Time passed since the agent was initialized (in hundredths of a second).

This property is used when sending SNMP traps, and it normally provides the time since the system was restarted in 1/100s of a second.

If another value is desired, you may set this property to a custom value. From that point on, SysUpTime will return the value set plus time elapsed.

setSysUpTime

public void setSysUpTime(int sysUpTime)
                  throws IPWorksException

Time passed since the agent was initialized (in hundredths of a second).

This property is used when sending SNMP traps, and it normally provides the time since the system was restarted in 1/100s of a second.

If another value is desired, you may set this property to a custom value. From that point on, SysUpTime will return the value set plus time elapsed.

IPWorksException

config

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

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.

IPWorksException

doEvents

public void doEvents()
              throws IPWorksException

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.

IPWorksException

reset

public void reset()
           throws IPWorksException

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.

IPWorksException

sendSecureTrap

public void sendSecureTrap(java.lang.String remoteHost,
                           java.lang.String trapOID,
                           java.lang.String user,
                           java.lang.String password)
                    throws IPWorksException

Sends an authenticated SNMPv3 trap.

Similar to the SendTrap method except that User and Password are used to authenticate the trap.

IPWorksException

sendTrap

public void sendTrap(java.lang.String remoteHost,
                     java.lang.String trapOID)
              throws IPWorksException

Sends an SNMP Trap.

Depending upon the value of the SNMPVersion property, the packet is constructed as an SNMPv1 or SNMPv2 Trap PDU. The following configuration settings provide more control about how traps are generated:TrapPort,TrapAgentAddress,TrapCommunity,TrapEnterprise. The SysUpTime property provides the trap timestamp.

SendTrap sends an unauthenticated trap. The SendSecureTrap method is used to send authenticated SNMPv3 traps.

If any values are provided in the ObjId , ObjType , ObjValue arrays, (i.e. ObjCount is greater than 0), they are sent unchanged. In the case of an SNMPv2 or SNMPv3 Trap, if ObjCount is 0, the following values are set: sysUpTime.0 equal to SysUpTime and snmpTrapOID.0 equal to TrapOID .

For SNMPv2 and SNMPv3 Traps, TrapOID must contain the full OID of the Trap. For SNMPv1, TrapOID must be a string of the form "generic.specific" where generic and specific are numeric values providing the Trap Generic Type and Specific Type.

For SNMPv1, TrapOID must be of the form "GenericTrap.SpecificTrap". These values are sent in the PDU header.TrapAgentAddressandTrapEnterpriseare taken from the corresponding configuration settings.

Additionally, the following symbolic values are recognized and translated as follows:

Trap NameOID (SNMPv2 and above)

SNMPv1 GenericType

coldStart \011\0111.3.6.1.6.3.1.1.5.1

0

warmStart \011\0111.3.6.1.6.3.1.1.5.2

1

linkDown \011\0111.3.6.1.6.3.1.1.5.3

2

linkUp \011\011\0111.3.6.1.6.3.1.1.5.4

3

authenticationFailure1.3.6.1.6.3.1.1.5.5

4

egpNeighborLoss1.3.6.1.6.3.1.1.5.6

5

enterpriseSpecific\0111.3.6.1.6.3.1.1.5.7\011

6

IPWorksException

value

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

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.

IPWorksException

addSnmpagentEventListener

public void addSnmpagentEventListener(SnmpagentEventListener l)
                               throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeSnmpagentEventListener

public void removeSnmpagentEventListener(SnmpagentEventListener l)