Editing Guide to madagascar API (section)

==Java Interface==
There are two interfaces to Java that are available.  New codes should be written to use the SWIG interface ONLY.  The older interface (using the MINES JTK) is deprecated, and is only provided while users migrate their code to the new interface.

===SWIG===

To install the SWIG interface:

1. Download the Java Standard Development Kit (JDK).  Installation varies by platform.

2. Create the JAVA_HOME environment variable for your shell.  This should point to the directory where the JDK was installed. Example (for Ubuntu 10.04):
<syntaxhighlight lang="bash">
export JAVA_HOME=/usr/lib/jvm/java-6-opensdk
</syntaxhighlight>

3. Reconfigure Madagascar:
<syntaxhighlight lang="bash">
./configure API=java
</syntaxhighlight>

4. Reinstall Madagascar (Ignore the compilation warnings for Java files):
<syntaxhighlight lang="bash">
scons; scons install
</syntaxhighlight>

The installation creates two files: <tt>$RSFROOT/lib/libjrsf.so</tt> and <tt>$RSFROOT/lib/rsf.jar</tt>.

Make sure that you set your LD_LIBRARY_PATH to include <tt>$RSFROOT/lib</tt>.

A short demonstration of the interface follows:

<syntaxhighlight lang="java">
import rsf.RSF;
import rsf.Input;
import rsf.Output;

/* A simple Java program to clip a dataset. */

public class Clip {
    static {
        System.loadLibrary("jrsf");
    }
    public static void main(String[] args){
        // Initialize command line argument passing
         RSF par = new RSF(args);
         // Get the input file name.
         Input input = new Input("in");
         Output output = new Output("out");
        // Get the value to clip to.
         float clip = par.getFloat("clip",0.0f);
        // Read our input header
        int n3 = input.getN(3);
        int n2 = input.getN(2);
        int n1 = input.getN(1);
        //Perform clipping operation on a single trace and write out.
        float[] data = new float[n1];
         for(int i = 0; i < n3; ++i){
            for(int j = 0; j < n2; ++j){
                input.read(data);
                for(int k = 0; k < n1; ++k){
                    if (data[k] > clip) data[k] = clip;
                    else if (data[k] < -clip) data[k] = -clip;
                }
                output.write(data);
            }
         }
         output.setN(1,n1);
         output.setN(2,n2);
         output.setN(3,n3);
         input.close();
         output.close();
    }
}
</syntaxhighlight>

There are only three classes in the interface:

1.'''RSF''' - The command line argument parser, and the initializer for the native interface.  An RSF object MUST be instantiated BEFORE instantiating an Input or Output object.

2. '''Input''' - An object that provides read access to an RSF file.  

3. '''Output''' - An object that provides write access to an RSF file.

Additionally, the shared library (libjrsf.so or libjrsf.dll) must be included via the System.loadLibrary("jrsf"); as the first command in the file.

To compile on the command line:
<syntaxhighlight lang="bash">
javac -cp $RSFROOT/lib Clip.java
</syntaxhighlight>

To include this as part of a SCons script (SConstruct):
<syntaxhighlight lang="python">
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500 l1=1000')
Flow('clipd','dat Clip.class',
    '''
    %s Clip clip=0.5
    ''' % WhereIs('java'))
Flow('test.attr','clipd','sfattr')
</syntaxhighlight>

Note, that we compile <tt>Clip.java</tt> using the SCons Java builder.  To execute the command, we have to locate the "java" command, which we do using <tt>WhereIs('java')</tt>.  Then we execute the class name, and pass any command line arguments as usual.  The files are read from standard in for this program and written to standard out.  

Please see the [[Library Reference]] for more details on the functions available in the SWIG API.

'''Note: Additional Java packages can included in SCons automatically by setting the CLASSPATH environment variable to point to the JAR files that they are contained in.'''

===Mines JTK===
'''THIS INTERFACE IS DEPRECATED AND ONLY PROVIDED AS A REFERENCE.  THIS INTERFACE IS NO LONGER SUPPORTED AND WILL BE REMOVED'''

This interface may still be compiled by specifying the MINESJTK environment variable. 

The interface to Java is less full featured than others.  Presently, it only allows you to read RSF files with fewer than 4-dimensions into Java, and then export RSF files.  '''The Java interface does not support reading from standard in, or writing from standard out.  Therefore, the Java Interface does not support piping either.''' The Java interface at present treats all values as floats, and does not have support for complex numbers.  Java programs are not parsed for self-doc information like other programs are either.  Using javadoc may be a viable alternative to creating a parsing engine for Java programs.

Once the build is complete, the JAR file rsf.jar will be added to your $RSFROOT/lib folder.  

There are two ways to access the API:

1. From the command line:  point the classpath at BOTH compile and runtime to this location on the command line.
<syntaxhighlight lang="bash">
javac -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test.java 
java -cp $MINESJTK:$RSFROOT/lib/rsf.jar:. Test arg1=... arg2=... arg3=...
</syntaxhighlight>

2. From within a SConstruct script:  BOTH the path for the API ($RSFROOT/lib) and the path to the Mines JTK ($MINESJTK) are automatically added to the environment variable CLASSPATH and JAVACLASSPATH for executions made within an SConstruct.  Additionally, any additional classes that are already in the CLASSPATH environmental variable in the shell that you launch from will be added to your classpath.  This allows you to include additional libraries automatically within your Java programs.  The local directory (.) is also included in the CLASSPATH.

<syntaxhighlight lang="python">
from rsf.proj import *

# Compiles Clip.class
project.Java('.','Clip.java')

Flow('dat',None,'spike n1=1000 n2=100 n3=10 nsp=1 k1=500')
Flow('clipd','Clip.class dat',
    '''
    %s ${SOURCES[0].filebase} clip=0.5 
    in=${SOURCES[1]} out=$TARGET 
    ''' % WhereIs('java'),stdin=0,stdout=-1)
Flow('test.attr','clipd','sfattr')

End()
</syntaxhighlight>

The interface itself is fairly straightforward.  More details on the methods exposed by the API can be found at the [[Library_Reference#Java_API | Library Reference]].

Data clipping, argument parsing, and IO example:

<syntaxhighlight lang="java">
import rsf.Par;
import rsf.Reader;
import rsf.Writer;
import rsf.Header;

/* A simple Java program to clip a dataset.

Presently, there is no automatic self-documentation generation for use
with sfdoc.  Javadoc may be a better way to generate self-doc for Java
programs.

*/

public class Clip {
    public static void main(String[] args){
        // Initialize command line argument passing
         Par par = new Par(args);
         // Get the input file name.
         String input = par.getString("in","");
         // If the input file name is nothing, then quit!
         if (input.equals("")){
                System.out.println("Did not find input file!");
                System.exit(1);
         }
         //If the output file name is nothing, then quit!
         String output = par.getString("out","");
         if (output.equals("")){
                System.out.println("Did not find output file!");
                System.exit(1);
         }
        // Get the value to clip to.
         float clip = par.getFloat("clip",0.0f);
        //Read our header file.
         Header header = Reader.readHeader(input);
        // Read our binary data.
         float[][][] data = Reader.readBinary3D(header);
        //Initialize our array values.
         int n3 = header.getN(3);
         int n2 = header.getN(2);
         int n1 = header.getN(1);
        //Perform clipping operation.
         for(int i = 0; i < n3; ++i){
            for(int j = 0; j < n2; ++j){
                for(int k = 0; k < n1; ++k){
                    float trace = data[i][j][k];
                    if (trace > clip) data[i][j][k] = clip;
                    else if (trace < -clip) data[i][j][k] = -clip;
                }
            }
         }
        //Write our data out, using the same header values to the file
        //located at: output.
         Writer.writeRSF(header,data,output);
    }
}
</syntaxhighlight>

How to read a file:

<syntaxhighlight lang="java">
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
      public static void main(String[] args){

                Header header = Reader.readHeader("junk.rsf"); //To read the header file, just feed in the path relative to the execution directory
                System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

                float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data
       }
}
</syntaxhighlight>

How to write a file:

<syntaxhighlight lang="java">
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
      public static void main(String[] args){
                
                Header header = Reader.readHeader("test.rsf"); //To read the header file, just feed in the path relative to the execution directory
                System.out.println(header); //The header file will print out if you ask it to, this is good for debugging

                float[][] data = Reader.readBinary2D(header); //Now I can manipulate my data

                //...Do something
                Writer.writeRSF(header,data,"test2.rsf"); //Write out my data!
       }
}
</syntaxhighlight>

If you want to create a dataset from scratch from within Java, then you can create an array of data, modify the values, create a header, and then write it out to rsf:

<syntaxhighlight lang="java">
import rsf.Header;
import rsf.Reader;
import rsf.Writer;

public class Test {
      public static void main(String[] args){

                int n1 = 20;
                int n2 = 40;
                float[][] data = new float[n2][n1]; 
                //The order for dimensions is reversed, because RSF stores them as column-major arrays (see Python API).

                //...Do something

                Header header = new Header();
                header.setN(1,n1);
                /* We set the values using the proper RSF number for the dimension, instead of the Java array index.
                   Example:  RSF Dimension 1, corresponds to array index 0 in Java.
                             However, we set the values using index 1.  The mapping is handled behind the scenes.
                 */
                header.setN(2,n2); 
                header.setDelta(1,0.0);
                header.setLabel(1,"time");
                header.setUnits(1,"s");
                Writer.writeRSF(header,data,"junk2.rsf"); //Write out my data!
       }
}
</syntaxhighlight>