# 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> snmpVersionAndMP =
            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(snmpVersionAndMP.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(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(String)` method:

        smiManager.unloadModule("SNMPv2-MIB");

To remove a MIB module from the MIB repository, use the method `SmiManager.deleteModule(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);
        }

- Related Packages
  Package
  Description
  com.snmp4j.smi.ber
  com.snmp4j.smi.polymorphic
  com.snmp4j.smi.util
  The `com.snmp4j.smi.util` package contains utility classes to be used in conjunction with the `SmiManager` class of the `com.snmp4j.smi` package.
  com.snmp4j.smi.version
- Class
  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`.
  CompilationResult
  The `CompilationResult` class holds the MIB module names successfully parsed for each MIB file or the parsing errors that were detected during compilation.
  DefaultPolymorphicVariableFormats
  The `DefaultPolymorphicVariableFormats` class provides default polymorphic variable formats for common SNMP MIBs.
  NamedInputStream
  The NamedInputStream class represents an input stream with a name to identify the stream.
  NamedInputStream.ZipFormat
  A supported ZIP file format
  RepositoryDriver
  The RepositoryDriver adapts between the `SmiManager` and the (persistent) storage that holds the compiled MIB modules.
  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.
  SmiAccess
  The SmiMaxAccess enumerates the ACCESS values of SMIv2 for MODULE-COMPLIANCE and AGENT-CAPABILITIES statements, including the deprecated `SmiAccess.writeOnly` for backward-compatibility.
  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).
  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.
  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.
  SmiComplianceType
  The `SmiComplianceType` distinguishes between GROUP and OBJECT compliance definitions in MODULE-COMPLIANCE statements.
  SmiError
  The `SmiError` class represents a syntax or semantic error in a SMI specification file.
  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.
  SmiGroupType
  The enumeration SmiGroupType distinguishes the type of a SMI group.
  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.
  SmiManager
  The `SmiManager` Pro class manages the Structure of Management Information (SMI) specifications.
  SmiManager.NonPrintableStringFormat
  Defines the format for non-printable strings in formatted object identifiers (OIDs).
  SmiManager.OctetStringDefaultFormat
  The default formats to be applied for displaying `OctetString`s.
  SmiManager.OIDFormat
  The OIDFormat defines the formatting of `OID` values.
  SmiManager.SmiModuleImportImpl
  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.
  SmiModuleImport
  The SmiModuleImport interface defines the structure of an SMI IMPORT statement on the level of MIB module dependencies.
  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 `SmiObject`s according to self defined criteria.
  SmiObjectType
  The SmiObjectType interface extends the `SmiObject` by attributes specific to the SMI OBJECT-TYPE construct, i.e., the MAX-ACCESS clause.
  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.
  SmiParseException
  The `SmiParseException` provides information about violations of the Structure of Management Information (SMI) v1 or v2 standards.
  SmiRevision
  The SmiRevision represents the REVISION clause of a SMIv2 MODULE-IDENTITY construct.
  SmiStatus
  The SmiStatus enumerates the values of the SMIv1 and v2 STATUS clause.
  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 an enumerated value or a range restriction.
  SmiSyntaxElement.Type
  The type of enumerated value.
  SmiSyntaxImpl
  The `SmiSyntaxImpl` class represents the attributes of a SMI SYNTAX clause.
  SmiSyntaxType
  The SmiSyntaxType identifies one of four SYNTAX clause types of OBJECT-TYPE or TEXTUAL-CONVENTION SMI constructs.
  SmiTextualConvention
  The SmiTextualConvention represents the SMIv2 TEXTUAL-CONVENTION and the SMIv1 type assignment construct.
  SmiType
  The SmiType defines the SMI construct (for example `OBJECT-TYPE`) that defined the SMI object.
  SmiValueType
  Ths SmiValueType interface abstracts the common element of the OBJECT-TYPE and the TEXTUAL-CONVENTION SMI constructs.