• Reading the libSBML version from the JAR file
• Using libSBML from within Apache Tomcat

This section discusses special topics that are unique to the Java language interface implemented in libSBML.

## Reading the libSBML version from the JAR file

Beginning with libSBML version 4.3, the JAR file containing the optional Java language bindings for libSBML incorporates the libSBML version number. This allows applications and other software to query the version number of a libSBML JAR file without actually having to invoke libSBML. A complete demonstration program illustrating how to do this is provided with the libSBML source code distribution in the file `"examples/src/printLibSBMLVersion.java"`; the essential portion is illustrated in the following code fragment:

    Package p = Package.getPackage("org.sbml.libsbml");
    if (p != null)
    {
      System.out.println("Package name: " + p.getImplementationTitle());
      System.out.println("Package version: " + p.getImplementationVersion());
    }
    else
    {
      System.err.println("Unable to get package org.sbml.libsbml");
    }

A program simply needs to load the libSBML JAR file in some manner, and then use the standard Java `Package` class methods to extract the name and version number.

Note, however, that this approach will only work with libSBML version 4.3 or later, because in prior versions, libSBML did not include the relevant fields in the JAR manifest.

## Using libSBML from within Apache Tomcat

The following instructions explain how to set up libSBML to work inside a web application running in Apache Tomcat. This procedure has been tested with Tomcat versions 6.0.29 and 7.0.5 on Windows 7 (64-bit), Fedora Core 14 (Linux, 64-bit) and Mac OS X 10.6.5.

In the instructions that follow, we assume you have already installed Tomcat on your system or otherwise have a working Tomcat installation. Let the placeholder TOMCAT stand for the root of the Apache Tomcat installation directory on your system.

### Setup step 1: Add the libSBML libraries to Tomcat

First, you need to add the libSBML Java bindings files to Tomcat's library directory. (Prior to doing this, you will of course need to have built and installed libSBML with the Java bindings enabled, as described in a separate section of this manual.)

In the table below, for Linux and Mac OS X, let the placeholder PREFIX stand for the directory where you installed libSBML (i.e., the value you used with `configure --prefix=PREFIX`, typically `"/usr/local"`). For Windows, let the placeholder LIBSBML-VERSION stand for the name of the particular libSBML installation you have downloaded and installed in the folder `C:\Program Files\SBML\` on your system. (For example, for the 64-bit binary installation of libSBML version 4.2.0, this folder would by default be `C:\Program Files\SBML\libsbml-4.2.0-libxml2-x64`. The same instructions will work for the 32-bit version by simply substituting `x86` for the `x64`.)

System | Files to copy
--- | ---
Linux | PREFIX`/lib/libsbmlj.so` PREFIX`/share/libsbmlj.jar` (Suggestion: use the Linux system command `ldd` to verify that the libraries upon which `libsbmlj.so` depends can be found on your system. A command such as "`ldd` PREFIX`/lib/libsbmlj.so`" should not report any missing libraries.)
Mac OS X | PREFIX`/lib/libsbmlj.jnilib` PREFIX`/share/libsbmlj.jar` (Suggestion: use the Mac OS system command `otool` to verify that the libraries upon which `libsbmlj.so` depends can be found on your system. A command such as "`otool -L` PREFIX`/lib/libsbmlj.so`" should not report any missing libraries.)
Windows | `C:\Program Files\SBML\LIBSBML-VERSION\bindings\java\libsbmlj.jar` `C:\Program Files\SBML\LIBSBML-VERSION\bindings\java\sbmlj.dll` `C:\Program Files\SBML\LIBSBML-VERSION\win64\bin\*.dll`
Copy the indicated files into the directory TOMCAT`/lib/` on your system.

### Setup step 2: Make the libraries accessible to Tomcat

The next step is to ensure that the libraries can be found by Tomcat. A simple way to achieve this is to make use of a standard feature in Tomcat: it automatically looks for and runs a script file named `setenv.sh` (on Linux and Mac OS) or `setenv.bat` (on Windows) if it exists in the Tomcat `bin` directory. You can use this script file to set environment variables that influence Tomcat's behavior, and for our purposes, we can set certain variables that let Tomcat find the libSBML dynamically-loaded libraries.

The following table shows the contents of the shell script for different programming systems. We provide the entire contents of the file here, under the assumption that your Tomcat installation does not already have such a file. If your Tomcat does have this file already, then only add the line setting the environment variable.

System | File name | Contents of the shell script
--- | --- | ---
Linux | `setenv.sh` |
    #!/bin/bash

    echo "Setting LD_LIBRARY_PATH"
    export LD_LIBRARY_PATH=TOMCAT/lib:$LD_LIBRARY_PATH
Mac OS X | `setenv.sh` |
    #!/bin/bash

    echo "Setting DYLD_LIBRARY_PATH"
    export DYLD_LIBRARY_PATH=TOMCAT/lib:$DYLD_LIBRARY_PATH
Windows | `setenv.bat` |
    set PATH=TOMCAT/lib:%PATH%
Place the indicated content into the named file located in the directory TOMCAT`/bin/` on your system.

### Setup step 3: Write an initializer for loading the native libSBML library

An initializer class is needed in order to load the native library portion of libSBML. Using a separate initializer avoids the problem of trying to call Java's `System.loadLibrary()` method from servlets and JSP pages—which Java does not allow.

A simple example of an initializer program is listed below. The example uses the package `mypackage` for illustration purposes only; you would subsitute whatever makes sense for your particular application. Also, the specific actions taken by `Initialize()` here is not important, so you could replace it with other code that makes sense for your application. In the next section, we will show the `Initialize()` method is called.

    package mypackage;
    import org.sbml.libsbml.libsbml;   // The repeated "libsbml" is not a typo.

    public class Initializer
    {
        static
        {
            System.loadLibrary("sbmlj");
        }

        public static void Initialize()
        {
             System.out.println("Initialized!");
    	 System.out.println("Using LibSBML: " + libsbml.getLibSBMLDottedVersion());
        }
    }

Save the contents above in a file called `"Initializer.java"`, compile it, and save the resulting `.class` file to a subdirectory of the Tomcat `/lib` directory named after the package name. In other words, for the example code above, this would be TOMCAT`/lib/mypackage/Initialize.class`.

That's all that is needed to set up your Tomcat to use libSBML in JSP pages and servlets. In the next two sections, we provide examples of how to access libSBML in practice.

### Using libSBML in JSP pages

Your JSP application must call the initialization method (i.e., `Initialize()` in the code example above) once; after that, the JSP pages can freel access libSBML methods. Perhaps the best way of invoking `Initialize()` once is by calling it from the `jspInit()` method. We illustrate this using an example JSP page listed below:

    <%@ page language="java" contentType="text/html; charset=ISO-8859-1"
        pageEncoding="ISO-8859-1" import="org.sbml.libsbml.*" import="mypackage.*"%>

    <%!
    public void jspInit()
    {
        Initializer.Initialize();
    }
    %>

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
    <html>
    <head>
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    <title>Insert title here</title>
    </head>
    <body>
       <%= new String("Hello!") %>
       <%= new String(libsbml.getLibSBMLDottedVersion()) %>
    </body>
    </html>

To test it, following these steps:

- Create a directory in TOMCAT`/webapps`. For the purposes of the rest of this discussion, we will call this directory WebContent, but you can name it anything you wish (well, anything that's a legal directory name on your operating system).
- Save the file contents listed above in WebContent as some file with a `.jsp` extension. For purposes of the rest of this discussion, we will call this file hellojsp.jsp.
- Start Tomcat. For purposes of this discussion, we assume that your Tomcat instance is running on your local host computer, and that it is listening to port 8080.
- Navigate a web browser to the URL `http://localhost:8080/`WebContent`/`hellojsp.jsp.

You should see the string "Hello!" printed along with libSBML's version number. The screenshot shown below illustrates this.

Screenshot of the simple JSP page calling a libSBML method.

### Using libSBML in servelets

It is also possible to use libSBML in servlets served by Tomcat. The following listing gives an example of doing this.

    package mypackage;

    import java.io.IOException;
    import javax.servlet.ServletException;
    import javax.servlet.annotation.WebServlet;
    import javax.servlet.http.HttpServlet;
    import javax.servlet.http.HttpServletRequest;
    import javax.servlet.http.HttpServletResponse;

    import org.sbml.libsbml.*;

    /**
     * Servlet implementation class Hello
     */
    @WebServlet(description = "test program testing libsbml", urlPatterns = { "/Hello" })
    public class Hello extends HttpServlet
    {
        private static final long serialVersionUID = 1L;

        /**
         * @see HttpServlet#HttpServlet()
         */
        public Hello()
        {
            super();
            Initializer.Initialize();  // Call the libSBML initializer.
        }

        /**
         * @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse response)
         */
        protected void doGet(HttpServletRequest request, HttpServletResponse response)
        	throws ServletException, IOException
        {
        	handleRequest(request, response);
        }

        private void handleRequest(HttpServletRequest request,
            HttpServletResponse response) throws IOException
        {
            response.getOutputStream().println("Hello from servlet!");
            response.getOutputStream().println("Using libsbml version: " +
        	libsbml.getLibSBMLDottedVersion());
        }

        /**
         * @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse response)
         */
        protected void doPost(HttpServletRequest request, HttpServletResponse response)
        	throws ServletException, IOException
        {
        	handleRequest(request, response);
        }
    }