of School Computer Science & Engineering -- UNSW
http://www.cse.unsw.edu.au/
Objectives of this presentation
To explain the purpose of the Java Native Interface (JNI). To outline a procedure for producing a JNI for the C code produced by the B
An Introduction to the B Method Using Native C Code with Java The Java Native Interface
2nd October 2001
c Ken Robinson 2000, 2001
Toolkit.
To give a small demonstration of an embedding of the native C code in a simple
Java interface.
mailto::[e-mail]
1/39
?
i
P
2/39
?
i
P
Embedding Native C code in Java
As with many programming languages it is possible to embed native C code into a Java program and use the C functions as Java methods. However, native C functions will not normally match the C functions corresponding to Java methods. The following slide illustrates the mismatch for the the implementation of
The Java/Native Code Mismatch
response
< --
BorrowBook(user,book)
C
void BorrowBook(int
response,int user,int book)
Mismatch
BorrowBook MainLibraryAPI. BorrowBook
operation from
The top half of the slide shows the B operation into C.
and its translation
The bottom half of the slide shows a possible representation of that operation as a Java method and its translation into C. There is a mismatch between the native C functions and the C code corresponding to real Java methods.
JNIEXPORT void JNICALL Java LibraryJNI BorrowBook (JNIEnv env, jobject obj, jint user, jint book)
C
public native void BorrowBook(intuser, int book)
3/39
?
i
P
4/39
?
i
P
The Mismatch
There are number of important differences between the two C functions in the middle of the slide:
What the JNI does
The Java Native Interface (JNI) provides a facility for the declaration of native methods on the Java side, and a way of programming a connection between the two mismatched C functions. The following explanation will be based on the
The results of the B operation are coded as a references. References aren't
allowed in Java and hence there will be no way of describing these arguments in Java.
MainLibraryAPI
machine and
its implementation. We will provide an embedding of the code generated by the B-Toolkit.
The translation of the Java method has two extra arguments: one is an environment pointer, and the other is the object that owns this method. These have no counterpart in the B implementation.
5/39
?
i
P
6/39
?
i
P
A Directory Structure
The following procedure requires the building of both C and Java files and access to the C files generated by the B-Toolkit translator. For convenience, we will create a directory
MainLibraryJNI.java
We need to build a Java file that specifies all the native C functions that we want to use as Java native methods. In this example we use global (static) variables to implement the operation results. Another possibility would be to use an array argument and pass back results in the array. Notice that
JNI
at the outer level of the B
development directory, and within that directory we create two directories:
C
and
Java.
Having translated the implementation of the relevant B machine, we need copies of the C files in the
INI MainLibraryAPI
the B-Toolkit in
is the initialisation function implemented by
C
directory. This can be achieved simply, if there is only one
MainLibraryAPI.c.
to load the shared object library that
implementation present, by creating soft links in the command in the
C directory.
Run the following
Notice the call to
C
System.loadLibrary
directory
contains the compiled C functions. We will build this library in a later step.
ln -s ../../CDE/C/ .
7/39
?
i
P
8/39
?
i
P
/** GUI for the Library B development * [e-mail] */ public class MainLibraryJNI { // global variables static int response = -1; // for register user static int newuser = -1; // for WhoBorrowed static int user = -1; // initialisation public native void INI_MainLibraryAPI(); // main operations public native void RegisterUser();
9/39
public public public public public public public public public
AcquireBook(int bookNo); ExitLibrary(int bookNo); BeginBrowseBook(int bookNo); EndBrowseBook(int bookNo); BorrowBook(int user, int bookNo); ReturnBook(int bookNo); WhoBorrowed(int bookNo); ReserveBook(int user, int bookNo); CancelBookReservation(int user, int bookNo); public native void UnCollectBook(int user, int bookNo); static { System.loadLibrary("MainLibrary"); } }
native native native native native native native native native
void void void void void void void void void
?
i
P
10/39
?
i
P
MainLibraryJNI.h
MainLibraryJNI.java
This, of course, will create should be compiled by running
Understanding the B-Toolkit code
We now need to move our attention to the equivalent to If you look in the
javac MainLibraryJNI.java MainLibraryJNI.class MainLibraryJNI.h
should then be created by running
C directory and eventually MainLibraryJNI.java.
build a C
CDE/C directory of the B development you will find suffixes .c, .h and .g. These play the following roles:
files with
javah MainLibraryJNI
This file should be linked into the
.c: .h: .g:
standard role of carrying code; defines machine parameters, constants and functions of machine; provides the instantiation of machine parameters and other constants. We will illustrate the
C
directory by running
ln -s ../Java/MainLibraryJNI.h .
in the
a
C
directory.
a
.h
and
.g
files with examples.
As for all softlinks created in this process, the link should only be created once.
11/39
?
i
P
12/39
?
i
P
MainLibraryAPI.h
Perhaps the most important thing to notice are the declaration of variables
extern int MainLibraryAPIP1; extern int MainLibraryAPIP2; extern int MainLibraryAPIP3;
and
MainLibraryAPIP1, MainLibraryAPIP2
denoting the three machine parameters of
MainLibraryAPIP3 MainLibraryAPI.
extern char * _MainLibraryAPI_RESPONSE []; extern char * _MainLibraryAPI_USER []; #define RESPONSE _MainLibraryAPI_RESPONSE #define USER _MainLibraryAPI_USER #define #define #define #define #define #define #define #define #define OK 1 BookInLibrary 2 LibraryFull 3 BookNotForLoan 4 BookNotOnLoan 5 BookNotAvailable 6 NotBeingBrowsed 7 InvalidReservation 8 NoNewUsers 9
? i P
13/39
?
i
P
14/39
#define #define #define #define #define #define void void void void void void void void void void void
NotRegisteredUser 10 NotForCollection 11 NotReservedForUser 12 ReserveQueueFull 13 UnBorrowedBook 14 FAIL 15
void UnCollectBook(int *_response,int _user,int _book);
INI_MainLibraryAPI(void); RegisterUser(int *_response,int *_newuser); AcquireBook(int *_response,int _book); ExitLibrary(int *_response,int _book); BeginBrowseBook(int *_response,int _book); EndBrowseBook(int *_response,int _book); BorrowBook(int *_response,int _user,int _book); ReturnBook(int *_response,int _book); WhoBorrowed(int *_response,int *_user,int _book); ReserveBook(int *_response,int _user,int _book); CancelBookReservation (int *_response,int _user,int _book);
15/39
?
i
P
16/39
?
i
P
MainLibraryAPI.g
Things to notice about this file:
int MainLibraryAPIP1 = MainLibraryAPIPV1; int MainLibraryAPIP2 = MainLibraryAPIPV2; int MainLibraryAPIP3 = MainLibraryAPIPV3; char * _MainLibraryAPI_RESPONSE [] = { "", "OK", "BookInLibrary", "LibraryFull", "BookNotForLoan", "BookNotOnLoan", "BookNotAvailable", "NotBeingBrowsed", "InvalidReservation", "NoNewUsers", "NotRegisteredUser", "NotForCollection", "NotReservedForUser", "ReserveQueueFull", "UnBorrowedBook", "FAIL", "_RESPONSE" }; char * _MainLibraryAPI_USER [] = {"1..maxuser"}; #define user_NvarPV1 MainLibraryAPIPV1 #include "user_Nvar.g" #define LibraryDBPV1 MainLibraryAPIPV2
it contains the instantiation of machine parameters of all machines imported by
the implementation of
MainLibraryAPI;
for all machines imported by the implementation of
it includes the
.g file MainLibraryAPI;
as extern in the
it contains the machine parameter variables of
MainLibraryAPI,
declared
.h
file. These variables are set to symbolic values, which are
currently undefined.
17/39
?
i
P
18/39
?
i
P
#define LibraryDBPV2 {"1..maxbook"} #define LibraryDBPV3 {"1..maxuser"} #include "LibraryDB.g"
MainLibraryJNI.g
.g files it follows that the machine parameters will not have been defined and nor will the .g files have been included for the following
Given the role and usage of the machines:
the top level machine, in our case any machines that are
MainLibraryAPI;
SEEN
by any machines in the implementation.
Thus, we need to build a file that the represents interface to the topmost level. This file clearly has the role of a it
.g file and for want of a better name, we will call
MainLibraryJNI.g.
19/39
?
i
P
20/39
?
i
P
/** Gui for Library B development * [e-mail] */ #define MainLibraryAPIPV1 10 #define MainLibraryAPIPV2 10 #define MainLibraryAPIPV3 5 #include "MainLibraryAPI.g" #define maxuser MainLibraryAPIPV1 #define maxlibrary MainLibraryAPIPV2 #define maxreserve MainLibraryAPIPV3 #include "LibraryDBCtx.g" #define Book_TYPEPV1 10 #include "Book_TYPE.g" #define maxbook Book_TYPEPV1 #include "Bool_TYPE.g" #include "basic_io.g" #include "file_dump.g" #include "Scalar_TYPE.g"
21/39
#include "String_TYPE.g" #include "LibraryDB_file_dump.g"
?
i
P
22/39
?
i
P
Note carefully the included files:
MainLibraryJNI.c
Now we can build the C file that will act as an interface between the native C functions and the C representations of the Java native methods declared in
jni.h
part of the JNI.
stdio.h MainLibraryAPI.h MainLibraryJNI.h MainLibraryJNI.g
will further include generated by B-Toolkit. generated by javah. our top-level
MainLibraryJNI.java.
Notice the following for each operation:
.g
file.
The C function representing the Java method; Local variables for any results; A call of the native C function, with appropriate passing of references to result
variables;
jni.h
jni md.h,
which contains machine dependent defini-
tions of various types.
The use of the environment to pass any results back to the appropriate global
variables.
23/39
?
i
P
24/39
?
i
P
/** Gui for Library B development * [e-mail] */ #include #include #include #include #include <jni.h> <stdio.h> "MainLibraryAPI.h" "MainLibraryJNI.h" "MainLibraryJNI.g"
/* initialisation */ JNIEXPORT void JNICALL Java_MainLibraryJNI_INI_1MainLibraryAPI (JNIEnv *env, jobject obj) { INI_MainLibraryAPI(); }
/* register user */ JNIEXPORT void JNICALL Java_MainLibraryJNI_RegisterUser (JNIEnv *env, jobject obj) { int response = 0; int newuser = 0; jclass cls = (*env)->GetObjectClass(env, obj); jfieldID fid; /* call the C method */ RegisterUser(&response, &newuser); /* set the fields to be accessed by java. */ fid = (*env)->GetStaticFieldID (env, cls, "response", "I"); (*env)->SetStaticIntField(env, cls, fid, response); fid = (*env)->GetStaticFieldID (env, cls, "newuser", "I"); (*env)->SetStaticIntField(env, cls, fid, newuser); }
25/39
?
i
P
26/39
?
i
P
/* acquire book */ JNIEXPORT void JNICALL Java_MainLibraryJNI_AcquireBook (JNIEnv *env, jobject obj, jint book){ int response = 0; jclass cls = (*env)->GetObjectClass(env, obj); jfieldID fid; /* call the C method */ AcquireBook(&response, book); /* set the fields to be accessed by java. */ fid = (*env)->GetStaticFieldID (env, cls, "response", "I"); (*env)->SetStaticIntField(env, cls, fid, response); }
/* exit library */ JNIEXPORT void JNICALL Java_MainLibraryJNI_ExitLibrary (JNIEnv *env, jobject obj, jint book){ int response = 0; jclass cls = (*env)->GetObjectClass(env, obj); jfieldID fid; /* call the C method */ ExitLibrary(&response, book); /* set the fields to be accessed by java. */ fid = (*env)->GetStaticFieldID (env, cls, "response", "I"); (*env)->SetStaticIntField(env, cls, fid, response); }
27/39
?
i
P
28/39
?
i
P
/* BeginBrowseBook */ JNIEXPORT void JNICALL Java_MainLibraryJNI_BeginBrowseBook (JNIEnv *env, jobject obj, jint book){ int response = 0; jclass cls = (*env)->GetObjectClass(env, obj); jfieldID fid; /* call the C method */ BeginBrowseBook(&response, book); /* set the fields to be accessed by java. */ fid = (*env)->GetStaticFieldID (env, cls, "response", "I"); (*env)->SetStaticIntField(env, cls, fid, response); }
/* end browse book */ JNIEXPORT void JNICALL Java_MainLibraryJNI_EndBrowseBook (JNIEnv *env, jobject obj, jint book){ int response = 0; jclass cls = (*env)->GetObjectClass(env, obj); jfieldID fid; /* call the C method */ EndBrowseBook(&response, book); /* set the fields to be accessed by java. */ fid = (*env)->GetStaticFieldID (env, cls, "response", "I"); (*env)->SetStaticIntField(env, cls, fid, response); }
29/39
?
i
P
30/39
?
i
P
/* borrow book */ JNIEXPORT void JNICALL Java_MainLibraryJNI_BorrowBook (JNIEnv *env, jobject obj, jint user, jint book) { int response = 0; jclass cls = (*env)->GetObjectClass(env, obj); jfieldID fid; /* call the C method */ BorrowBook(&response, user, book); /* set the fields to be accessed by java. */ fid = (*env)->GetStaticFieldID (env, cls, "response", "I"); (*env)->SetStaticIntField(env, cls, fid, response); }
/* return book */ JNIEXPORT void JNICALL Java_MainLibraryJNI_ReturnBook (JNIEnv *env, jobject obj, jint book){ int response = 0; jclass cls = (*env)->GetObjectClass(env, obj); jfieldID fid; /* call the C method */ ReturnBook(&response, book); /* set the fields to be accessed by java. */ fid = (*env)->GetStaticFiel...