file: README		I. Henry and G. Moody	 August 2005
			Last revised:         20 August 2010

Name: wfdb-java -- WFDB wrappers for Java

Purpose:

The WFDB library (http://physionet.org/physiotools/wfdb.shtml) provides uniform
access to digitized signals and annotations in a wide variety of formats,
including those in PhysioBank (http://physionet.org/physiobank/).  The WFDB
library is written in C and includes bindings for C++ and wrappers for Fortran.

This package provides an interface that allows use of the WFDB library
functions from Java programs.  The wrappers are suitable for use by Java
applications, but cannot be used with applets because they require
platform-specific code.

Authors:

Isaac Henry (ihenry@physionet.org), George Moody (george@physionet.org)

Background literature:

The SWIG web site (http://www.swig.org/)
The WFDB Programmer's Guide (http://www.physionet.org/physiotools/wpg/)

Platforms:

GNU/Linux, Mac OS X, MS Windows. Other platforms supported by SWIG should 
also work but have not been tested.

Code organization:

This is a subpackage of wfdb-swig (see ../README).  The file named Makefile
invokes 'make' to copy the contents of 'conf' to 'build',  to generate
wrapper sources usig SWIG, and to create a customized 'Makefile' to manage
the build and installation processes (see INSTALL).  The wrappers
themselves are generated by SWIG from ../wfdb.i (although javadoc.i is
referenced by the build process, SWIG currently makes no use of it;  in a
future release of SWIG, javadoc documentation will be automatically generated
from javadoc.i).

URLs:
   code:
	http://code.google.com/p/wfdb-swig/source/browse/#svn/trunk/wfdb-java
	http://code.google.com/p/wfdb-swig/source/browse/trunk/wfdb.i
   test scripts and data:
	http://physionet.org/wfdb-swig/examples/*.java
	http://physionet.org/wfdb-swig/wfdb-java/examples/
   docs:
	The WFDB Programmer's Guide (http://physionet.org/physiotools/wpg/);
	also see the notes below

Installation and testing:

See INSTALL, in this directory.

_______________________________________________________________________

A Trivial Example Program in Java

This program is a translation to Perl of Example 2 from the WFDB Programmer's
Guide (http://physionet.org/physiotools/wpg/).  It translates the `atr'
annotations for the record named in its argument into an AHA-format annotation
file with the annotator name `aha'.


import java.io.*;
import wfdb.*;

public class example2 {
    
    public static void main(String argv[]) {
		
	    WFDB_AnninfoArray an = new WFDB_AnninfoArray(2);
	    WFDB_Annotation annot = new WFDB_Annotation();

	    if (argv.length < 1) {
		    System.out.println("usage: " + "fixme" + " record");
		    System.exit(1);
	    }
	    WFDB_Anninfo a = an.getitem(0);
	    a.setName("atr"); a.setStat(wfdb.WFDB_READ);
	    an.setitem(0, a);
	    a = an.getitem(1);
	    a.setName("aha"); a.setStat(wfdb.WFDB_AHA_WRITE);
	    an.setitem(1, a);
	    if (wfdb.annopen(argv[0], an.cast(), 2) < 0) System.exit(2);
	    while (wfdb.getann(0, annot) == 0 && wfdb.putann(0, annot) == 0)
		    ;
	    wfdb.wfdbquit();
    }
}

The functions used in this example are described in detail in the WFDB
Programmer's Guide; all are methods of the "wfdb" class.  For now, note that
wfdb.annopen prepares a record to read by wfdb.getann, which reads an
annotation each time it is called.  Note that WFDB constants are also members
of the "wfdb" class.

The WFDB data types are described in the WFDB Programmer's Guide. In Java, each
WFDB structure is paired with an accessor class that allows you to work with
pointers to the native C structures in memory.  These classes are often
refereed to as "shadow classes".  Elements of WFDB C structures are accessed
with set/get methods of the shadow class. For example, a.setName("atr") sets
the 'name' member for C structure the Java class is wrapping.

In addition, there are several 'Array' special classes, which are used in place
of pointer arrays in C.  Note that the 'cast' method must be used when passing
an 'Array' object to a method, as in

  wfdb.annopen(argv[0], an.cast(), 2)

The items in the 'Array' object can be accessed using the 'getitem' and
'setitem' methods.  Special care must be taken when manipulating the members of
an array. As shown in the example, you must first obtain a shadow class object
for an item using 'getitem',

  WFDB_Anninfo a = an.getitem(0);

which can then be used to get or set structure members. 

  a.setName("atr"); a.setStat(wfdb.WFDB_READ);

Take special note that you must use 'setitem' to copy your changes back to the
array.

  an.setitem(0, a);

This may seem unintuitive, but remember that the Array classes only manipulate
underlying C structures.

A copy of this program is available as ../examples/example2.java.
To compile it, type
	make examples

The ../examples directory also contains translations into Java of the other
examples from the WFDB Programmer's Guide.


Compiling a Java Program with the WFDB Library

The WFDB classes are contained in the wfdb.jar file. To compile an
application on from the commandline, we can say:

   javac -classpath /usr/share/java/wfdb.jar:. someapp.java

to produce an executable class called someapp.class. You may use any
other compiler options you choose, but you must include the full path
of the wfdb.jar file int your classpasth.

Alternatively, you may compile a Java application into a fully compiled
binary, using GNU gcj:

   gcj -fjni -I/usr/share/java/wfdb.jar --main=someapp \
        /usr/share/java/wfdb.jar someapp

Two points to keep in mind if you try this:

 * The full pathname of the wfdb.jar file must be listed twice as shown.
 * Although gcj accepts a -o option to specify the name of the output file,
   this option cannot be used when there is more than one source file
   (as will be true when compiling anything else together with wfdb.jar).
   The default output is named 'a.out';  you will probably want to rename
   it, like this:
	mv a.out someapp


Running a Java Program with the WFDB Library

To run a WFDB Java .class file on a Linux system, we can say:

   java -cp /usr/share/java/wfdb.jar:. -Djava.library.path=/usr/lib someapp

You must include the full path to the wfdb.jar file in your classpath, and you
must specify the path to the JNI "glue" library in your java.library.path.
The shell script 'jw' (in the 'examples' directory) does this;  if you use
WFDB Java applications frequently, you may wish to copy it into a directory in
your PATH, such as /usr/local/bin.  In this case, you will be able to run the
class by typing:

   jw someapp

If you have used gcj to obtain a fully compiled application, you may run
it just as you would any other program, by typing its name at the command line.
(If the program is not located in a directory that is in your PATH, type its
absolute or relative pathname to run it.)