libSBML
"5.12.0"

Accessing libSBML from Java software

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:

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);
    }
  }

}

libSBML
"5.12.0"


LibSBML "5.12.0", an application programming interface (API) library for SBML.