NEW PAGE

Linking C into Java

Notes on linking C into Java

Instructions on linking native C code on Linux JDK 1.0.1

• /homes/sep/matt/sdi/conv/tvdeconC We link a C convolution into our java framework to compare the efficiency of Java and C. For a pure Java version of the same code see /homes/sep/matt/sdi/conv/tvdeconC.
• /homes/sep/matt/jag/sep/io We link in a C conversion routine that accepts a float of arrays and converts it into an array of bytes. The array of bytes can be written to disk more efficiently then the original floats (bytes are written by buffer chunks unlike floats that are written individually). Since Java is strongly typed the conversion cannot be done in Java. The efficiency is especially important for Linux machines with their rather poorly designed NFS io.

• Include the following static method in the file myClass.java (which will contain native methods):

       static {
           System.load("/FullPathName/myObjectFile.so");
       }
  

  We probably want to use System.loadLibrary(), but I cannot get it to work. The path to the shared library file myObjectFile.so is often system dependend and I use following System call to figure it out:

        // If this throws an exception, we are probably non-local
        System.getProperty("java.home");
        // The following (commented out) seems to ALWAYS throw an exception
        //      System.getSecurityManager().checkPropertyAccess("java.home");
        String OpSys   = System.getProperty("os.name");
        // if local and Linux, load in a native routine to speed up write()
        if (OpSys.equals("Linux")) {
          local = true;
          //String libDir  = "/homes/sep/matt/jag/sep/io/";
          String libDir  = "/homes/sep/matt/jag/sep/";
          String libFile = "DataKeeper.so";
          System.load(libDir + OpSys + "/" + libFile);
        }
  

  I guess This can also be done in a try loop that chooses to execute an alternative java implementation if the system does not supply a the required C file:

  	try {
              System.loadLibrary("file");
          } catch (UnsatisfiedLinkError e) {
              System.err.println("can't find your library");
              // do here something an alternative equivalent? 
          }
  

• In the same class, you should declare which methods will be native:

       public native void myFirstNativeMethod(...);
       public native int  anotherNativeMethod(...);
  

  The methods have no body

• Compile myClass.java to myClass.class as usual (using javac).

• Create a C header file and a stubs file (Note, how the names of the created stub files mimics the package name with underscores instead of dots or slashes):

       method1> javah -classpath MyClassPath myPacakge.myClass
       method1> javah -classpath MyClassPath -stubs myPackage.myClass
       method1> ls myPackage_myClass.*
       myPackage_myClass.c myPackage_myClass.h
  

  Alternatively, use the rule in makefile.inc:

       method2> make myPackage.myClass.javah
  

• Write the C code using the function prototypes in myPackage\_myClass.h. These prototypes spell out the type names for the various arguments and return values. (besides the obvious arguments, javah generates a pointer to the calling object (the first argument). You can use it to reference the objects member variables from within the native method, even if these variables were not handed in as arguments. The H in front of the argument type names is for Handle).

  file: myCcode.c

       #include 
       #include "myPackage_myClass.h"
       /* Plus other #includes your code might need (e.g. stdio.h) */
  
  
       extern void myPackage_myFirstNativeMethod(...) {
             /* your useful code goes here */
       }
       
       extern int  myPackage_anotherNativeMethod(...) {
             /* your useful code goes here */
       }
  

  This example does not show any variables in the package arguments Don't forget to add the variable names to the argument lists in the function declarations. The proper naming conventions

• Create the "library" file (the following version is for the Linux machines:

       example> gcc -shared myPackage_myClass.c myCcode.c \
                    -I/usr/local/java/include             \
       		  -I/usr/local/java/include/solaris     \
       		  -o myObjectFile.so
  

• Now make sure that the environment variable, LD\_LIBRARY\_PATH is set to the directory where the library file, myObjectFile.so, resides. Actually, this step probably only matters if you somehow get System.loadLibrary() to work in the earlier step instead of System.load().