Class SmiManager

java.lang.Object
com.snmp4j.smi.SmiManager
All Implemented Interfaces:
PolymorphicVariableFormatter, SmiCompiler, org.snmp4j.util.OIDTextFormat, org.snmp4j.util.VariableTextFormat
public final class SmiManager extends Object implements org.snmp4j.util.OIDTextFormat, org.snmp4j.util.VariableTextFormat, SmiCompiler, PolymorphicVariableFormatter
The SmiManager Pro class manages the Structure of Management Information (SMI) specifications. SMIv1 and v2 MIB modules can be parsed and compiled to a MIB repository which provides its content to SNMP4J through an OID and Variable formatter and parser.
Version:
2.0.0
Author:
Frank Fock

  • Constructor Details

    • SmiManager

      public SmiManager(String licenseKey, File repositoryDirectory) throws IOException
      Creates a SmiManager that provides the MIB information to SNMP4J through implementations of the OIDTextFormat and VariableTextFormat interfaces. In addition, MIB information can be retrieved through the methods of this class too.

      To add MIB support to your SNMP4J based application, simply add the following code in your main class: 

      static {
   SmiManager smiManager = new SmiManager("myLicenseKey", new File("myEmptyDirectory"));
   SNMP4JSettings.setOIDTextFormat(smiManager);
   SNMP4JSettings.setVariableTextFormat(smiManager);
   // If you need to disable full index formatting,
   // then choose a different format below and uncomment the line:
   // smiManager.setOidFormat(OIDFormat.ObjectNameAndDecodedIndex4RoundTrip);
}
      Parameters:
      licenseKey - the license key string you received with the purchase a SNMP4J-SMI license or its evaluation. You may provide null to use SNMP4J-SMI for free. But then you may not use any MIB modules of the "enterprise" OID subtree.
      repositoryDirectory - an empty directory where the SmiManager can read and store compiled MIB modules persistently. This directory may contain files from an existing MIB repository of AGENT++ AgenPro, MIB Designer, or MIB Explorer. It must not contain any plain text (i.e., uncompiled) MIB files.
      Throws:
      IOException - when the repositoryDirectory is not accessible.

    • SmiManager

      public SmiManager(String licenseKey, RepositoryDriver repositoryDriver)
      Creates a SmiManager that provides the MIB information to SNMP4J through implementations of the OIDTextFormat and VariableTextFormat interfaces. In addition, MIB information can be retrieved through the methods of this class too.

      To add MIB support to your SNMP4J based application, simply add the following code in your main class: 

      static {
   SmiManager smiManager = new SmiManager("myLicenseKey", new File("myEmptyDirectory"));
   SNMP4JSettings.setOIDTextFormat(smiManager);
   SNMP4JSettings.setVariableTextFormat(smiManager);
}
      Parameters:
      licenseKey - the license key string you received with the purchase a SNMP4J-SMI license or its evaluation.
      repositoryDriver - a RepositoryDriver instance which handles the reading and writing of MIB modules to disk, database, or other persistent storage.

  • Method Details

    • useCompression

      public SmiManager useCompression(boolean enableCompressionOfCompiledModules)
      Configures whether to enable or disable compression for compiled modules. Any MIB modules compiled after setting this to true will be compressed using GZIP. Existing MIB modules will not be changed. Compressed MIB modules can be read even if this setting is false. The default is @code true} since 1.12.0.
      Parameters:
      enableCompressionOfCompiledModules - a boolean value where true enables compression of compiled modules and false disables it.
      Returns:
      this instance for fluent configuration.
      Since:
      1.12.0

    • isUseCompression

      public boolean isUseCompression()
      Determines if compression is enabled for compiled MIB modules.
      Returns:
      true if compression is enabled, false otherwise
      Since:
      1.12.0

    • isIndexClauseReferenceCachingEnabled

      public boolean isIndexClauseReferenceCachingEnabled()
      Check if index caching is enabled or not.
      Returns:
      true if the caching of INDEX clauses (i.e., the reference objects therein) is enabled, false otherwise.
      Since:
      1.12.2

    • setIndexClauseReferenceCachingEnabled

      public void setIndexClauseReferenceCachingEnabled(boolean indexClauseReferenceCachingEnabled)
      Enables or disables caching of INDEX clause references. If enabled, conversions from index OIDs to variables with getIndexVariables(OID, OID) can be much faster. The cache is automatically invalidated if MIB modules are added or removed but rebuilt if any function is used that accesses the object defintions referenced by an INDEX clause.
      Parameters:
      indexClauseReferenceCachingEnabled - true if the caching of INDEX clauses (i.e., the reference objects therein) should be enabled, false otherwise (any existing cache will be deleted).
      Since:
      1.12.2

    • getOidFormat

      public SmiManager.OIDFormat getOidFormat()
      Gets the current SmiManager.OIDFormat (default is SmiManager.OIDFormat.ObjectNameAndDecodedIndex4RoundTrip).
      Returns:
      the current OID format. See setOidFormat(com.snmp4j.smi.SmiManager.OIDFormat).

    • setOidFormat

      public void setOidFormat(SmiManager.OIDFormat oidFormat)
      Sets the SmiManager.OIDFormat to be used to render object identifiers. To get numeric OIDs (e.g., "1.3.6.1.2.1") use SmiManager.OIDFormat.Numbers. To get object name prefix and numeric suffix (e.g., "ifDescr.0") use SmiManager.OIDFormat.ObjectNameNumIndex, which is the default. To get object name prefix and decoded index suffix (e.g., "vacmViewTreeFamilyType.demoReadView.mib-2" instead of "1.3.6.1.6.3.16.1.5.2.1.4.12.100.101.109.111.82.101.97.100.86.105.101.119.6.1.3.6.1.2.1") use SmiManager.OIDFormat.ObjectNameAndDecodedIndex. To get object name prefix and decoded index suffix for a round-trip (e.g., "vacmViewTreeFamilyType."demoReadView".'mib-2'" instead of "1.3.6.1.6.3.16.1.5.2.1.4.12.100.101.109.111.82.101.97.100.86.105.101.119.6.1.3.6.1.2.1") use SmiManager.OIDFormat.ObjectNameAndDecodedIndex4RoundTrip.
      Parameters:
      oidFormat - an SmiManager.OIDFormat value.

    • getOctetStringDisplayHint

      public SmiManager.OctetStringDefaultFormat getOctetStringDisplayHint()
      Gets the current OCTET STRING default display format.
      Returns:
      the SmiManager.OctetStringDefaultFormat which is used to display OCTET STRING (and enumerated) values, if there is no MIB defined DISPLAY-HINT available. The default is SmiManager.OctetStringDefaultFormat.ASCII.

    • setOctetStringDisplayHint

      public void setOctetStringDisplayHint(SmiManager.OctetStringDefaultFormat octetStringDisplayHint)
      Sets the display format for OctetString values as defined by the enumeration SmiManager.OctetStringDefaultFormat. If this value is set to any SmiManager.OctetStringDefaultFormat other than SmiManager.OctetStringDefaultFormat.MIB then enumerated values (syntax INTEGER with labels) will be formatted by format(org.snmp4j.smi.OID, org.snmp4j.smi.Variable, boolean) as number. Otherwise as label(n) where n is the INTEGER number and label the enum label.
      Parameters:
      octetStringDisplayHint - the display format. SmiManager.OctetStringDefaultFormat.MIB is the default and displays the values as defined in the MIB. If there is no DISPLAY-HINT in the MIB format, OCTET STRING values will be displayed in ASCII format.

    • listModules

      public String[] listModules() throws IOException
      Returns the MIB module names of the MIB modules available in the repository directory.
      Returns:
      an array of MIB module names.
      Throws:
      IOException - if the repository directory cannot be read and listed.

    • getLoadedModuleNames

      public String[] getLoadedModuleNames()
      Returns the MIB module names of the MIB modules loaded into the SmiManager either explicitly by a previous call of loadModule(String) and compile(NamedInputStream[], CompilationMonitor, TargetMode, OverwriteMode, Strictness) with SmiCompiler.TargetMode.storeIntoRepositoryAndLoad or indirectly by imports of directly loaded MIB modules.
      Returns:
      an array of MIB module names.

    • getExplicitlyLoadedModuleNames

      public String[] getExplicitlyLoadedModuleNames()
      Returns the MIB module names of the MIB modules explicitly loaded with the loadModule(String) and compile(NamedInputStream[], CompilationMonitor, TargetMode, OverwriteMode, Strictness) with SmiCompiler.TargetMode.storeIntoRepositoryAndLoad into the SmiManager. This method will not return MIB module names of MIB modules that were loaded because of IMPORT dependencies only.
      Returns:
      an array of MIB module names.
      Since:
      1.9.0 (Pro edition only)

    • getLoadedSmiModules

      public List<SmiModule> getLoadedSmiModules() throws IOException
      Get the SmiModule object for all loaded MIB modules.
      Returns:
      the list of loaded SmiModule instances.
      Throws:
      IOException - if the repository manager uses an IO based RepositoryDriver and the IO operation failed.
      Since:
      1.7.1

    • loadModule

      public boolean loadModule(String moduleName)
      Loads a MIB module from disk (MIB repository) into memory. If the module has been loaded its data is available for the formatting and parsing operations of this SmiManager instance.
      Parameters:
      moduleName - the MIB module name (e.g. "SNMPv2-MIB").
      Returns:
      true if the module and all the MIB objects it is importing from other modules could be loaded successfully, false otherwise.

    • loadAllModules

      public List<SmiModule> loadAllModules() throws IOException
      Loads all modules concurrently, using a thread pool with a maximum number of threads equal to the number of available processors.
      Returns:
      a list of loaded modules.
      Throws:
      IOException - if the repository directory cannot be read and listed.
      Since:
      2.0.1

    • loadModules

      public boolean[] loadModules(String[] moduleNames, int maxThreads, boolean overwriteExistingObjects)
      Loads the specified modules concurrently, using a thread pool with a maximum number of threads defined by the given parameter. The method attempts to load the modules either completely. Depending on the value of the `overwriteExistingObjects` flag, already loaded objects from the same module (identified by a technical ID from the repository) will be removed and reloaded or added as a duplicate.
      Parameters:
      moduleNames - an array of strings representing the names of the modules to load
      maxThreads - the maximum number of threads to be used for concurrent loading operations
      overwriteExistingObjects - a boolean flag specifying whether existing objects should be overwritten. It is recommended to use true unless you need to load MIB modules as quickly as possible.
      Returns:
      a boolean array where each element corresponds to the success state of loading the respective module
      Since:
      1.12.0

    • getPolymorphicFormatterFactory

      public PolymorphicVariableFormatterFactory getPolymorphicFormatterFactory()
      Get the polymorphic formatter factory.
      Returns:
      PolymorphicVariableFormatterFactory used by this SmiManager instance.
      Since:
      2.0.0

    • setPolymorphicFormatterFactory

      public void setPolymorphicFormatterFactory(PolymorphicVariableFormatterFactory polymorphicFormatterFactory)
      Set the polymorphic formatter factory. By default, the DefaultPolymorphicVariableFormats is used.
      Parameters:
      polymorphicFormatterFactory - PolymorphicVariableFormatterFactory to be used by this SmiManager instance.
      Since:
      2.0.0

    • unloadModule

      public boolean unloadModule(String moduleName)
      Unload a MIB module from the SmiManager memory. The corresponding MIB module in the MIB repository directory will not be modified.
      Parameters:
      moduleName - a MIB module name.
      Returns:
      true if the MIB module was in memory and is now removed, false otherwise.

    • resetModules

      public void resetModules()
      Remove all loaded modules from memory and clears the module repository. This method performs the following actions: 1. Clears the module repository to ensure all loaded modules are removed. 2. Empties the collection of loaded modules, resetting the internal state. This method is synchronized to ensure thread safety when accessing or modifying the module repository and loaded module list.
      Since:
      1.12.0

    • unloadModuleWithDependencies

      public final int unloadModuleWithDependencies(String moduleName)
      Unload a MIB module from the SmiManager memory, including all its dependencies that are not needed by other loaded MIB modules. The compiled MIB modules in the MIB repository directory will not be modified.
      Parameters:
      moduleName - a MIB module name.
      Returns:
      The number of MIB objects removed from the memory (including the module itself). If zero is returned, then no object has been removed.
      Since:
      1.9.0

    • isModuleLoaded

      public final boolean isModuleLoaded(String moduleName)
      Checks if the MIB module with the specified name is already loaded into the SmiManager from disk.
      Parameters:
      moduleName - a MIB module name.
      Returns:
      true if the MIB module is loaded, false otherwise.

    • deleteModule

      public final List<String> deleteModule(String moduleName, boolean forceDeletion)
      Deletes a MIB module from the MIB repository directory if it is not used/imported by other MIB modules in the repository.
      Parameters:
      moduleName - the MIB module name of the module which should be deleted.
      forceDeletion - if true, it will not be checked if other MIB modules in the repository import from the MIB module with name moduleName, otherwise that check is performed and the MIB module will not be deleted if it is still used by depending MIB modules. WARNING: Deleting a MIB module which is used by others can lead to errors while accessing those modules.
      Returns:
      an empty List if the MIB module has been deleted or one or more MIB module names of MIB modules that depend on the MIB module with the name moduleName. If the list contains only one element and that is the module's name, then the RepositoryDriver did not allow to delete the MIB module or an IO error occurred.

    • compile

      public final String[] compile(File textOrZipFile) throws SmiParseException, FileNotFoundException
      Compiles a MIB module from a given text or ZIP file.
      Parameters:
      textOrZipFile - an existing text or ZIP file. A ZIP file must end with ".ZIP" or ".zip" to be recognized as ZIP file.
      Returns:
      an array of the module names successfully parsed.
      Throws:
      SmiParseException - if the MIB module contains a syntax or semantic error.
      FileNotFoundException - if the specified cannot be found or opened for reading.

    • resetOidQuoting

      public void resetOidQuoting()
      Resets the OID quotation characters and escape sequences to the default (which is highly recommended to be used). This method executes as follows: 
         oidFixedLengthStringQuote = '\'';
   oidVariableLengthStringQuote = '"';
   oidFixedLengthStringQuoteEscapeSequence = "\\'";
   oidVariableLengthStringQuoteEscapeSequence =  "\\\"";
   oidStringQuoteEscapeCharacter = '\\';
      Since:
      1.1.1

    • getOidFixedLengthStringQuote

      public char getOidFixedLengthStringQuote()
      Gets the quote character for fixed length formatted sub-index OIDs.
      Returns:
      a quote character, by default the single quote '.
      Since:
      1.1.1

    • setOidFixedLengthStringQuote

      public void setOidFixedLengthStringQuote(char oidFixedLengthStringQuote)
      Sets the quote character for fixed length formatted sub-index OIDs.
      Parameters:
      oidFixedLengthStringQuote - a quote character.
      Since:
      1.1.1

    • getOidVariableLengthStringQuote

      public char getOidVariableLengthStringQuote()
      Gets the quote character for variable length formatted subindex OIDs.
      Returns:
      a quote character, by default the double quote ".
      Since:
      1.1.1

    • setOidVariableLengthStringQuote

      public void setOidVariableLengthStringQuote(char oidVariableLengthStringQuote)
      Sets the quote character for variable length formatted subindex OIDs.
      Parameters:
      oidVariableLengthStringQuote - a quote character.
      Since:
      1.1.1

    • getOidFixedLengthStringQuoteEscapeSequence

      public String getOidFixedLengthStringQuoteEscapeSequence()
      Gets the sequence to escape a character sequence for fixed length formatted subindex OID quotes.
      Returns:
      a quote escape sequence.
      Since:
      1.1.1

    • setOidFixedLengthStringQuoteEscapeSequence

      public void setOidFixedLengthStringQuoteEscapeSequence(String oidFixedLengthStringQuoteEscapeSequence)
      Sets the sequence to escape character sequence for fixed length formatted subindex OID quotes.
      Parameters:
      oidFixedLengthStringQuoteEscapeSequence - a quote escape sequence.
      Since:
      1.1.1

    • getOidVariableLengthStringQuoteEscapeSequence

      public String getOidVariableLengthStringQuoteEscapeSequence()
      Gets the sequence to escape character sequence for variable length formatted subindex OID quotes.
      Returns:
      a quote escape sequence.

    • setOidVariableLengthStringQuoteEscapeSequence

      public void setOidVariableLengthStringQuoteEscapeSequence(String oidVariableLengthStringQuoteEscapeSequence)
      Sets the sequence to escape character sequence for variable length formatted sub-index OID quotes.
      Parameters:
      oidVariableLengthStringQuoteEscapeSequence - a quote escape sequence.
      Since:
      1.1.1

    • getOidStringQuoteEscapeCharacter

      public char getOidStringQuoteEscapeCharacter()
      Gets the OID string escape character for quotes. This character must be used to define the both escape sequences getOidFixedLengthStringQuoteEscapeSequence() and getOidVariableLengthStringQuoteEscapeSequence(). Otherwise the results of formatting and parsing of OIDs are undefined.
      Returns:
      the escape character (default is the backslash character) for escaping OID string quotes.

    • setOidStringQuoteEscapeCharacter

      public void setOidStringQuoteEscapeCharacter(char oidStringQuoteEscapeCharacter)
      Sets the OID string escape character for quotes. This character must be used to define the both escape sequences getOidFixedLengthStringQuoteEscapeSequence() and getOidVariableLengthStringQuoteEscapeSequence(). Otherwise, the results of formatting and parsing of OIDs are undefined!
      Parameters:
      oidStringQuoteEscapeCharacter - the escape character (default is the backslash character) for escaping OID string quotes.

    • compile

      public String[] compile(NamedInputStream mibFile) throws SmiParseException
      Compiles a MIB module from a given InputStream and returns the names of the compiled MIB modules from the stream.
      Parameters:
      mibFile - a stream containing the contents of one or more MIB module specifications.
      Returns:
      an array of MIB module names compiled from the stream.
      Throws:
      SmiParseException - if the specification has SMI syntax or semantic errors.

    • compile

      public List<CompilationResult> compile(File[] files, CompilationMonitor compilationMonitor, boolean loadIntoRepository, boolean updateExistent, boolean compileLeniently) throws IOException
      Compiles an array of text or ZIP files provided as Files. The compilation is executed in three phases:
      1. The provided files are loaded into memory.
      2. The loaded files are analyzed about their module names and then sorted according to their dependencies to other modules.
      3. The sorted MIB modules will then be compiled and written into the internal MIB repository. In addition, if enabled, the compiled MIB modules will also be loaded into the MIB cache.
      The compilation progress can be monitored by callbacks through the CompilationMonitor interface.
      Parameters:
      files - an array of File instances where each instance may represent a text or ZIP file. ZIP file names have to end with ".ZIP" or ".zip".
      compilationMonitor - an optional CompilationMonitor implementation to monitor the progress of the compilation.
      loadIntoRepository - if true the compiled MIB modules will not only be stored into the internal MIB repository, but also directly loaded into the MIB cache so that they can be used right after this method call completes.
      updateExistent - if true compiled MIB modules will replace existing MIB modules in the MIB repository with the same module names.
      compileLeniently - if true syntax and semantic checks are limited to the necessary minimum. A MIB module that can be successfully parsed in lenient mode may contain severe standard violations and even errors that can affect proper formatting and value parsing support for SNMP4J. Use this option only if you can handle the risk or if you are not able to fix or let fix the errors in the MIB specification(s).
      Returns:
      a List of CompilationResult instances. Each instance represents an input file. For ZIP files, a CompilationResult instance is returned for each ZIP file entry.
      Throws:
      IOException - if any IO operation fails when accessing the input files (InputStreams).

    • compile

      public List<CompilationResult> compile(NamedInputStream[] files, CompilationMonitor compilationMonitor, SmiCompiler.TargetMode compilerTargetMode, SmiCompiler.OverwriteMode overwriteMode, SmiCompiler.Strictness strictness) throws IOException
      Description copied from interface: SmiCompiler
      Compiles an array of text or ZIP files provided as NamedInputStreams. The compilation is executed in three phases:
      1. The provided NamedInputStreams are loaded into memory.
      2. The loaded files are analyzed about their module names and then sorted according to their dependencies to other modules.
      3. The sorted MIB modules will then be compiled and written into the internal MIB repository. In addition, if enabled, the compiled MIB modules will also be loaded into the MIB cache.
      The compilation progress can be monitored by callbacks through the CompilationMonitor interface.
      Specified by:
      compile in interface SmiCompiler
      Parameters:
      files - an array of NamedInputStream instances where each instance may represent a text or ZIP file.
      compilationMonitor - an optional CompilationMonitor implementation to monitor the progress of the compilation.
      compilerTargetMode - with the mode SmiCompiler.TargetMode.storeIntoRepositoryAndLoad the compiled MIB modules will not only be stored into the internal MIB repository, but also directly loaded into the MIB cache so that they can be used right after this method call completes. With SmiCompiler.TargetMode.dryRun no modifications to the MIB repository or MIB cache are done and only the result of the syntax check is returned.
      overwriteMode - specifies whether compiled MIB modules will replace existing MIB modules in the MIB repository as well as in the cache with the same module names or not.
      strictness - if SmiCompiler.Strictness.lenient is used then syntax and semantic checks are limited to the necessary minimum. A MIB module that can be successfully parsed in lenient mode may contain severe standard violations and even errors that can affect proper formatting and value parsing support for SNMP4J. Use this option only if you can handle the risk or if you are not able to fix or let fix the errors in the MIB specification(s).
      Returns:
      a List of CompilationResult instances. Each instance represents an input file. For ZIP files, a CompilationResult instance is returned for each ZIP file entry.
      Throws:
      IOException - if any IO operation fails when accessing the input files (InputStreams).

    • compile

      public List<CompilationResult> compile(NamedInputStream[] files, CompilationMonitor compilationMonitor, SmiCompiler.TargetMode compilerTargetMode, SmiCompiler.OverwriteMode overwriteMode, SmiCompiler.Strictness strictness, int maxThreads) throws IOException
      Compiles an array of text or ZIP files provided as NamedInputStreams, optionally using several threads to compile independent MIB modules in parallel. This is the multi-threaded variant of compile(NamedInputStream[], CompilationMonitor, com.snmp4j.smi.SmiCompiler.TargetMode, com.snmp4j.smi.SmiCompiler.OverwriteMode, com.snmp4j.smi.SmiCompiler.Strictness).

      After the input modules have been sorted by their dependencies, the ModuleInfoSorter groups the cleanly resolvable modules into dependency levels where all modules of a level are independent of each other. The modules of a level are parsed and semantically analyzed in parallel and then stored serially into the repository before the next (higher) level is processed. Modules with unresolved dependencies or import cycles are compiled sequentially afterwards, as with the single-threaded variant.

      The returned CompilationResult list, its order and all CompilationMonitor callbacks are identical to those of the single-threaded variant - only the actual parsing/semantic analysis runs concurrently.

      Thread-safety note: when maxThreads > 1 and this SmiManager was created with a custom RepositoryDriver, that driver's read operations (RepositoryDriver.readModule(RepositoryIO) / RepositoryDriver.listModuleNames()) must be thread-safe, because imported modules are resolved concurrently during the parallel parse phase. The default file-/classpath-based repository is thread-safe in this respect. If in doubt, pass maxThreads = 1. Note that unique module IDs are allocated during the (parallel) parse phase, so module IDs are consumed even for modules whose compilation later fails - this matches the single-threaded behavior.

      Parameters:
      files - an array of NamedInputStream instances where each instance may represent a text or ZIP file.
      compilationMonitor - an optional CompilationMonitor implementation to monitor the progress of the compilation.
      compilerTargetMode - the SmiCompiler.TargetMode controlling whether modules are only checked (dry run) or stored into the repository (and optionally loaded).
      overwriteMode - the SmiCompiler.OverwriteMode controlling how existing modules are handled.
      strictness - the SmiCompiler.Strictness controlling how strictly modules are parsed.
      maxThreads - the maximum number of threads to use for parallel compilation. Values <= 1 select the single-threaded compilation (no behavioral change). Larger values are capped at the number of available processors (Runtime.availableProcessors()).
      Returns:
      a List of CompilationResult instances, identical to the single-threaded variant.
      Throws:
      IOException - if any IO operation fails when accessing the input files (InputStreams) or the repository.
      Since:
      2.0.1

    • compile

      @Deprecated public List<CompilationResult> compile(NamedInputStream[] files, CompilationMonitor compilationMonitor, boolean loadIntoRepository, boolean updateExistent, boolean compileLeniently) throws IOException
      Deprecated.
      Use compile(NamedInputStream[], CompilationMonitor, com.snmp4j.smi.SmiCompiler.TargetMode, com.snmp4j.smi.SmiCompiler.OverwriteMode, com.snmp4j.smi.SmiCompiler.Strictness) instead which provides a cleaner interface.
      Compiles an array of text or ZIP files provided as NamedInputStreams. The compilation is executed in three phases:
      1. The provided NamedInputStreams are loaded into memory.
      2. The loaded files are analyzed about their module names and then sorted according to their dependencies to other modules.
      3. The sorted MIB modules will then be compiled and written into the internal MIB repository. In addition, if enabled, the compiled MIB modules will also be loaded into the MIB cache.
      The compilation progress can be monitored by callbacks through the CompilationMonitor interface.
      Parameters:
      files - an array of NamedInputStream instances where each instance may represent a text or ZIP file.
      compilationMonitor - an optional CompilationMonitor implementation to monitor the progress of the compilation.
      loadIntoRepository - if true the compiled MIB modules will not only be stored into the internal MIB repository, but also directly loaded into the MIB cache so that they can be used right after this method call completes.
      updateExistent - if true compiled MIB modules will replace existing MIB modules in the MIB repository with the same module names.
      compileLeniently - if true syntax and semantic checks are limited to the necessary minimum. A MIB module that can be successfully parsed in lenient mode may contain severe standard violations and even errors that can affect proper formatting and value parsing support for SNMP4J. Use this option only if you can handle the risk or if you are not able to fix or let fix the errors in the MIB specification(s).
      Returns:
      a List of CompilationResult instances. Each instance represents an input file. For ZIP files, a CompilationResult instance is returned for each ZIP file entry.
      Throws:
      IOException - if any IO operation fails when accessing the input files (InputStreams).

    • format

      public final String format(org.snmp4j.smi.OID instanceOID, org.snmp4j.smi.Variable variable, boolean withOID)
      Specified by:
      format in interface org.snmp4j.util.VariableTextFormat

    • parseVariableBinding

      public final org.snmp4j.smi.VariableBinding parseVariableBinding(String text) throws ParseException
      Specified by:
      parseVariableBinding in interface org.snmp4j.util.VariableTextFormat
      Throws:
      ParseException

    • parse

      public final org.snmp4j.smi.Variable parse(org.snmp4j.smi.OID classOrInstanceOID, String text) throws ParseException
      Specified by:
      parse in interface org.snmp4j.util.VariableTextFormat
      Throws:
      ParseException

    • parse

      public final org.snmp4j.smi.Variable parse(int smiSyntax, String text) throws ParseException
      Specified by:
      parse in interface org.snmp4j.util.VariableTextFormat
      Throws:
      ParseException

    • parseByTC

      public org.snmp4j.smi.Variable parseByTC(org.snmp4j.smi.OID classOrInstanceOID, String textualConventionObjectName, String variableText)
      Parses a string representation of a variable using a textual convention defined in the MIB.
      Parameters:
      classOrInstanceOID - The object identifier (OID) of the class or instance to which the variable belongs.
      textualConventionObjectName - The name of the textual convention object (the MIB module name can be used as prefix separated with '.') used to interpret the variable.
      variableText - The string representation of the variable to be parsed.
      Returns:
      A Variable object constructed from the input string, or null if parsing fails or the relevant textual convention or object type is not found.
      Since:
      2.0.0

    • format

      public final String format(int[] value)
      Specified by:
      format in interface org.snmp4j.util.OIDTextFormat

    • formatRowIndex

      public String formatRowIndex(org.snmp4j.smi.OID columnOrTableEntryOID, org.snmp4j.smi.OID indexOID)
      Formats a row index OID into a string representation.
      Parameters:
      columnOrTableEntryOID - the OID of the table entry. If null, the indexOID is returned as string.
      indexOID - the OID of the row index.
      Returns:
      the formatted index string or the dotted OID string if formatting fails.
      Since:
      2.0.0

    • formatForRoundTrip

      public String formatForRoundTrip(int[] value)
      Specified by:
      formatForRoundTrip in interface org.snmp4j.util.OIDTextFormat

    • parse

      public final int[] parse(String text) throws ParseException
      Specified by:
      parse in interface org.snmp4j.util.OIDTextFormat
      Throws:
      ParseException

    • tokenizeQuotedString

      public static List<String> tokenizeQuotedString(String text, String quotes, char escapeChar, String delimiter, boolean includeQuotes)
      Tokenize a string by a delimiter string but do not split quoted strings with the supplied quote characters. Value escaping of the quote characters as well.
      Parameters:
      text - the text to tokenize (split into pieces).
      quotes - the list of quote characters to process.
      escapeChar - the escape character that can be used to escape quotes.
      delimiter - the delimiter string that separates the tokens.
      includeQuotes - if true quotes will be return as part of the returned tokens, otherwise they will be removed from the token boundaries.
      Returns:
      the list of tokens.

    • getOidFormatNonPrintableStrings

      public SmiManager.NonPrintableStringFormat getOidFormatNonPrintableStrings()
      Gets the SmiManager.NonPrintableStringFormat for strings in formatted OIDs. A string is not printable if it contains any ISO control characters as defined by Character.isISOControl(char) except if these ISO control characters are all whitespace characters as defined by Character.isWhitespace(char) and not '&#92;u001C'-'&#92;u001F'.
      Returns:
      the current format for non-printable strings.
      Since:
      1.1

    • setOidFormatNonPrintableStrings

      public void setOidFormatNonPrintableStrings(SmiManager.NonPrintableStringFormat oidFormatNonPrintableStrings)
      Sets the SmiManager.NonPrintableStringFormat for strings in formatted OIDs. The default is SmiManager.NonPrintableStringFormat.asIs
      Parameters:
      oidFormatNonPrintableStrings - the new format for non-printable strings (must not be null).
      Since:
      1.1

    • getIndexVariables

      public org.snmp4j.smi.Variable[] getIndexVariables(org.snmp4j.smi.OID table, org.snmp4j.smi.OID index)
      Gets the variable values for all subindex objects for the specified table entry.
      Parameters:
      table - the table entry OID (= "tableOID.1") the index OID belongs to.
      index - the index OID which should be split into its subindex values (variables).
      Returns:
      null if the table entry OID cannot be resolved, otherwise the index OID is split into the subindex variables which are then returned as an array.

    • getIndexStringFromVariables

      public String getIndexStringFromVariables(org.snmp4j.smi.OID table, List<org.snmp4j.smi.VariableBinding> indexObjects)
      Gets the INDEX string representations from a list of INDEX objects.
      Parameters:
      table - the table definition with the INDEX clause to be used for the conversion.
      indexObjects - a list of INDEX object values.
      Returns:
      creates dot ('.') separated string representation of the given INDEX objects using the variable display

    • findSmiObject

      public SmiObject findSmiObject(org.snmp4j.smi.OID oid)
      Gets the SMI object defined for the specified OID. For SMI objects that have no OID, i.e., TEXTUAL CONVENTIONS you will have to use findSmiObject(String, String) instead.
      Parameters:
      oid - the object identifier of the SMI object to return.
      Returns:
      the SMI object that provides additional information about a MIB object.
      Since:
      1.2 (Pro edition only)

    • getTableEntry

      public SmiObjectType getTableEntry(org.snmp4j.smi.OID colOID)
      Gets the SMI table object defined for the specified OID. If the specified OID is not a table entry OID, but a table OID, the table entry OID is derived from the table OID. Otherwise, null is returned.
      Parameters:
      colOID - the object identifier of the SMI table object to return.
      Returns:
      the SmiObjectType that provides information about a MIB table object type with the INDEX definition, or null if the specified OID does not correspond to a table entry or table OID.
      Since:
      2.0.0

    • findSmiObjectType

      public SmiObjectType findSmiObjectType(org.snmp4j.smi.OID oidInstance)
      Gets the SMI object type defined for the specified instance OID. For looking up SMI objectfrom their OID, thus without index suffix use findSmiObject(OID) instead. For example, this method will return the SmiObject sysDescr on "1.3.6.1.2.1.1.1.0" and "1.3.6.1.2.1.1.1" if the SNMPv2-MIB is loaded. If IF-MIB is loaded, "1.3.6.1.2.1.2.2.1.7.20100" will return the ifAdminStatus SmiObjectType.
      Parameters:
      oidInstance - the object instance identifier of the SMI OBJECT-TYPE to lookup.
      Returns:
      the SmiObjectType that provides information about a MIB object type.
      Since:
      1.9.14 (Pro edition only)

    • findRootSmiObject

      public SmiObject findRootSmiObject()
      Gets the SMI object with the lexicographic smallest OID within the currently loaded MIB modules.
      Returns:
      the SmiObject with the smallest OID (which exists - i.e. SmiTextualConvention instances must not be returned) within all loaded MIB modules. If no module with an object with OID is loaded then null will be returned.
      Since:
      1.2 (Pro edition only)

    • findRootSmiObject

      public SmiObject findRootSmiObject(String moduleName)
      Gets the SMI object with the lexicographic smallest OID within the given loaded MIB module.
      Parameters:
      moduleName - the module name for which the root object should be returned. If there is no MIB module loaded with that name or it contains no object identifiers, then null is returned.
      Returns:
      the SmiObject with the smallest OID (which exists - i.e. SmiTextualConvention instances must not be returned) within the given loaded MIB module.
      Since:
      1.9 (Pro edition only)

    • findSmiModule

      public SmiModule findSmiModule(String moduleName)
      Gets the SmiModule with the specified module name. Note: The module name is an uppercase name and is always different from the MODULE-IDENTITY object name which starts with a lower case letter.

      For SMIv2 the returned SmiModule is also a SmiModuleIdentity!

      Parameters:
      moduleName - a MIB module name (e.g. SNMPv2-MIB).
      Returns:
      the SmiModule with the module name moduleName or null if such a module has not been loaded yet with loadModule(String).
      Since:
      1.2 (Pro edition only)

    • findSmiModules

      public List<SmiModule> findSmiModules(org.snmp4j.smi.OID smiObjectIdentifier)
      Gets the SmiModule that defines the provided object identifier.

      For SMIv2 the returned SmiModule is also a SmiModuleIdentity!

      Parameters:
      smiObjectIdentifier - an OID of an object that is defined by the MIB module (usage by import will not match).
      Returns:
      a list of SmiModules defining the provided OID or null if the OID could not be found in any module. The returned list might be empty if no MIB module that defines it is currently loaded with loadModule(String)).
      Since:
      1.6 (Pro edition only)

    • findSmiObject

      public SmiObject findSmiObject(String moduleName, String objectName)
      Gets the SMI object defined for the specified object name. For SMI objects that have an OID, i.e. OBJECT-TYPE it is recommended to use the findSmiObject(org.snmp4j.smi.OID) instead if possible in order to avoid ambiguities when not able to provide a MIB module name.
      Parameters:
      moduleName - the name of the MIB module, the object is defined in.
      objectName - the name of the SMI object to return.
      Returns:
      the SMI object that provides additional information about a MIB object.
      Since:
      1.2 (Pro edition only)

    • findSmiObject

      public SmiObject findSmiObject(String moduleName, String objectName, boolean includeImportedModules)
      Gets the SMI object defined for the specified object name. For SMI objects that have an OID, i.e. OBJECT-TYPE it is recommended to use the findSmiObject(org.snmp4j.smi.OID) instead if possible in order to avoid ambiguities when not able to provide a MIB module name.
      Parameters:
      moduleName - the name of the MIB module, the object is defined in or imported by (if includeImportedModules is set to true).
      objectName - the name of the SMI object to return.
      includeImportedModules - if false this method behaves exactly like findSmiObject(String, String) if true then first the provided moduleName is searched for the definition of an object with the name objectName. If it is not found then the first import of an object with that name is used and findSmiObject(String, String) is called with the MIB module name of that import dependency.
      Returns:
      the SMI object that provides additional information about a MIB object.
      Since:
      1.7 (Pro edition only)

    • findSmiObject

      public <S extends SmiObject> List<S> findSmiObject(String moduleName, SmiObjectFilter<S> filter)
      Gets the SMI object defined for the specified OID. For SMI objects that have an OID, i.e., OBJECT-TYPE it is recommended to use the findSmiObject(org.snmp4j.smi.OID) instead if possible to avoid ambiguities when not able to provide a MIB module name.
      Type Parameters:
      S - the type of the SMI object to find.
      Parameters:
      moduleName - the name of the MIB module, the object is defined in or null when objects of all modules should be returned.
      filter - a SmiObjectFilter instance that selects the objects to return by callback.
      Returns:
      a list of SMI objects matching the filter and null if the specified moduleName could not be found.
      Since:
      1.2 (Pro edition only)

    • setIncludeUnknownErrorsCause

      public void setIncludeUnknownErrorsCause(boolean includeUnknownErrorsCause)
      Sets the flag that controls whether exceptions or other unknown error messages during parsing and storing of MIB modules to the repository should be included in the error message or not.
      Parameters:
      includeUnknownErrorsCause - if true the message text of caught exceptions during MIB compilation will be included in the "errUnknownError" message, false otherwise (the default).
      Since:
      1.3 (Pro edition only)

    • isIncludeUnknownErrorsCause

      public boolean isIncludeUnknownErrorsCause()
      Returns the flag that controls whether exceptions or other unknown error messages during parsing and storing of MIB modules to the repository should be included in the error message or not.
      Returns:
      true if the message text of caught exceptions during MIB compilation will be included in the "errUnknownError" message, false otherwise (the default).
      Since:
      1.3 (Pro edition only)

    • setSmiErrorTextResourceBundle

      public void setSmiErrorTextResourceBundle(String resourceBundleClassName)
      Sets the class name of the custom resource bundle for SMI error texts. You need to set this value only if you want to provide your own error texts or error texts for languages other than English.
      Parameters:
      resourceBundleClassName - the class name (including package name) of the resource bundle with the SMI error texts. For an example message resource bundle, see the "examples" directory of the distribution.
      Since:
      1.3 (Pro edition only)

    • setStoreFilenamesInRepository

      public void setStoreFilenamesInRepository(boolean storeFilenameInRepository)
      Sets a system property that controls whether the MIB compiler will store the file names of the MIB files into the repository when a MIB module is compiled. The filename can be later read with the SmiModule.getSourceFilename() method.
      Parameters:
      storeFilenameInRepository - if true file names are stored, otherwise not stored at all (default).
      Since:
      1.6

    • isStoreFilenamesInRepository

      public boolean isStoreFilenamesInRepository()
      Checks a system property that controls whether the MIB compiler will store the file names of the MIB files into the repository when a MIB module is compiled or not.
      Returns:
      if true file names are stored, otherwise not stored at all (default).
      Since:
      1.6

    • formatVariable

      public String formatVariable(org.snmp4j.smi.OID oid, org.snmp4j.smi.Variable variable, List<? extends org.snmp4j.smi.VariableBinding> rowData, org.snmp4j.util.VariableTextFormat fallbackFormatter)
      Description copied from interface: PolymorphicVariableFormatter
      Formats a variable according to the given OID and row data using the currently configured available polymorphic Variable implementations. If no such implementation is available, the variable is formatted by the given VariableTextFormat implementation.
      Specified by:
      formatVariable in interface PolymorphicVariableFormatter
      Parameters:
      oid - the instance OID of the variable.
      variable - the variable to format.
      rowData - the VariableBindings available of the same row where the variable is located. If there is another column that has been associated per configuration with this column oid and that column OID defines a polymorphic Variable type for this column, then this variable is formatted using the VariableTextFormat that is associated with the variable value of type-defining column.
      fallbackFormatter - the fallback formatter to use if no polymorphic implementation is available.
      Returns:
      the formatted variable.

    • addPolymorphicVariableTypeMapping

      public PolymorphicColumnType addPolymorphicVariableTypeMapping(org.snmp4j.smi.OID typeColumnOID, PolymorphicColumnType polymorphicColumnType)
      Description copied from interface: PolymorphicVariableFormatter
      Adds a polymorphic variable type mapping.
      Specified by:
      addPolymorphicVariableTypeMapping in interface PolymorphicVariableFormatter
      Parameters:
      typeColumnOID - the OID of the column that defines the polymorphic variable type.
      polymorphicColumnType - the polymorphic variable type mapping.
      Returns:
      the previously registered polymorphic variable type mapping or null if there was no such mapping.

    • removePolymorphicVariableTypeMapping

      public PolymorphicColumnType removePolymorphicVariableTypeMapping(org.snmp4j.smi.OID variableColumnOID)
      Description copied from interface: PolymorphicVariableFormatter
      Removes a polymorphic variable type mapping.
      Specified by:
      removePolymorphicVariableTypeMapping in interface PolymorphicVariableFormatter
      Parameters:
      variableColumnOID - the OID of the column that defines the polymorphic variable.
      Returns:
      the removed polymorphic variable type mapping.