7.0 Instrumenting General Code

7.1 Overview

Instrumentation of the managed resources, an application, a service or an object representing a device, is the way that you can expose their desired output. As specified in the previous chapter, the Agent Toolkit supports code generation for JMX instrumentation for a given MIB, using the JMX Compiler.

The generated code will be based on the Model MBeans specified by JMX specification. Following the Model MBean, the specification provides the flexibility for Initialization with XML file, Persistence, and Caching for the attribute values.

This chapter explains the process of adding the actual functionality to the generated code, so that the agent responds with the desired information.

7.2 Generated Code Structure

On generating the code, the instrumentation file and relevant XML files for the RequiredModelMBean will be generated along with the main file under respective directories.

Instrumentation files are generated under jmxprojects/<projectname>/agent/src/com/myCompany/myPackage/directory.
XML files are created under jmxprojects/projectname/agent/bin/conf/xml/mbeans/ directory.

The typical set of files generated for a MIB group are explained below:

7.2.1 Main File

The default name of the Main File is AdventNetJMXAgent.java. You can configure the Main file name in the JMX Compiler by selecting Source Code Generation -> General option, from the Project -> Settings tree. Specify the Main file name in the Agent Name option.

Composition of the Main File

The main file has the MBean Server instantiated and the code for the initialization of all the adaptors lies here. Also, the generated instrumented objects are made as Model MBeans (using the RequiredModelMBean) and registered with the MBean Server. Thus, it does the following:

Instantiates the MBean Server.
Initializes the interested adaptors (which are chosen while code generation).

Necessary code for sending traps (if trap definition is present in the MIB) will be present here.
Any AdventNet SNMP Agent bean (e.g., SNMP Proxy, Dynamic Registration, etc.,) plug-in to SNMP Adaptor can be done here.
Makes all the generated JMX instrumentation codes into ModelMBean using the javax.management.RequiredModelMBean class, initialized with the relevant XML file and registered with the MBeanServer. For example, the following code is generated in the main file AdventNetJMXAgent.java, for registering the agentSystem MBean of the AGENT-SAMPLE-MIB,

agentSystemInstrumentExt=new AgentSystemInstrumentExt();
xmlLocation = this.getClass().getResourceAsStream ("/conf/xml/mbeans/AgentSystemInstrument.xml");
rmm = new RequiredModelMBean(com.adventnet.utils.jmx.Utilities.convertXmlToModelMBeanInfo(xmlLocation));
rmm.setManagedResource(agentSystemInstrumentExt, "objectReference");
notifTable.put(agentSystemInstrumentExt , rmm);
name = "AdventNetJMXAgent:type=AgentSystemInstrumentExt";
server.registerMBean(rmm, new ObjectName(name));
rmm.load();

Because Notification is defined for the scalar group "agentSystem", the code gets generated as AgentSystemInstrumentExt with the code notifTable.put(agentSystemInstrumentExt , rmm);

Note that the following code will be generated in the Main File, if any notification is defined for that MIB. While sending notifications, this method will be called from the xxxInstrumentExt file or xxxEntryExt file which will return a ModelMBeanNotificationBroadcaster and the sendNotification() method of this object will be called.

private static Hashtable notifTable = new Hashtable();
public static ModelMBeanNotificationBroadcaster getNotifHandler(Object
source)
{
return (ModelMBeanNotificationBroadcaster)notifTable.get(source);
}

If the user has written his own MBean (such as Dynamic MBean, Standard MBean), then it can be registered with the MBean Server in this main file. Look at the example in

<Agent Toolkit Home>/examples/jmx/dynamicMBean directory for Dynamic MBean and
<Agent Toolkit Home>/examples/jmx/standardMBean directory for Standard MBean.

The AgentSystemInstrument.java and AdiskTable.java are the objects to be wrapped by the RequiredModelMBean for the agentSystem group and the adiskTable in the MIB respectively. The RequiredModelMBean for these classes are initialized by their relevant XML files generated, namely AgentSystemInstrument.xml and AdiskTable.xml.

The stub files where the user has to fill in the code are AgentSystemInstrument and AdiskEntry java files. Note that the AgentSystemInstrument will be persisted using the Model MBean persistence support as specified in its XML file, while for AdiskTable,the persistence is through the FileToVector support. If FileToVector option is turned off while code generation, then the AdiskTable also gets persisted using the Model MBean persistence support.

7.2.2 Instrumentation Files

The JMX protocol-independent instrumentation file will be generated for each scalar and table MBean defined in the MIB.

Instrument Files

For each scalar MBean, one instrument file will be generated with the name xxxInstrument.java. This file will have the getter and setter methods for all the attributes in the MBean. For example, the instrument file generated for the scalar group agentSystem of the agent-sample-mib is AgentSystemInstrument.java. Following are the key features of Instrument files:

Instrument files are generated for all scalar MBeans.

Instrument files have the getters and setters for each attribute in the scalar MBean.

Instrumentation for the attributes present in the scalar Mbean can be done in this file only.

Entry Files

For each table MBean, one instrument file will be generated with the name xxxEntry.java. This file will have the getter and setter methods for all the columns in the table. In addition to this file, one more file will be generated for each table MBean with the name xxxTable.java. This file is registered as a modelMbean in the MBean server. This file is used to identify an entry in the table and call the corresponding getter and setter methods in the xxxEntry.java file.

For example, the instrument file generated for the table group adiskTable of the agent-sample-mib is AdiskEntry.java . The AdiskTable.java is registered as a model MBean in the MBean server. Following are the key features of Entry files:

Entry files generated for all table MBeans.

Entry files have the getters and setters for each table attribute

Instrumentation for tables can be done in these Entry files.

7.2.3 XML File

For each scalar / table MBean , the relevant XML file is generated with the name xxxInstrumentr.xml for scalars and xxxTable.xml for tables. This file contains the attribute/operation information for making xxxInstrument.java or xxxTable.java as model Mbean.

It also has the protocol-dependent details (for example, OID SYNTAX type details for SNMP) for each attribute of the MBean. These information get converted to relevant descriptor objects when its RequiredModelMBean instance is initialized with the XML file.

For example, the XML file generated for the scalar group agentSystem of the agent-sample-mib is AgentSystemInstrument.xml . The XML file generated for the table group adiskTable is AdiskTable.xml

7.2.4 Other Files

Notification File

This file gets generated when Notification is defined for that particular group. This file extends the xxxInstrument.java file for a scalar MBean and xxxEntry.java file for a table MBean and has all Notification details present in it.

For example, Notifications are defined in agentSystem group and adiskTable of the agent-sample-mib. Hence, the Notification file generated for the scalar group agentSystem is AgentSystemInstrumentExt.java and for adiskTable is AdiskEntryExt.java

Persistence Files

The XMLtoVector file/FiletoVector file is generated if persistence for tables in 'File to Vector' format or 'XML to Vector' format is provided. Depending on the storage option, this file is generated. This file has methods such as readFromfile() and writeIntoFile() for reading and writing into file.

For example, if storage option for the adiskTable Mbean is provided in XML format, the AdiskTableXMLToVector.java file is generated.

TL1 Command Set and Data Set Files

To support common instrumentation for TL1 Adaptors (to be chosen in the UI of the JMX Compiler), two files get generated additionally. This is used to query the agent. The tcs folder gets generated when the TL1 Adaptor option is selected in the JMX Compiler. The two files that are generated additionally (.dat and .tcs) get stored under the jmxprojects/<projectname>/agent/src/com/myCompany/myPackage/folder.

run.bat/sh File

This file is used to run the Multi-Protocol agent. This file is generated in the <Agent Toolkit Home>/jmxprojects/projectname/agent/bin directory.

7.3 Instrumenting the Generated Code

Instrumentation (editing the generated code) for a desired function is done based on the application and requirement of the user.

7.3.1 Editing Files Generated for Scalars

In section 5.4.2.2. Instrument files, we saw what are the stub files generated for a scalar group for the given MIB using JMX Compiler tool. In this section, we will see how to instrument or fill in the stub file of the agentSystem group present in the agent-sample-mib.

AgentSystemInstrument.java

This class contains the protocol - independent stubs for the various objects defined in the agentSystem group of agent-sample-mib.txt MIB file. Users can fill in their stubs here. The instrumentation code has to be filled between these tags in order to support code merging when regenerated.

/* User code starts here */
/* User code ends 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 code is regenerated, the JMX 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.

For example, the getter method generated for the attribute agentDescr of the agentSystem Mbean is given below.

/**
* Handles the JMX Get Request for agentDescr
*/
public String getAgentDescr()
throws AgentException {
// Fill up the stub with required processing

return agentDescr;
}

This getter method will be called from the adaptors when any GET/GETNEXT request is meant for the attribute agentDescr. By default, it returns the default value "agentDescr not initialized". You have to add the required code within the user tags, so that the attribute agentDescr returns the desired output.

7.3.2 Editing Files Generated for Tables

The files generated for adiskTable of the agent-sample-mib are as follows :

AdiskTable.java
AdiskTable.xml
AdiskEntry.java

AdiskTable.java

This class contains getter and setter methods for just one attribute which is of type javax.jmx.openmbean. TabularData of name "AdiskTable". The utility methods in com.adventnet.utils.jmx.Utilities class take care of conversion of entries (AdiskEntry) to TabularData. AdiskTable class also has provision for setting the Vector/Hashtable of AdiskEntrys (the key for the Hashtable is Object[ ] of index objects.)

AdiskTable.xml

This XML file has only one attribute descriptor for "AdiskTable". The table's column information is furnished as various attribute descriptors inside the AdiskTable attribute description. This kind of specifying column information is of proprietary manner.

AdiskEntry

Instance of this class specifies a row of this table. It has the column's getter and setter methods. Users can fill in their stubs here.

/**
*Handles the JMX Get Request for adiskID
*/
public Integer getAdiskID()
throws AgentException {
// fill up with necessary processing

return adiskID;
}

7.3.3 Code Merging

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

/* User code starts here */

Add your code here

/* User code ends here */

// AdventNet code ends here

// Your code can be added here

// AdventNet 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 JMX 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 JMX Compiler UI

              This feature is enabled/disabled in the JMX Compiler UI as follows:

              1)Click Project->Settings->Source Code Generation->General
              2)Enable/Disable Merge with previous stub files in the General panel of Source Code Generation