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:

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:

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: 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:

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!).

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:

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: