Getting started: the 1-minute introduction
Configuring your environment to use the Java version of libSBML
Reading SBML
The SBMLDocument container
Writing SBML
Static methods for common reading and writing operations

This section summarizes how to read and write SBML content in Java using the facilities provided by the libSBML Java API.

## Getting started: the 1-minute introduction

LibSBML uses the class SBMLDocument as a top-level container for storing SBML content and data associated with it (such as warnings and error messages). Here is a simple example to start this discussion:

    import org.sbml.libsbml.SBMLReader;
    import org.sbml.libsbml.SBMLDocument;

    public class ReadSBML
    {
      public static void main (String[] args)
      {
        if (args.length != 1)
        {
          System.out.println("Usage: java readSBML filename");
          System.exit(1);
        }

        SBMLReader reader     = new SBMLReader();
        SBMLDocument document = reader.readSBML(args[0]);

        System.out.println("  filename: " + args[0]);
        System.out.println("  error(s): " + document.getNumErrors());

        if (document.getNumErrors() > 0)
        {
          document.printErrors();
          System.exit(1);
        }
      }

      static
      {
        try
        {
          System.loadLibrary("sbmlj");
          /* Extra check to be sure we have access to libSBML: */
          Class.forName("org.sbml.libsbml.libsbml");
        }
        catch (Exception e)
        {
          System.err.println("Error: could not load the libSBML library");
          System.exit(1);
        }
      }
    }

The code above illustrates probably the simplest possible use of libSBML: reading a model and printing any errors encountered. The code begins by importing two classes that are used in the program (SBMLDocument and SBMLReader). Next, after checking that it has been supplied with an argument at run-time, the program reads a file using the method readSBML, which returns an instance of an SBMLDocument object. A subsequent call to the getNumErrors() method on the returned object returns the number of errors encountered (if any), and the call to printErrors() prints them to the standard error output stream.

## Configuring your environment to use the Java version of libSBML

Dynamically loaded software libraries such as libSBML usually require some configuration steps in order to allow your computing environment to find the libraries when running applications that depend upon them. For the libSBML Java API, please make sure to read the subsections titled Accessing libSBML and Accessing libSBML from Java in the LibSBML Installation section of this manual. To summarize: you must make sure that your `CLASSPATH` environment variable includes the file `libsbmlj.jar`, and that your dynamic library search path variable includes the directory in which the `libsbmlj.so and libsbml.so` (Linux), `sbmlj.dll and libsbml.dll` (Windows), or `libsbmlj.jnilib and libsbml.dylib` (MacOSX) files are located.

As an example, if you are running under Linux and you configured libSBML with a prefix of `/usr/local` and did a normal "make install", and you are using the typical sh or bash shell in your terminal, you would need to execute

      export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"

or put the above in your shell's initialization file (`.bashrc` or `.profile` in your home directory) and cause the shell to re-read the initialization file. In addition, prior to running Java programs, you would need to either (1) set your `CLASSPATH` environment variable to include the `libsbmlj.jar` file, or (2) include the file in the `-classpath` option passed to the Java interpreter when it is started.

If you are running under MacOS instead of Linux, your sh or bash shell settings instead need to be

      export DYLD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"

## Reading SBML

SBML may be read from a file or from an in-memory character string using the methods provided by the class SBMLReader:

- `public SBMLDocument readSBML(java.lang.String filename)`. This function takes a file name, attempts to read an SBML document from the file, and returns a pointer to an SBMLDocument object if successful.
- `public SBMLDocument readSBMLFromString(java.lang.String xml)`. This function takes a string, attempts to read an SBML document from the string, and returns a pointer to an SBMLDocument object if successful.

The model may be either in SBML Level 1 or SBML Level 2 format. LibSBML implements an unified object model for SBML that encompasses both Level 1 and Level 2, so applications generally do not need to worry about differences in syntax between these definitions of SBML when reading and writing models. (However, applications still need to be concerned about the SBML constructs used and how they are interpreted, since there are substantial differences between SBML Level 1 and Level 2!)

## The SBMLDocument container

As might be deduced from the examples so far, an SBMLDocument object in libSBML represents a whole SBML model and its associated data. SBMLDocument corresponds roughly to the class Sbml defined in the SBML Level 2 specification, but it does not have a direct correspondence in SBML Level 1. (But, it is created by libSBML no matter whether the model is Level 1 or Level 2.)

SBMLDocument is derived from class SBase, so that it contains the usual SBase attributes (in SBML Level 2 Versions 3 and 4) of "metaid" and "sboTerm", as well as the subelements "notes" and "annotation". It also contains the attributes "level" and "version" indicating the Level and Version of the SBML document read. The class SBase (and thus its subclasses such as SBMLDocument) provides methods for querying this information:

- `public long getLevel()` returns the SBML Level of the model.
- `public long getVersion()` returns the SBML Version within the Level of the model.

Of course, the whole point of reading an SBML file or data stream is to get at the SBML model it contains. The following method allows access to the Model object within an SBML document:

- `public Model getModel()` returns a Model object for the SBML model contained in the SBMLDocument object.

SBMLDocument also acts to log any problems encountered while reading the model from the file or data stream. Whether the problems are warnings or errors, they are reported through a single common interface involving the object class SBMLError. The example earlier on this page already showed some of the methods available for accessing errors and warnings; here is a slightly more complete list:

- `public long getNumErrors()` returns a count of the diagnostic messages logged during while attempting to read an SBML model using either readSBML(java.lang.String filename) or readSBMLFromString(java.lang.String xml).
- `public SBMLError getError(long n)` returns a specific error indexed by the integer `n`. The SBMLError object class provides methods for assessing the severity of the problem encountered and for finding out the line and column number of where the problem occurred in the SBML input.
- `public void printErrors(org.sbml.libsbml.OStream stream)` prints all of the diagnostics to the given output stream. If the argument `stream` is omitted, it prints to the standard error output stream.

Finally, another set of SBMLDocument methods worth mentioning in the context of reading SBML are those for running consistency-checking and validation rules on the SBML content. These methods assess whether the SBML is legal according to basic rules listed in the SBML Level 2 Versions 2 through 4 specification documents. Note that they are mostly structural checks, in the sense that they can indicate whether the SBML is properly constructed; they cannot tell if a model is nonsense. (But at least they can assess whether it's syntactically correct nonsense!).

- `public long checkConsistency()` performs a set of structural and mathematical checks on the SBML content and reports the number of failed checks (errors) encountered. Callers may use the getNumErrors() and getError() interfaces to examine the individual errors.
- `public long checkL1Compatibility()` peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 1, and returns the number of failures. If all the checks succeed, it returns 0.
- `public long checkL2v1Compatibility()` peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 1, and returns the number of failures. If all the checks succeed, it returns 0.
- `public long checkL2v2Compatibility()` peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 2, and returns the number of failures. If all the checks succeed, it returns 0.
- `public long checkL2v3Compatibility()` peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 3, and returns the number of failures. If all the checks succeed, it returns 0.
- `public long checkL2v4Compatibility()` peforms a set of semantic consistency checks on the document to establish whether it can be converted to SBML Level 2 Version 4, and returns the number of failures. If all the checks succeed, it returns 0.

At the time of this libSBML release, the most recent release of SBML is Level 2 Version 4.

## Writing SBML

Writing SBML is, in the end, a very simple matter in libSBML. The library provides the SBMLWriter class with the following two functions for this purposes:

- `public boolean writeSBML(SBMLDocument d, java.lang.String filename)` writes the given SBML `d` to the file named `filename` and returns either `true` on success or `false` on failure. Reasons for failure can be, for example, that the named file could not be opened for writing.
- `public java.lang.string writeSBMLToString(SBMLDocument d)` writes the given SBML document `d` to a character string and returns a pointer to it, or throws an exception if a failure occurred.

## Static methods for common reading and writing operations

LibSBML provides a number of static methods in the class libsbml for reading and writing SBML content directly, by-passing the need to create SBMLReader and SBMLWriter objects. These methods are simply equivalents of the other methods described above:

- `public SBMLDocument readSBML(java.lang.String filename)`
- `public SBMLDocument readSBMLFromString(java.lang.String xml)`.
- `public boolean writeSBML(SBMLDocument d, java.lang.String filename)`
- `public java.lang.string writeSBMLToString(SBMLDocument d)`