Package com.snmp4j.smi

package com.snmp4j.smi

Provides classes and interfaces for parsing, compiling, loading, and using Management Information Base (MIB) specifications written in Structure of Management Information (SMI) version 1 and 2 with SNMP4J to format and parse SNMP data.

The SmiManager class implements the SNMP4J interfaces OIDTextFormat and VariableTextFormat and thus provides MIB information for SNMP4J with a tight integration.

To setup a SmiManager, either a MIB repository directory for exclusive use by SNMP4J-SMI or an implementation of the RepositoryDriver interface is needed.

The following UML package diagram illustrates the dependencies between the classes of the core SNMP4J-SMI API. Users of the API normally only need to use the com.snmp4j.smi and the com.snmp4j.smi.util packages directly.

SmiManager Creation

Integration with SNMP4J

The integration of the MIB parser (SMI compiler) with SNMP4J is astonishingly simple. You basically need only three lines of code to be executed in your application before initializing SNMP4J:

     /* Replace 'null' with your license key after evaluation: */
    SmiManager smiManager = new SmiManager(null, new File("/myMibRepositoryDir"));
    // Alternatively, if you cannot create a persistent directory on the target system:
    //SmiManager smiManager = new SmiManager(null, new MemRepositoryDriver());

    // Register the SmiManager as OID and VariableBinding formatter with SNMP4J:
    SNMP4JSettings.setOIDTextFormat(smiManager);
    SNMP4JSettings.setVariableTextFormat(smiManager);

Initially a SmiManager does not know of any MIB modules other than SNMPv2-CONF, SNMPv2-SMI, and SNMPv2-TC for SMIv2 and RFC-1212, RFC-1215, and RFC1155-SMI for SMIv1. Once SmiManager knows a MIB module, it can:

1. format OIDs with object names instead of numerical notation: "sysDescr.0" instead "1.3.6.1.2.1.1.1.0".
2. parse OIDs from object names
3. format variable bindings according to their SMI syntax and display hint: "ifAdminStatus.4 = up(1)" instead "1.3.6.1.2.1.2.2.1.7.4 = 1"
4. parse variable bindings from a text representation according to their SMI syntax and display hint.

To make a MIB module available to the SmiManager and thus to SNMP4J, two steps are necessary:

1. Compile the MIB into the MIB repository of the SmiManager.
2. Load the MIB module into the internal MIB cache.

Parsing and compiling a MIB specification text file into an internal format of the MIB repository is more effort (CPU) and time consuming than just loading the internal format into memory. The major difference is also, that during compilation all dependent MIB modules need to be parsed too (if not yet available in the cache).

To compile one or more MIB specification files into the internal MIB repository call one of the compile methods. First the simplest variant is shown and second the most complex but also the most flexible:

    // Easy MIB compilation:
    try {
        // Compile the MIB modules in a MIB file:
        String[] moduleNames = smiManager.compile(new File("C:\mymibfile.txt"));
        // Load compiled MIB modules into memory:
        for (String moduleName : moduleNames) {
            smiManager.loadModule(moduleName);
        }
    } catch (SmiParseException pex) {
        pex.printStacktrace();
    }

    // More complex but flexible:
    // 1. Create the input streams. Here two variants are shown and used in a single example:
    InputStream inputStreamSMIv2 = MyMibLoader.class.getResourceAsStream("SMIv2.zip");
    InputStream inputStreamAGENTPP = new FileInputStream("AGENTPP-CONFIG-MIB.txt");
    // 2. Implement a CompilationMonitor to monitor the progress. Here a very simple example that logs out the progress
    // messages:
    CompilationMonitor compilationMonitor = new CompilationMonitor() {
      public boolean loadingProgress(String fileName, int current, int maxCount) {
        System.out.println("Loading "+fileName+" "+current+"/"+maxCount);
        return true;
      }
      public boolean sortingProgress(String fileName, int current, int maxCount) {
        System.out.println("Sorting "+fileName+" "+current+"/"+maxCount);
        return true;
      }
      public boolean compilationProgress(String moduleName, int current, int maxCount) {
        System.out.println("Compiling "+moduleName+" "+current+"/"+maxCount);
        return true;
      }
    };
    // 3. Create the NamedInputStreams:
    List<CompilationResult> result =
        smiManager.compile(new NamedInputStream[] {
            new NamedInputStream(inputStreamSMIv2, "SMIv2", NamedInputStream.ZipFormat.ZIP),
            new NamedInputStream(inputStreamAGENTPP, "AGENTPP", NamedInputStream.ZipFormat.none),
        }, compilationMonitor, true, true, false);
    inputStreamSMIv2.close();
    inputStreamAGENTPP.close();
    // 4. Evaluate the compilation results:
    System.out.println(result.toString());

If you have already compiled MIB modules in your repository and you want to make them available to SNMP4J, simply load them by their MIB module name with SmiManager.loadModule(java.lang.String):

    smiManager.loadModule("SNMPv2-MIB");
    // Note: The SMIv1 RFC1213-MIB has been deprecated and replaced by several new SMIv2 MIBs, but you can still load
    // it if necessary. However, SNMP4J-SMI will use the SMIv2 object definitions instead SMIv1, if both are loaded:
    smiManager.loadModule("RFC1213-MIB");

A loaded MIB module can be unloaded to free memory by using the SmiManager.unloadModule(java.lang.String) method:

    smiManager.unloadModule("SNMPv2-MIB");

To remove a MIB module from the MIB repository, use the method SmiManager.deleteModule(java.lang.String, boolean). With the boolean option set to true, the deletion of a MIB module can be forced even if there are other MIB modules that depend on that module. Forcing the deletion can make sense if a repository is cleared for example. The MIB modules that depend on a deleted MIB module might get useless or might cause runtime errors if used.

In any case, the MIB module will not be unloaded from the cache.

    List<String> dependentModules = smiManager.deleteModule("SNMPv2-MIB", false);
    if (!dependentModules.isEmpty()) {
        System.out.println("Deletion failed because the following dependent modules exist: "+dependentModules);
    }

Interface Summary

Interface	Description
CompilationMonitor	The CompilationMonitor interface is implemented by classes that are supposed to monitor the progress of a multi MIB file compilation operation of the SmiManager.
RepositoryDriver	The RepositoryDriver adapts between the SmiManager and the (persistent) storage that holds the compiled MIB modules.
SmiAgentCapabilities	The SmiAgentCapabilities interface represents a SMIv2 AGENT-CAPABILITIES statement.
SmiCompiler	The SmiCompiler provides a simple yet complete interface to check, compile, store, and load MIB files content (i.e., MIB modules).
SmiCompliance	The SmiGroupCompliance interface represents the GROUP or OBJECT clause of a MODULE-COMPLIANCE statement in SMIv2.
SmiComplianceModule	The SmiComplianceModule interface defines the attributes for the "Module" element of the SMIv2 MODULE-COMPLIANCE macro.
SmiErrorInfo	The SmiErrorInfo interface represents a syntax or semantic error in a SMI specification file.
SmiGroup	The SmiGroup represents a SMI OBJECT-GROUP or NOTIFICATION-GROUP object.
SmiImport	The SmiImport represents an element within the IMPORTS construct of a SMIv1 or SMv2 MIB module.
SmiIndexInfo	The SmiIndexInfo interface represents the meta information of a SMI INDEX clause element which are relevant for converting an OID index value to an INDEX object and vice versa.
SmiModule	The SmiModule represents a SMIv1 or SMIv2 MIB MODULE-DEFINITION.
SmiModuleCompliance	The SmiModuleCompliance interface defines the attributes of the SMIv2 MODULE-COMPLIANCE macro.
SmiModuleIdentity	The SmiModule represents a SMIv2 MODULE-IDENTITY.
SmiNotificationType	The SmiNotificationType interface extends the SmiObject by attributes specific to the SMI NOTIFICATION-TYPE and TRAP-TYPE constructs, for example the OBJECTS clause.
SmiObject	The SmiObject interface represents the SMI information of a MIB object.
SmiObjectCompliance	The SmiObjectVariation interface defines the attributes that are included in MODULE-COMPLIANCE module parts (SmiComplianceModule) OBJECT clause and is also used in the AGENT-CAPABILITIES module section.
SmiObjectFilter<S extends SmiObject>	The SmiObjectFilter can be used to filter SmiObjects according to self defined criteria.
SmiObjectType	The SmiObjectType interface extends the SmiObject by attributes specific to the SMI OBJECT-TYPE construct, i.e.
SmiObjectTypeIndex	The SmiObjectTypeIndex represents an OBJECT-TYPE definition that is used as an INDEX element for a table.
SmiObjectVariation	The SmiObjectVariation interface defines the attributes for the object variation part of an AGENT-CAPABILITIES statement.
SmiRevision	The SmiRevision represents the REVISION clause of a SMIv2 MODULE-IDENTITY construct.
SmiSupportedModule	The SmiSupportedModule interface represents a SMIv2 MODULE clause of the AGENT-CAPABILITIES statement.
SmiSyntax	The SmiSyntax represents the SYNTAX clause of OBJECT-TYPE or TEXTUAL-CONVENTION SMI constructs.
SmiSyntaxElement	The SmiSyntaxElement represents a enumerated value or a range restriction.
SmiTextualConvention	The SmiTextualConvention represents the SMIv2 TEXTUAL-CONVENTION and the SMIv1 type assignment construct.
SmiValueType	Ths SmiValueType interface abstracts the common element of the OBJECT-TYPE and the TEXTUAL-CONVENTION SMI constructs.

Class Summary

Class	Description
CompilationResult	The CompilationResult class holds the MIB module names successfully parsed for each MIB file or the parsing errors that were detected during compilation.
NamedInputStream	The NamedInputStream class represents an input stream with a name to identify the stream.
RepositoryIO	The RepositoryIO class is used to return the InputStream or OutputStream instances provided by a RepositoryDriver instance to read or store a compiled MIB module from/into persistent storage.
SmiError	The SmiError class represents a syntax or semantic error in a SMI specification file.
SmiManager	The SmiManager Pro class manages the Structure of Management Information (SMI) specifications.
SmiSyntaxImpl	The SmiSyntaxImpl class represents the attributes of a SMI SYNTAX clause.

Enum Class Summary

Enum Class	Description
NamedInputStream.ZipFormat	A supported ZIP file format
SmiAccess	The SmiMaxAccess enumerates the ACCESS values of SMIv2 for MODULE-COMPLIANCE and AGENT-CAPABILITIES statements, including the deprecated SmiAccess.writeOnly for backward-compatibility.
SmiCompiler.OverwriteMode	The OverwriteMode defines whether existing MIB modules should be overwritten or not.
SmiCompiler.Strictness	The Strictness defines the number of syntax checks done on the sources.
SmiCompiler.TargetMode	The TargetMode defines the target for the compiled MIB modules.
SmiComplianceType	The SmiComplianceType distinguishes between GROUP and OBJECT compliance definitions in MODULE-COMPLIANCE statements.
SmiGroupType	The enumeration SmiGroupType distinguishes the type of a SMI group.
SmiManager.NonPrintableStringFormat	Defines the format for non-printable strings in formatted object identifiers (OIDs).
SmiManager.OctetStringDefaultFormat	The default formats to be applied for displaying OctetStrings.
SmiManager.OIDFormat	The OIDFormat defines the formatting of OID values.
SmiStatus	The SmiStatus enumerates the values of the SMIv1 and v2 STATUS clause.
SmiSyntaxElement.Type	The type of enumerated value.
SmiSyntaxType	The SmiSyntaxType identifies one of four SYNTAX clause types of OBJECT-TYPE or TEXTUAL-CONVENTION SMI constructs.
SmiType	The SmiType defines the SMI construct (for example OBJECT-TYPE) that defined the SMI object.

Exception Summary

Exception	Description
SmiParseException	The SmiParseException provides information about violations of the Structure of Management Information (SMI) v1 or v2 standards.