Java Dynamic Management Kit 5.1 Tools Reference Guide

Chapter 1 SNMP MIB Compiler (`mibgen`)

The Java Dynamic Management Kit (Java DMK) provides a toolkit for developing SNMP agents and managers. This toolkit includes the SNMP MIB Compiler, mibgen, which is used for compiling SNMP MIBs into Java source code for agents and managers.

This chapter describes how to use the mibgen compiler, in the following sections:

1.1 Overview of the `mibgen` Compiler

The mibgen tool is a Java technology-based SNMP MIB compiler that takes an SNMP MIB as input and generates a set of Managed Beans (MBeans). These MBeans can be customized to implement the MIBs, enabling the Java DMK agent to be managed by an SNMP manager. You can use standard MBeans, model MBeans, dynamic MBeans and open MBeans in conjunction with the mibgen compiler.

The mibgen compiler is able to process the following:

Tables with cross–references that are indexed across several MIBs
Nested groups
Default value variables
Row status, namely tables controlled by a columnar object obeying the RowStatus convention, as defined in RFC 2579.

1.2 Starting the `mibgen` Compiler

To start the mibgen compiler, type the following command.

prompt% installDir/SUNWjdmk/5.1/bin/mibgen [options] mib1 ... mibN

Note –

The script for starting the mibgen tool uses the JAVA_HOME environment variable to determine the path to the Java 2 Platform, Standard Edition (J2SE). Therefore, even if you have the correct path to the J2SE platform in your PATH environment variable, this is overwritten by the JAVA_HOME variable.

1.3 `mibgen` Options

To invoke the java.com.sun.jdmk.tools.MibGen class, you need to invoke java.com.sun.jdmk.tools.MibGen options mib files.

mibgen options mib files

The options are listed below.

-n

Parses the MIB files without generating code.

-d dir

Generates code in the specified target directory.

-tp pkgName

Generates code within the specified Java package (target package).

-desc

Includes the DESCRIPTION clause of OBJECT-TYPE as comment in generated code.

-mo

(manager-only)

Generates code for the SNMP manager only, namely the metadata file for the MIB variables (SnmpOidTable file). By default, the mibgen compiler generates code for both SNMP agents and managers. By selecting the -mo option, you enable the mibgen compiler to generate code for only the manager and not for agents. The -mo option is incompatible with the -n option.

-mc

(MIB-CORE)

Does not use the default MIB-CORE definitions file provided with Java DMK. In this case, the user must specify the MIB-CORE definitions file as one of the MIB files. For example, java.com.sun.jdmk.tools.MibGen -mc mib my_mib_core.

-a

Generates code for all the MIB files. Without this option, the Java code is generated only for the first MIB file. In this case, the following MIB files are used to resolve some definitions of the first MIB file.

-p prefix

Uses the specified prefix for naming generated classes.

-g

Generates a generic version of the metadata that will access the MBeans through the MBean server instead of using a direct reference. This enables you to plug in dynamic MBeans, instead of the generated standard MBean skeletons.

-gp prefix

Uses the specified prefix to name the generic metadata classes. For example, the metadata class for group System will be named SystemprefixMeta. The default is no prefix.

-sp prefix

Uses the specified prefix to name the standard metadata classes. For example: the metadata class for group system will be named SystemprefixMeta. Default is no prefix.

-help

Prints a usage message explaining how to invoke the compiler, as follows:

<mib files>: By default mibgen generates code only for the modules specified in the first file. The other files are only used for closure analysis except when the -a is specified.

The order followed by the mibgen compiler to find the MIB_CORE definitions file is as follows:

The user MIB_CORE definitions file specified in the MIB files using the -mc mibgen option.
The command line parameter specified using the -Dmibcore.file Java property.
The default MIB_CORE definitions file provided with the Java DMK in installDir/etc/mibgen (mib_core.txt). To succeed, you must be able to derive the installation directory from the CLASSPATH environment variable. Otherwise, the mibgen compiler looks for the mib_core.txt file in currentDir/etc/mibgen.
When using generic metadata (-g option), backward compatibility is not ensured. Using the -g option has generic advantages, whereby MBeans are accessed through the MBean server, any kind of MBeans can be plugged in, but this option slightly reduces the overall performance.

Note –

SNMP MIB implementations generated using the mibgen compiler from Java DMK 5.0 can run and recompile on Java DMK 5.1 without modification.

1.3.1 Advanced `mibgen` Options

Advanced mibgen options are specified with a -X prefix, as shown in the following list.

mibgen -X:advanced options mib files

-X:advanced options includes the following options.

-X:define

Defines a valid mibgen property in the form name=value

-X:use-display-hint[:on|:off]

Uses DISPLAY-HINT.

When on, this option instructs mibgen to generate an attribute of type String for any object using a textual convention whose DISPLAY-HINT is 255a [com.sun.jdmk.tools.mibgen.options .use.display.hint=true]

-X:abstract-mib[:on|:off]

Generate abstract MIB.

When on, this option instructs mibgen to generate an abstract MIB. The MIB class is an abstract class when the MBean factory methods are abstract. [com.sun.jdmk.tools.mibgen.options .mib.factory.abstract=true]

-X:no-table-access[:on|:off]

No table accessor.

When on, this option instructs mibgen not to generate any table accessors in the group of MBean interfaces. [com.sun.jdmk.tools.mibgen.options .mbean.table.accessor=false].

-X:use-unsigned-long[:on|:off]

Handles unsigned long values.

-X:target:5.0

Generates MIBs compatible with the Java DMK 5.0 implementation of SNMP.

-X:help

Print this help message.

1.4 Output From the `mibgen` Compiler

The mibgen compiler also generates the Java source code that is required for representing a whole MIB in an SNMP manager. The mibgen compiler parses an SNMP MIB and generates the following.

For agents and managers:
- A class mapping symbolic names with object identifiers of MIB variables
For agents:
- An MBean that represents the whole MIB
- Classes that represents SNMP groups or entities as MBeans and their corresponding metadata classes
- Classes that represents SNMP tables
- Classes that represents SNMP enumerated types

MBeans generated by the mibgen compiler need to be updated to provide the definitive implementation. For more information, see the corresponding section in the Java Dynamic Management Kit 5.1 Tutorial.

1.4.1 Representation of the Whole MIB

The mibgen compiler generates a Java file that represents and initializes the whole MIB. This class extends the class SnmpMib. SnmpMib is an abstract Java class in the com.sun.management.snmp.agent package and is a logical abstraction of an SNMP MIB. The SNMP adaptor uses the SnmpMib class to implement agent behavior. The generated MIB file offers factory methods for group MBeans.

To Implement the Generated MIB File

Subclass the group MBean skeleton you want to implement, and complete the getter, checker, and setter methods.

Subclass the generated MIB file.

Redefine the factory methods for the group MBeans you have implemented, and ensure that they instantiate the actual implementation class and not the skeleton.

The mibgen compiler uses the module name specified in the MIB definition to name files representing whole MIBs. The compiler removes special characters and replaces them with an underscore character (_).

1.4.2 Representation of the Whole MIB in an SNMP `OidTable`

The mibgen compiler generates a Java file that contains the code required to represent a whole MIB in an SNMP manager OidTable. This class extends the com.sun.management.snmp.snmpOidTableSupport class, which implements the com.sun.management.snmp.snmpOidTable class and maintains a database of MIB variables. A name can be resolved against the database. This file can be used by both the agent and the manager API and contains metadata definitions for the compiled MIB. The metadata can then be loaded into the SnmpOid table.

The file is always generated when mibgen is invoked. The generated file is called MIBnameOidTable. The -mo option generates only the MIBnameOidTable file. This file is the only file generated for SNMP managers. All other files are dedicated to the SNMP agents.

1.5 Classes Representing SNMP Groups

For each SNMP group defined in the MIB, the mibgen compiler generates:

A skeletal MBean, with its interface
A metadata file

1.5.1 Skeletal MBeans Representing Groups

The mibgen compiler generates an MBean for each group that is defined in the MIB. These skeletal MBeans need to be completed by adding implementation-specific code, to provide access methods. The generated code is initialized with default values for the various MIB variables. If the MIB specifies a default value for an SNMP variable, this value is used to initialize the corresponding variable in the MBean skeleton. Therefore, if you compile the generated code directly, you obtain a running agent. In this case, values returned by the agent when querying the MIBs will be default values or meaningless values, if no default value has been provided in the MIB file for the variable.

The mibgen compiler uses the group names specified in the MIB definition to name MBeans that are generated from groups.

1.5.2 Metadata Files

In addition to generating skeletal MBeans to represent each group, the mibgen compiler generates a metadata file. The metadata file contains Java source code that provides the SNMP view of the MBean. Metadata files do not need to be modified. For metadata files, the Meta suffix is added.

1.6 Classes Representing SNMP Tables

For each SNMP table defined in the MIB, the mibgen compiler generates:

A class that contains the view of the table
A metadata file that corresponds to the SNMP table
A skeletal MBean that represents a table entry, with its interface
A metadata file that corresponds to the skeletal MBean

1.6.1 Class Containing the SNMP View of a Table (Metadata Class)

The metadata class containing the SNMP view of a table contains all the management of the table index. Usually you do not need to subclass or access the generated table Metadata classes, except when implementing virtual tables. See SNMP Virtual Table example in the Java Dynamic Management Kit 5.1 Tutorial for details.

The class name is derived from the name of the table, and is postfixed by Meta. For example, for a table named sysApplInstallPkgTable in the MIB, mibgen will generate a Metadata class called SysApplInstallPkgTableMeta.

1.6.2 Class Containing the MBean View of the Table

The class containing the MBean view of a table enables you to add or remove entries dynamically from the table. This class contains callbacks and factory methods that enable you to instantiate or delete entries upon receiving requests from a remote SNMP manager. See the Simple SNMP Tables example and SNMP Table Insrtrumentation example in the Java Dynamic Management Kit 5.1 Tutorial for details.

The class name is prefixed with Table, followed by the name of the table. For example, for a table named sysApplInstallPkgTable in the MIB, mibgen will generate an MBean view of the table class called TableSysApplInstallPkgTable.

1.6.3 Skeletal MBeans Representing SNMP Table Entries

For each table in a MIB, the mibgen compiler generates an MBean that represents a table entry. These skeletal MBeans must be completed by adding implementation specific code, called access methods. The generated code is initialized with default values for table–entry fields. Therefore, if you compile the generated code directly, you obtain a running agent. In this case, values returned by the agent when querying the MIBs are not meaningful. The mibgen compiler uses the entry names that are specified in the MIB definition to name MBeans that are generated from table entries. For example, for a table entry definition named sysApplInstallPkgEntry in the MIB, mibgen will generate a skeletal MBean class named SysApplInstallPkgEntry and an interface named SysApplInstallPkgEntryMBean.

Note –

Remote creation of table entries is disabled by default, for security reasons. You can dynamically enable and disable remote creation of table entries by calling the setCreationEnabled operation on the generated MBean-like object.

The RowStatus convention, that is defined in RFC 2579, is fully supported by the code generator. When a table is defined using SNMPv2, if it contains a control variable with row status syntax, the mibgen compiler generates a set of methods allowing this table to be remotely controlled by this variable. However, the remote creation and remote deletion of rows remains disabled by default.

Table objects are divided into two categories:

A metadata class
An MBean-like object

When remote table-entry creation is enabled, and the creation of a new table is requested, a factory method is called on the MBean-like object to instantiate the new table entry. By default, an instance of the skeleton class for that table entry is instantiated.

To Instantiate Your Own Implementation Class

Subclass the MBean-like object to redefine the factory method for remote entry creation.

Redefine this factory method so that it returns an instance of your implementation class, instead of the default skeleton.

Subclass this table's group MBean to instantiate your new MBean-like object, instead of the generated default object.

This is demonstrated in the RowStatus example, which is presented in the Java Dynamic Management Kit 5.1 Tutorial.

1.6.4 Metadata Files

In addition to generating skeletal MBeans to represent each table entry, the mibgen compiler generates a Java file containing the SNMP view of the MBean. Metadata files do not need to be modified. For metadata files, the Meta suffix is added.

1.6.5 Classes Representing SNMP Enumerated Types

The mibgen compiler generates a specific class for each enumerated type that is defined in the MIB. This class contains all the possible values defined in the enumerated type. The generated class extends the generic class Enumerated, defined in the com.sun.jdmk package. The HTML adaptor can use the Enumerated class to display all the labels that are contained in an enumeration. The mibgen compiler can handle enumerated types defined as part of a type definition or in-line definition.

Generated code representing SNMP enumerated types is prefixed with Enum followed by the type name or the variable name for inline definition.

Note –

The mibgen compiler has an option -p prefix that you can use to prefix the names of all generated files with a specific string.

For example, in MIB II, TCP connection states are represented by an enumeration containing all the possible states for a TCP connection. The mibgen compiler generates a Java class named EnumTcpConnState to represent the enumeration.

1.7 Information Mapping

For each group defined in your MIB, the mibgen compiler generates an MBean. Each variable in the group is represented as a property of the MBean. If the MIB allows read access to a variable, the mibgen compiler generates a getter method for the corresponding property. If the MIB allows write access to a variable, the mibgen compiler generates a setter method for the property. Tables are seen as indexed properties whose type corresponds to the table entry type. The SNMP view of the table is maintained by a specific table object contained in the generated MBean. The mibgen compiler maps the MIB variable syntax to a well-defined Java type.

The MBeans that the mibgen compiler generates do not have any dependencies on specific SNMP objects. Therefore, these MBeans can be easily browsed or integrated into the various Java DMK components. The translation between the SNMP syntax and the MBean syntax is performed by the metadata.

MBeans generated by the mibgen compiler must be updated to provide the definitive implementation. The generated code is an operational agent. Thus, the code can be compiled, run, and tested without any modification.

As a general rule, use subclassing to implement your custom behavior. Do not edit the generated file, or your modification will be lost when you regenerate your MIB. Instead of subclassing the generated skeleton classes, you can also provide your own implementation that simply implements the corresponding generated interface, as shown in the SNMP Virtual Tables example in the Java Dynamic Management Kit 5.1 Tutorial.

Example 1–1 shows how to implement a skeletal MBean.

Example 1–1 Implementing a Skeletal MBean

public class g1 implements g1MBean, Serializable { 	
	    protected Integer myVar = new Integer (1);
      public g1(SnmpMib myMib) {
      {
      public Integer getMyVar() throws SnmpStatusException {
          return myVar;
      }

       public void setMyVar(Integer x)  throws SnmpStatusException {
           myVar = x;
      }

}

You must subclass or provide an implementation of the skeletal MBean to implement your MIB behavior. For information about developing an SNMP agent, SNMP Manager, SNMP API, and SNMP Proxy, see the corresponding sections in the Java Dynamic Management Kit 5.1 Tutorial.

Chapter 1 SNMP MIB Compiler (mibgen)

1.1 Overview of the mibgen Compiler

1.2 Starting the mibgen Compiler

1.3 mibgen Options

1.3.1 Advanced mibgen Options

1.4 Output From the mibgen Compiler

1.4.1 Representation of the Whole MIB

To Implement the Generated MIB File

1.4.2 Representation of the Whole MIB in an SNMP OidTable

1.5 Classes Representing SNMP Groups

1.5.1 Skeletal MBeans Representing Groups

1.5.2 Metadata Files

1.6 Classes Representing SNMP Tables

1.6.1 Class Containing the SNMP View of a Table (Metadata Class)

1.6.2 Class Containing the MBean View of the Table

1.6.3 Skeletal MBeans Representing SNMP Table Entries

To Instantiate Your Own Implementation Class

1.6.4 Metadata Files

1.6.5 Classes Representing SNMP Enumerated Types

1.7 Information Mapping

Example 1–1 Implementing a Skeletal MBean

Chapter 1 SNMP MIB Compiler (`mibgen`)

1.1 Overview of the `mibgen` Compiler

1.2 Starting the `mibgen` Compiler

1.3 `mibgen` Options

1.3.1 Advanced `mibgen` Options

1.4 Output From the `mibgen` Compiler

1.4.2 Representation of the Whole MIB in an SNMP `OidTable`