Using JBI

Native methods that use the Jamaica Binary Interface are equal to native methods that use JNI from the point of view of the Java code. JBI native methods need to be marked using the native keyword. An example is given here.

      
public class Test {

  public static native int example(int i);

  public static void main(String[] args) {
    System.out.println(example(args.length));
  }
}
      
    

The include file that is normally generated by jamaicah or javah for a JNI method cannot be used for code that uses JBI. A specific include file nees to be generated using jamaicah -jbi as follows:

      
> javac Test.java
> jamaicah -jbi Test
 + Test.h
      
    

The name mangling for JBI methods is the same as the name mangling used for JNI methods, with the only exception that the name of the C routine starts with Jam_ instead of Java_. The arguments of JBI functions always uses a reference to the current thread (of type jamaica_thread *) as the first argument. For static methods, the following arguments directly correspond to the arguments of the Java declaration (there is no additional argument for the class as in JNI), while for instance methods, the second argument is always a reference to the current instance this.

The resulting include file Test.h looks as follows.

      
/* DO NOT EDIT THIS FILE - it was generated by jamaicah:
   -jbi Test
*/

#ifndef _INCLUDED_TEST_
#define _INCLUDED_TEST_

#include "jbi.h"

#ifdef __cplusplus
extern "C" {
#endif


/* Class:     Test
 * Method:    example
 * Signature: (I)I */
extern jamaica_int32 Jam_Test_example(jamaica_thread *currentThread, jamaica_int32 arg0);


#ifdef __cplusplus
}
#endif

#endif /* _INCLUDED_TEST_ */

/* end of file */
      
    

A simple implementation of this native routine could calcluate the square of the integer argument as follows.

      
#include "Test.h"

jamaica_int32 Jam_Test_example(
    jamaica_thread *currentThread, 
    jamaica_int32 arg0) {
  return arg0*arg0;
}
      
    

To build an application that uses JBI code, the Jamaica builder needs to be instructed which classes contain native methods that use JBI instead of JNI. To distinguish JBI from JNI methods, the builder requires access to the include files generated by jamaicah for all classes that contain native code. The builder parses these include files and decides from their contents whether a class uses JNI or JBI.

For the builder to be able to locate all include files generated by jamaicah, it needs to be informed about the paths that contain include files. This information has to be provided via the option -include. Typically, you do not want to override the setting of the include path of the standard classes that use native code. So, all that is required is the addition of new paths for your application via -include+=<path>, as in the following example. In addition to the include path, the class path and the object file containing the native code is also provided .

      
> jamaica Test -classpath classes -include+=./include 
    -object obj/Test.o