|
|
8.1 Overview
8.2 Generated Code Structure
8.3 Instrumenting the Generated Code
To get the device or application specific data, a few files in the generated source files need to be instrumented to include the desired function. This will depend on how the MIB is defined, how the data associated with the MIB can be accessed, how it needs to be delivered to the Manager etc. This section clearly explains the files generated for a MIB and the steps involved in instrumenting the same for retrieving application specific details.
On generating code for a MIB, the following files get generated by default in <Agent Toolkit Home>/snmpprojects/projectname/agent/src/com/myCompany/myPackage directory.
Main file
Instrument Files
Entry Files
Persistence Files and
Other Files (Trap File and Base Table Files)
Let us see in detail how these files are organized.
The Agent Main file is normally generated as WebNMSSnmpAgent.java. This Main File name can be modified as per your requirement by specifying it in the text field provided for Agent Name in Project -> Settings menu bar -> Source Generation Panel -> General of MIB Compiler UI.
The Main methods are generated in the Main file and it is very important to know the code organization of this file as this would help you implement methods at a later stage for attaining specific functionality.
Composition of Main File
Any main file will be organized as given below.
It extends com.adventnet.snmp.snmp2.agent.SnmpAgent
Since <MainFile Name> object extends SnmpAgent, SnmpAgent will get instantiated when <MainFile Name> object is instantiated.
On instantiating the SnmpAgent, the Agent will be started at the specified port and will wait for SNMP requests.
All requests sent to the Agent will reach the SnmpAgent and later given to PduRequestHandlers, if the request is valid.
Instantiates com.adventnet.snmp.snmp2.agent.PduRequestHandler
Instantiates all the generated xxxRequestHandler's (for every scalar and table group) and registers them with the PduRequestHandler with the group/tableEntry OIDs.
The registration tree in the PduRequestHandler will be registered with OID's corresponding to the group or tableEntry.
PduRequestHandler takes care of finding out the proper listener based on the OID after getting the request from the SnmpAgent
Instantiates all the Registration Listeners.
Provides Agent Param Options for starting the Agent in commandline.
Provides methods for Acl and Trap Forwarding Table Instantiation.
Provides methods for implementing V2 Compliance.
Provides some Variable Declarations.
Provides code for stopping the Agent.
8.2.2 Request Handler File for a Scalar/Tabular Group
Request Handler Files get generated for every
group of the MIB and these handler files takes care of forwarding the
requests from the Manager to the respective OID. Thus, the basic functionality
of this file is to register each module with the Agent and handle all
requests from the Managers such as
GET, GET-NEXT, and SET. The Request Handler files also handles row creation
in case of a table. The methods get generated by default and you need
not edit this file.
XXXRequestHandler.java file for a Scalar Group
Extends SimpleRequestHandler class.
The processGetRequest, processSetRequest, processGetNextRequest methods are generated in this class overriding the SimpleRequestHandler's methods.
These methods will take care of processing various requests received by the Agent.
XXXRequestHandler.java file for a Tabular Group
Similar to Scalars, this file extends BaseTableRequestHandler class.
The processGetRequest, processSetRequest, processGetNextRequest methods are generated in this class overriding the BaseTableRequestHandler's methods.
These methods will take care of processing the various requests received by the Agent.
These Request Handler Files also have methods for adding row entries to a Table at agent start-up. Please refer to SNMP Table Handling to know more on the createAndAddEntry method and other methods.
8.2.3 Instrument File for a Scalar
These are the files that get created for every scalar group and implements InstrumentHandlerInterface. The file can be edited to retrieve specific or expected values, i.e. you can modify this file depending upon your requirements. Each instrument file contains a getter and setter for every scalar variable, and also a getAttributes and setAttributes method.
The getAttributes and setAttributes method will be called from their respective handlers when there is a GET, GET-NEXT, or SET requests to the scalar variables. The advantage of using these methods are
It reduces the user implementation in every getter and setter methods generated for every scalar variable.
It is not required to collect data from the external application every time the getter and setter request is processed. The getAttributes and the setAttributes method contact the external application once, to retrieve the data for all the scalar variables.
The methods are used for grouping the attributes of a scalar group while performing multi-varbind requests.
These files get generated for tables and are similar to Instrument files generated for scalar variables, but extends BaseTableEntry class. They contain getters and setters for each variable in the table and also getAttributes and setAttributes method. These entry files are stub files to perform user implementation and pertains to the same advantages mentioned in the Instrument file.
xxxFileToVector.java file is generated when the storage option chosen during generation is Text file. This file implements com.adventnet.snmp.snmp2.agent.UpdateListener and has methods such as readFromfile() and writeIntoFile() for reading and writing into the text file. It is generated to make it simple for the users and to make the data available to the Agent in a flat file. You can also disable the option for generating "xxxFileToVector" by choosing RAM storage option in the MIB Compiler UI. This does not store the values anywhere except in runtime memory.
Alternatively, the xxxXMLToVector.java file is generated when the XML storage option is chosen before generation.
<MainFileName>Trap.java: This file has required methods for sending traps/notifications for the objects, which are grouped under Notification-Type/Trap-Type macros in the MIB module.
8.3 Instrumenting the Generated Code
Editing a file for a desired function (Instrumentation) needs to be done based on the application and the requirement of the user. This section has been explained assuming that the code generated for RFC1213 MIB is instrumented for retrieving specific values from the "sysDescr" scalar node ofsystemGroup and "ifDescr" column of ifTablegroup. Assume that the Agent is a v2c Agent.
Editing Files Generated for Scalars
The getter method of the scalar variable sysDescr in the System group of RFC 1213 MIB would be generated as follows in the SystemInstrument.java
|
/** * Handles the SNMP Get Request for sysDescr public String getSysDescr() // Fill up the stub with required processing return sysDescr; } |
On sending a GET request, the value of the sysDescr scalar variable is retrieved.
You can fill in your own stubs here. The instrumentation code has to be filled between these tags in order to support code merging when regenerated.
|
/* User code starts here */ |
These are the custom tags which can be used anywhere in the generated code. You just have to include your code in the file within these tags. When code is regenerated, the MIB Compiler looks for these tags and preserves the changes in the newly generated code. If either of the tags is not given, code merging will not be proper. Please refer to the topic "Code Merging" for more information.
Similarly, the setter method of the scalar variable sysDescr would be generated as follows.
|
/** // Fill up the stub with required
processing |
On sending a SET request to this scalar object with a new value, the new value is set to the OID. You can also edit these files to fill up your required processing.
Editing Files Generated for Tables
The getter methods of the table variable "ifDescr" in the ifTable group would be generated as follows in the ifEntry.java
|
/** // fill up with necessary processing return ifDescr; |
On doing a GET request for this column with the instance value would retrieve the value of that columnar variable.
Similarly, the setter methods of the table variable "ifDescr" would be generated as follows. On sending a SET request to this variable the value will be SET.
|
/** |
Edit these files to include the required values.
Code merging, is an option provided for users who prefer to shift between
releases. It is mainly used for migration purposes. Say, if a developer
using 5.0 version of Agent Toolkit decides to migrate to the 5.1 version,
then he can make use of this Merging option wherein the manually added
code (using the tags) is merged with the code, present in the file generated
by the new version of the toolkit, to attain the functions available in
the old version.If this option is not enabled before regenerating a file,
all the code added by the user would be lost.
The user code is normally added to the generated files using the
following tags.
// User code starts here
//Add your code here....
// User code ends here
OR
/* User code starts here */
Add your code here
/* User code ends here */
OR
// WebNMS code ends here
// Your code can be added here
// WebNMS code starts here
These are the custom tags which can be used anywhere in the generated code. The user has to just include his code in the file with these tags. When regenerated, the Mib Compiler looks for these tags and preserves the changes in the newly generated code. If either of the tags are not given merging will not be proper. Please note that the last tags are also supported and when these get generated in certain files, the user has to just include the codes between these tags which is generated, by default. Thus code merging is supported on all generated java files.
Enabling Code Merging Option in the Mib Compiler UI
This feature is enabled by default in the tool. It can be enabled/disabled in the Mib Compiler UI as follows:
|
|