The Java interface for libSBML is implemented partly as pure Java and partly as Java Native Interface (JNI) code. To use it in an application, additional steps must be taken after libSBML is installed on your computer.

#### Step 1: (maybe) set the run-time library search path

If you used the binary installers we provide for libSBML, or configured your system's library search path manually, applications should be able to find the libSBML library files at run time. If this is not the case, you can explicitly tell your Java interpreter where to find libSBML by setting the flag `-Djava.library.path` to the directory containing the libSBML library files. (This directory is the one containing the `.jnilib`, `.dylib` and/or `.dll` files for libSBML, depending on the operating system—not the JAR file.)

For example, suppose that you configured libSBML to be installed into `/usr/local` on a Linux system. Then, you could start your application using a command that begins as follows:

    java  -Djava.library.path=/usr/local/lib  -cp .:/usr/local/share/java/libsbmlj.jar  APPLICATION

If the library search path is not set correctly, applications will encounter a `java.lang.UnsatisfiedLinkError` at run time when they attempt to call `System.loadLibrary("sbmlj")` (discussed in Step 3 below). Here is an example of such an error message printed by the Java interpreter:

    Exception in thread "main" java.lang.UnsatisfiedLinkError: no libsbmlj in java.library.path
    	at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1764)
    	at java.lang.Runtime.loadLibrary0(Runtime.java:823)
    	at java.lang.System.loadLibrary(System.java:1044)
    	at test.(test.java:31)

#### Step 2: set your application's Java class search path

Java applications separately also need to have their class search paths set up such that they include the libSBML `.jar` file. This is often most easily done by setting the `CLASSPATH` environment variable, but other methods are possible. The exact recipe also depends on the operating system in use, as follows:

- Java on Linux, Mac OS X and similar Unix-like systems:

  You must either (1) set your `CLASSPATH` environment variable to include the `.jar` file, or (2) the libSBML `.jar` file must be listed in the `-classpath` option passed to the Java interpreter when it is started. As an example of the former approach, if you had configured libSBML to be installed into `/usr/local`, the `libsbmlj.jar` file will end up as `/usr/local/share/java/libsbmlj.jar` on Linux and Mac OS X and your environment variable would at minimum need to be set as follows:

        CLASSPATH=.:/usr/local/share/java/libsbmlj.jar

- Java on Windows systems:

  The instructions are essentially the same as for the case of Linux and similar systems, although the syntax for setting environment variables is slightly different. For example, if you had installed libSBML into `C:\libsbml` on your system, you might set your environment variable as follows:

        CLASSPATH=.;C:\libsbml\libsbmlj.jar

  Note: to set an environmental variable in Windows, use the System option in the Control Panel.

If the Java class search path is not set, then your application will encounter a `java.lang.ClassNotFoundException` error at run time when it first attempts to access a libSBML class. Here is an example of such an error message:

    Exception in thread "main" java.lang.NoClassDefFoundError: org/sbml/libsbml/XMLOutputStream
    	at test.main(test.java:15)
    Caused by: java.lang.ClassNotFoundException: org.sbml.libsbml.XMLOutputStream
    	at java.net.URLClassLoader$1.run(URLClassLoader.java:202)
    	at java.security.AccessController.doPrivileged(Native Method)
    	at java.net.URLClassLoader.findClass(URLClassLoader.java:190)
    	at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
    	at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301)
    	at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
    	... 1 more

#### Step 3: load the libSBML JNI library in the application

Finally, because of how JNI works in Java, an explicit call to `System.loadLibrary` is needed in an application to load the native language library portion of libSBML. This involves putting a Java `static` block of code somewhere in your application, usually in the application's main class. The following is an example of the minimum code for doing this:

    import org.sbml.libsbml.*;

    public class YourMainApplicationClass
    {
      public static void main (String[] args)
      {
        /* Whatever your application does here ... */
      }

      /**
       * The following static block is needed in order to load the
       * libSBML Java interface library when the application starts.
       */
      static
      {
          System.loadLibrary("sbmlj");
      }
    }

For real applications, it is often useful to catch run-time exceptions and try to interpret the causes on users' behalf. The following is a more elaborate example of code to load libSBML that tries to catch exceptions at run-time, interpret their meaning, and provide informative error messages about their causes. (Note that the following is an entirely optional replacement for the simpler version above.)

    import org.sbml.libsbml.*;
    public class YourMainApplicationClass
    {
      public static void main (String[] args)
      {
        /* Whatever your application does here ... */
      }

      /**
       * The following static block is needed in order to load the
       * libSBML Java interface library when the application starts.
       */
      static
      {
        try
        {
          System.loadLibrary("sbmlj");
          // For extra safety, check that the jar file is in the classpath.
          Class.forName("org.sbml.libsbml.libsbml");
        }
        catch (UnsatisfiedLinkError e)
        {
          System.err.println("Error encountered while attempting to load libSBML:");
          System.err.println("Please check the value of your "
                             + (System.getProperty("os.name").startsWith("Mac OS")
                                ? "DYLD_LIBRARY_PATH" : "LD_LIBRARY_PATH") +
                             " environment variable and/or your" +
                             " 'java.library.path' system property (depending on" +
                             " which one you are using) to make sure it list the" +
                             " directories needed to find the " +
                             System.mapLibraryName("sbmlj") + " library file and" +
                             " libraries it depends upon (e.g., the XML parser).");
          System.exit(1);
        }
        catch (ClassNotFoundException e)
        {
          System.err.println("Error: unable to load the file 'libsbmlj.jar'." +
                             " It is likely that your -classpath command line " +
                             " setting or your CLASSPATH environment variable " +
                             " do not include the file 'libsbmlj.jar'.");
          e.printStackTrace();

          System.exit(1);
        }
        catch (SecurityException e)
        {
          System.err.println("Error encountered while attempting to load libSBML:");
          e.printStackTrace();
          System.err.println("Could not load the libSBML library files due to a"+
                             " security exception.\n");
          System.exit(1);
        }
      }

    }