|
libSBML "5.15.2" |
||||||||
PREV NEXT | FRAMES NO FRAMES |
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.
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
.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)
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:
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
/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
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
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.15.2" |
||||||||
PREV NEXT | FRAMES NO FRAMES |