README.txt, v.1.2, 2003-03-27, Per Cederberg <per@percederberg.net>
===================================================================


1. Introduction
---------------

  This package contains MIB parser library for Java. The parser can 
  be used to parse MIB files as well as simple ASN.1 files. It does 
  not provide any useful stand-alone program, but rather a couple of
  simple examples demonstrating how the library can be used from 
  within other programs.

  This library has several known problems and shortcomings, and 
  should be considered work in progress. All known issues are 
  documented separately in the TODO.txt file, please read that file
  before filing bug reports. Most importantly, only SNMPv1 is fully
  supported in this release, support for other versions of SNMP is
  experimental. Please consider contributing (see below) if you wish
  to improve this software.

  This work is free software; you can redistribute it and/or modify 
  it under the terms of the GNU General Public License as published 
  by the Free Software Foundation; either version 2 of the License, 
  or (at your option) any later version.
 
  This work is distributed in the hope that it will be useful, but 
  WITHOUT ANY WARRANTY; without even the implied warranty of 
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
  separate LICENCE.txt file for more details.


2. Background
-------------

  The SNMP (Simple Network Management Protocol) is used to manage and 
  monitor devices remotely over a network. In order for both ends to 
  communicate correctly, the available parameters and semantics of 
  each of them are described in a MIB (Managable Information Base, 
  RFC 1155) file. The MIB file contains the details of all the 
  parameters available for reading and writing, as well as type 
  information and descriptions.

  The MIB file format is an ASN.1 (ISO 8824) syntax, with some
  additional macros predefined. In general, a MIB file can contain 
  any ASN.1 construct, but normally they only use simple data types 
  such as strings, numbers, etc. The full ASN.1 syntax, however, 
  allows definitions of macros that extends the syntax itself. This 
  latter form of ASN.1 construct is not supported by this parser. A 
  more detailed description of the syntax and limitations of ASN.1 
  and MIB files can be found in the following essay:

    http://www.percederberg.net/home/essays/master/master.html

  Several versions of SNMP exist, the latest being version 3 (RFC 
  3410) that was approved as an Internet standard in March 2002. The
  previous versions, SNMPv1 (RFC 1157) and SNMPv2 (RFC 1901), are 
  still the most commonly used, however.


3. Acknowledgements
-------------------

  This library is the result of many hours of hard work. The persons
  involved as of this release are:
  
    Per Cederberg <per@percederberg.net>
        Original creator of this library.
    Helena Sarin <hsarin@lucent.com>
        Simple JavaCC MIB grammar in the public domain.
    Your Name
        When you have contributed to this project.

  Parts of this work originates from an internal MIB processing and 
  code generation tool (Plug-Out) developed at Ericson Telecom. That 
  tool was developed for a Master's thesis in 1999 (documented in 
  http://www.percederberg.net/home/essays/master/master.html). 
  Ericsson has since kindly allowed the relicensing of this code 
  under the GNU GPL.



4. Contributions
----------------

  If you find this library useful or interesting, please consider to
  contribute to this project. The easiest way to contribute is to 
  report errors or issues regarding the use of this library. If you
  are able to fix the issue in the sources or provide test data to 
  demonstrate the problem, it would be ever better. Of course, you
  are also very welcome to do any additions or improvements to the 
  source code.
  
  Please send your suggestions, improvements and/or comments to 
  <mibparser@percederberg.net>. Also consider dropping a mail if you 
  choose to use this library, so that we can keep you informed about
  new releases or similar.



5. Some Implementation Notes
---------------------------- 

  The MIB parser in this distribution parses the files in a
  multi-stage process. The first stage is to read the file and create 
  the ASN.1 parse tree, i.e. a hierarchical structure in memory of 
  all the contents. Thereafter a first pass semantical analysis is 
  made that identifies all symbol names and checks for unsupported 
  constructs. In the second and last semantical pass, the symbol 
  types are validated and object identifiers are created for all 
  objects. Both of the two semantical analysis passes operate on the 
  same parse tree, without need to read the file twice from disk.

  The ASN.1 parser is created by JavaCC from the AsnParser.jj file. 
  All the source code generated by JavaCC is distributed in this 
  package, so there is no need to download and install JavaCC if no 
  changes are made to the grammar. Also, as a parse tree is created 
  by the grammar, there is no need to modify the parser in order to 
  change the semantics or processing stages. These stages instead 
  operate cleanly on the parse tree. As the support for parse trees 
  in JavaCC is far from being perfect, a manual approach to parse 
  tree creation has been taken. This implies that some changes in the 
  grammar file also require manual changes in other classes.
