Java Native Interface Programming |
This page shows you how to declare a native method in Java and how to generate the C/C++ function prototype.The Java Side
Our first example,
Prompt.java
, contains a native method that takes and prints a Java string, waits for user input, and then returns the line that the user typed in.The Java class
Prompt
contains amain
method which is used to invoke the program. In addition, there is agetLine
native method:private native String getLine(String prompt);Notice that the declarations for native methods are almost identical to the declarations for regular, non-native Java methods. There are two differences. Native methods must have the
native
keyword. Thenative
keyword informs the Java compiler that the implementation for this method is provided in another language. Also, the native method declaration is terminated with a semicolon, the statement terminator symbol, because there are no implementations for native methods in the Java class file.The Native Language Side
You must declare and implement native methods in a native language, such as C or C++. Before you do this, it is helpful to generate the header file that contains the function prototype for the native method implementation.First, compile the
Prompt.java
file and then generate the.h
file. Compile thePrompt.java
file as follows:javac Prompt.javaOnce you have successfully compiled
Prompt.java
and have created thePrompt.class
file, you can generate a JNI-style header file by specifying a-jni
option tojavah
:javah -jni PromptExamine the Prompt.h file. Note the function prototype for the native method
getLine
that you declared in Prompt.java.JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *, jobject, jstring);The native method function definition in the implementation code must match the generated function prototype in the header file. Always include
JNIEXPORT
andJNICALL
in your native method function prototypes.JNIEXPORT
andJNICALL
ensure that the source code compiles on platforms such as Win32 that require special keywords for functions exported from dynamic link libraries.Native method names are concatenated from the following components:
- the prefix
Java_
- the fully qualified class name
- an underscore "_" separator
- the method name
(Note that overloaded native method names, in addition to the above components, have extra two underscores "__" appended to the method name followed by the argument signature.)
As a result, the
Prompt.getLine
method is implemented byJava_Prompt_getLine
in native code. (There is no package name component because thePrompt
class is in the default package.)Each native method has two additional parameters, in addition to any parameters that you declare on the Java side. The first parameter,
JNIEnv *
, is the JNI interface pointer. This interface pointer is organized as a function table, with every JNI function at a known table entry. Your native method invokes specific JNI functions to access Java objects through theJNIEnv *
pointer. Thejobject
parameter is a reference to the object itself (it is like thethis
pointer in C++).Lastly, notice that JNI has a set of type names (e.g.,
jobject
,jstring
) that correspond to Java types. This is covered in the next section.
Java Native Interface Programming |