ISB Logo

ISBJava User Manual

CompBio Group, Institute for Systems Biology

Stephen Ramsey (sramsey at systemsbiology.org)

Group Logo

Contents

  1. Introduction
  2. Requirements
  3. Acknowledgements
  4. External Libraries
  5. Naming Conventions
  6. Using the library
  7. API Documentation
  8. Source Code
  9. Frequently asked Questions
  10. Getting Help

Introduction

The ISBJava project is a library (collection) of classes written in the Java programming language, that are intended to be used for research in computational biology.

This document is the user manual for the ISBJava library. This manual applies to the following release version of the library:

release version:   2.4.4
release date:      2006/09/28
The release notes for this version of the library can be found at the following URL:
http://magnet.systemsbiology.net/software/ISBJava/docs/ReadMe.html
The home page for this library is:
http://magnet.systemsbiology.net/software/ISBJava
The version history for this library can be found at the following URL:
http://magnet.systemsbiology.net/software/ISBJava/docs/VersionHistory.html
If you are reading this document through a print-out, you can find the online version of this document (which may be a more recent version) at the following URL:
http://magnet.systemsbiology.net/software/ISBJava/docs/UserManual.html

Requirements

You will need the Sun Java Development Kit (JDK) vesrion 1.4 or newer (or the equivalent) in order to use these classes. Some of the packages in this source directory tree require external Java packages/libraries to be installed. In order to compile the ISBJava library, you will need to have all of these external libraries listed in your CLASSPATH environment variable. Some of the external libraries are needed only in order to compile specific sub-packages of the ISBJava source tree; see the external libraries section of this manual for details.

The classes in this library have been tested on the Sun JDK v1.4.1, on the Red Hat Linux 8.0 platform and on Windows XP. On other platforms, your mileage may vary.

Ant is required to use the "build.xml" file in this directory. You can download and install Ant from the apache Ant project.

Acknowledgements

The initial version of ISBJava was implemented by Stephen Ramsey. The assistance, advice, and contributions of several individuals to the ISBJava project is gratefully acknowledged: Hamid Bolouri (Principal Investigator), William Longabaugh, and Alistair Rust.

The development of ISBJava is supported in part by grant #10830302 from the National Institute of Allergy and Infectious Disease (NIAID), a division of the National Institutes of Health (NIH).

External Libraries

The ISBJava system has various external library dependencies, that are documented in this section. All of the external libraries (excepting those that are included by default in the JDK) are included with the installation of ISBJava, in a subdirectory "extlib". Please make sure to use these libraries in order to compile the ISBJava.jar library from source code. Some of these external libraries have changed in recent versions, in such a way that they are no longer compatible with the source code in ISBJava. Where this is known to be the case, it is noted below.

The following table documents the external library dependencies of the ISBJava system. The libraries are provided in a compiled format called a "JAR archive". Some of the libraries have software licenses that require making the source code available, namely, the GNU Lesser General Public License (LGPL). For each of those licenses, a hyperlink is provided to a compressed archive file containing the source code for the version of the library that is included with ISBJava. These hyperlinks are shown in the "Source" column below.

Package name JAR name Home Page / Documentation License Version Source Code
jfreechart jfreechart.jar http://www.jfree.org/jfreechart/ LGPL 0.9.6 full
jcommon jcommon.jar http://www.jfree.org/jcommon/ LGPL 0.7.2 full
SBW (core) SBWCore.jar http://sbw.kgi.edu BSD 2.5.0 see SBW web site
Netx JNLP client netx.jar http://jnlp.sourceforge.net/netx LGPL 0.5 full
JavaHelp jh.jar http://java.sun.com/products/javahelp Sun Binary Code License 1.1.3 partial
JAMA Jama.jar http://math.nist.gov/javanumerics/jama public domain 1.0.1 full
colt colt.jar http://hoscheck.home.cern.ch/hoscheck/colt open source (see below) 1.0.3 full
odeToJava odeToJava.jar http://www.cs.dal.ca/~spiteri/students/mpatterson_bcs_thesis.ps (customized version -- see note below) public domain alpha.2.p1 full
SBMLReader SBMLReader.jar (customized and abridged version of the SBMLValidate library by Herbert Sauro and the SBW Project team) LGPL 1.0 full
Cytoscape cytoscape.jar http://www.cytoscape.org LGPL 1.1.1 see the Cytoscape Project Home Page

Please note that the SBMLReader.jar library is a modified version of the SBML-parsing code originally contained in the program SBMLValidate.jar. The package name has been changed also. This was done in order to minimize the potential for conflict in cases where the target installation computer already has an installation of SBMLValidate.jar from the Systems Biology Workbench (SBW).

The SBWCore.jar library distribution contains three external libraries: gnu-regexp, grace, and java_cup. For information about these libraries and to obtain the source code, please consult the various README.txt files within the subdirectories of the sbw-1.0.5/src/imported directory of the source archive for the SBWCore library, obtained at the link given above.

The odeToJava library is copyright Raymond Spiteri and Murray Patterson. It is provided with kind permission from Raymond Spiteri (Dalhousie University, Halifax, NS, Canada). The odeToJava library is not distributed in its original form with ISBJava. It has been modified from the version that is available from Netlib. Please use the odeToJava.jar library that is bundled with ISBJava, as it contains some features that are necessary in order to function correctly with ISBJava. The Netlib version of odeToJava is no longer compatible with ISBJava, without some slight modifications to the source code.

The jfreechart and jcommon libraries are used by ISBJava in order to generate graphical plots of simulation results. Please note that the public API for these libraries has changed in recent versions, in a non-backwards-compatible manner. It is necessary to use the (older) versions of these libraries (referenced above), that are provided with the ISBJava installation. If you download the latest version of the jfreechart and jcommon libraries from the JFree.org web site, they will not be compatible with ISBJava.

The Colt library is provided under the following license terms:

Copyright (c) 1999 CERN - European Organization for Nuclear Research.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose
is hereby granted without fee, provided that the above copyright notice appear in all copies and
that both that copyright notice and this permission notice appear in supporting
documentation.
CERN makes no representations about the suitability of this software for any purpose.
It is provided "as is" without expressed or implied warranty.

ISBJava depends on the Cytoscape program through the Java Network Launching Protocol (JNLP), which means that the Cytoscape program is not distributed with ISBJava. Instead, the Cytoscape program is loaded at run-time over the network, only when an application function is performed that depends on the Cytoscape program.

Note that the SBWCore library is only required for compiling the code in the "org.systemsbiology.chem.sbw" package. By omitting the org/systemsbiology/chem/sbw directory from the compilation (by adding a suitable "exclude" statement to the "javac" statements in the build.xml file), in principle the resulting ISBJava.jar file that would be built, would not have any dependencies on the aforementioned SBW libraries.

The jfreechart and jcommon libraries are needed in order to compile the org.systemsbiology.chem.app package. They are not needed for any other packages in the ISBJava library.

The SBMLReader.jar library is only required for compiling the code in the "org.systemsbiology.chem.app" and "org.systemsbiology.chem.sbml" packages. By omitting the org/systemsbiology/chem/sbml and the org.systemsbiology/chem/app directories from the the compilation (by adding suitable "exclude" statements to the build.xml file), in principle the resulting ISBJava.jar file that would be built, would not have any dependencies on the SBMLReader.jar library. However, the GUI application front-end to the "org.systemsbiology.chem" simulation package would not be available.

The odeToJava library is only required for compiling the code in the "org.systemsbiology.chem.odetojava" package. By omitting the org/systemsbiology/chem/odetojava directory from the the compilation (by adding a suitable "exclude" statement to the build.xml file), in principle the resulting ISBJava.jar file that would be built, would not have any dependencies on the odeToJava library.

Naming Conventions

A few notes about conventions used these java packages. The ".tp" suffix at the end of a package name indicates that the ".tp" subpackage contains test programs for the parent package. Similarly, a suffix ".t" at the end of a package name indicates that the ".t" subpackage contains unit tests for the parent package (in the JUnit framework).

These classes are all in development, and are subject to change at any time, without notice. All classes contained herein should be considered copyright of the Institute for Systems Biology, 2003.

Using the library

In order to use this library, you will need to download and run the installer available on the ISBJava home page. When you run the installer, you will be prompted to specify an installation directory.

The documentation will be stored in a subdirectory "docs" of the installation directory. Note that the Javadoc documentation is not provided by the installer, but you can generate it using the "javadoc" program available from the Sun Java Development Kit (JDK). You can also browse the Javadoc API for ISBJava on the web.

The compiled Java code for the library is contained in the file "ISBJava.jar", which is stored in the "lib" subdirectory of the installation directory. In order to be able to use this library in your Java programs, you will need to ensure that the aforementioned JAR file (ISBJava.jar) is added to your Java CLASSPATH. This can be done by modifying (or defining) the CLASSPATH environment variable, or it can be done by passing the "-cp" argument to the "javac" and "java" commands when compiling and running your program, respectively.

API Documentation

For technical reasons, the API documentation has been separated from the User Manual for the ISBJava library. The API documentation is available on-line at:

http://magnet.systemsbiology.net/software/ISBJava/javadoc
There is also a PDF version available at:
http://magnet.systemsbiology.net/software/ISBJava/docs/APIDocumentation.pdf
Please note that the PDF documentation is generated using an experimental Javadoc-to-PDF translater, so there are some glitches in the formatting of the PDF. At this time, the HTML Javadoc is the more readable format and has the more comprehensive network of hyperlinks.

Source Code

The source code for the ISBJava library is included with the library installer. You can find the code in the file "ISBJava-src.tar.gz" that is installed in the "src" subdirectory of the installation directory for this program.

Frequently asked Questions

I am unable to compile the source code because of the asserts. What is causing this problem?

When you run javac to compile the source code, make sure you use "-source 1.4", to enable parsing of Java 1.4 language constructs.

Getting Help

If you find that the ISBJava library does not function in accordance with the descriptions in this manual, or if there are sections of this manual that are incorrect or unclear, the authors would like to hear about it, so that we can make improvements and fix bugs in the software. Furthermore, the authors would appreciate feedback regarding new features or improvements that would be useful to users of this software. Before e-mailing the authors, it is a good idea to check the ISBJava application home page to see if a new version has been released, in which your specific problem may have been corrected. All releases are documented in the "version history" page accessible from the home page. The best way to contact the authors is to send e-mail to:

isbjava NOSPAM at NOSPAM systemsbiology.org.
The authors will attempt to respond to your e-mail as quickly as possible.

If you are reporting a bug, or something that you suspect is a bug, please provide as much information as you can about your specific installation of the ISBJava library. In particular, please provide us with the version number of the ISBJava library that you are using, the type and version number of the Java Runtime Environment that you are using (e.g., Sun JRE version 1.4.1), and your operating system type and verion (e.g., Red Hat Linux 8.0). Furthermore, if the problem is with a specific Java program using the library, please send us the source code of the complete program that generates the problem. Note that some effort to localize the problem to a reproducible test case with a small program, will help us significantly in fixing the problem that you are encountering. If the problem that you encountered generated a "stack backtrace" on the console, please include the full stack backtrace text in your bug report. Please also send us the text of any error message that you may have been reported by the library, in a dialog box or on the console. Providing this information will dramatically increase the likelihood that the authors will be able to quickly and successfully resolve the problem that you are encountering.


Last updated: 2006/01/30 20:19:24

Please e-mail comments or corrections regarding this document to: isbjava NOSPAM at NOSPAM systemsbiology.org