ahay/src/authoring-sf-programs-java

When to use

Choose the Java path when researchers bring an existing Java background or need access to Java scientific libraries (e.g., the Mines JTK) that have no C/Fortran equivalent. The file naming convention follows the same pattern as other language bindings: M<name>.java (e.g., MClip.java produces the program sfclip).

Note: Java support requires a JDK at configure time and the JAVA_HOME (or JAVA_SDK) environment variable set before running SCons. It is rarely used in practice — there are no M*.java programs in the main Madagascar tree. The files under api/java/ (Input.java, Output.java, etc.) are reference implementations and the test/Clip.java example demonstrates usage. Additionally, the Mines JTK (MINESJTK environment variable) is required for the older API layer under api/java/old/.

For the broader context of what an sf* program is, how self-documentation works, and general conventions that apply across all languages, see the shared skill: skills/authoring-sf-programs/.

Skeleton

A minimal Java program that reads a 3-D float dataset, processes it trace-by-trace, and writes the result. Based on the test/Clip.java reference implementation.

import rsf.RSF;
import rsf.Input;
import rsf.Output;
 
public class MExample {
    // Load the JNI bridge at class-load time
    static {
        System.loadLibrary("jrsf");
    }
 
    public static void main(String[] args) {
        // 1. Initialize the RSF parameter system with command-line args
        RSF par = new RSF(args);
 
        // 2. Open standard input and output RSF files
        Input  in  = new Input("in");
        Output out = new Output("out");
 
        // 3. Read header dimensions (1-based axis indexing)
        int n1 = in.getN(1);
        int n2 = in.getN(2);
        int n3 = in.getN(3);
 
        // 4. Copy axis metadata to output
        out.setN(1, n1);  out.setDelta(1, in.getDelta(1));
        out.setN(2, n2);  out.setOrigin(1, in.getOrigin(1));
        out.setN(3, n3);
 
        // 5. Parse a user parameter (with default fallback)
        float threshold = par.getFloat("threshold", 1.0f);
 
        // 6. Read, process, write one fast-axis slice at a time
        float[] trace = new float[n1];
        for (int i3 = 0; i3 < n3; i3++) {
            for (int i2 = 0; i2 < n2; i2++) {
                in.read(trace);
                // ... your processing here ...
                out.write(trace);
            }
        }
 
        // 7. Close files
        in.close();
        out.close();
    }
}

The static { System.loadLibrary("jrsf"); } block is mandatory — it loads the SWIG-generated JNI shared library (libjrsf.jnilib on macOS, jrsf.so on Linux) bridging Java to the underlying libdrsf C library.

API cheat sheet

RSF — parameter / initialisation (api/java/RSF.java)

RSFFile — header access (api/java/RSFFile.java)

Abstract base for Input and Output. All index arguments are 1-based.

Input — reading data (api/java/Input.java)

Extends RSFFile. Delegates to sf_floatread via the SWIG-generated m8r class.

Output — writing data (api/java/Output.java)

Extends RSFFile. Delegates to sf_floatwrite. Wraps all writes in try/catch (Exception e), printing to System.err on failure.

Error handling

Output and RSFFile accessors catch Exception, print to System.err, and return sensible defaults (0 / 0.0f / ""). No Java-level sf_error; fatal errors propagate from the C layer.

Build integration

The api/java/SConstruct file documents the full build process:

1. JDK detection — reads JAVA_HOME or JAVA_SDK from the SCons environment.

If neither is set the build exits immediately.

1. SWIG step — m8r.i is processed by SWIG with -java -package rsf to

produce m8r_wrap.c and the generated Java stubs (m8r.java, m8rJNI.java, m8rConstants.java, SWIGTYPE_p_sf_File.java, etc.).

1. JNI shared library — the wrap C file is compiled and linked against

libdrsf to produce libjrsf.jnilib (macOS) or jrsf.so (Linux).

1. Java compilation — javac compiles RSF.java, RSFFile.java,

Input.java, Output.java, and the generated stubs into rsf/*.class.

1. JAR packaging — rsf.class files are archived into rsf.jar and

installed to $RSFROOT/lib/.

For a user program there is no UserSconsTargets Java attribute in the SCons framework. User programs must replicate the compile-and-jar pattern manually or use the project.Java(...) helper demonstrated in api/java/test/SConstruct:

from rsf.proj import *
project.Java('.', 'MExample.java')
Flow('result', 'input MExample.class',
     '%s MExample threshold=0.5' % WhereIs('java'))
End()

The JVM must be able to locate both rsf.jar and the JNI library at runtime. Set CLASSPATH and java.library.path (or LD_LIBRARY_PATH / DYLD_LIBRARY_PATH) to point at $RSFROOT/lib/.

Pointers

All files under api/java/:

Shared conventions

Self-documentation, program naming (sf* / M*.java), data-type conventions, axis ordering (n1 is the fast axis), and the overall SCons flow are shared across all Madagascar language bindings. See:

skills/authoring-sf-programs/