Editing Guide to madagascar API (section)

===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.'''