![]() |
ISBJava User ManualCompBio Group, Institute for Systems BiologyStephen Ramsey (sramsey at systemsbiology.org) |
![]() |
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:
The release notes for this version of the library can be found at the following URL:release version: 2.4.4 release date: 2006/09/28
http://magnet.systemsbiology.net/software/ISBJava/docs/ReadMe.htmlThe home page for this library is:
http://magnet.systemsbiology.net/software/ISBJavaThe version history for this library can be found at the following URL:
http://magnet.systemsbiology.net/software/ISBJava/docs/VersionHistory.htmlIf 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
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.
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).
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 theSBWCore
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.
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.
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/javadocThere is also a PDF version available at:
http://magnet.systemsbiology.net/software/ISBJava/docs/APIDocumentation.pdfPlease 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.
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.
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.
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 at 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 at systemsbiology.org