The Java TM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search

Trail: Java Native Interface
Lesson: Integrating Java and Native Programs

## Declaring Native Methods

> This section illustrates how to declare a native method in Java and how to generate the corresponding C/C++ function prototype.

### The Java Side

Our first example, `Prompt.java`, contains a native method that accepts and prints a Java string. The program calls the native method, which waits for user input and then returns the line the user typed in.

The `Prompt` class contains a `main` method, which is used to invoke the program, and a native method named `getLine`, which is declared as follows:

>     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. However, you declare native methods differently, as follows:

- First, native methods must have the `native` keyword. The `native` keyword informs the Java compiler that the implementation for this method is provided in another language.
- Secondly, the native method declaration is terminated with a semicolon (the statement terminator symbol) because the Java class file does not include implementations for native methods.

### 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.

Compile the `Prompt.java` file and then generate the `.h` file. First, compile the `Prompt.java` file as follows:

>     javac Prompt.java

Once you have successfully compiled `Prompt.java` and have created the `Prompt.class` file, you can generate a JNI-style header file by specifying a `-jni` option to `javah`:

>     javah -jni Prompt

Examine 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 signature in the header file. Always include `JNIEXPORT` and `JNICALL` in your native method function signatures. `JNIEXPORT` and `JNICALL` 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

Graphically, this looks as follows:

Thus, the native code implementation for the `Prompt.getLine` method becomes `Java_Prompt_getLine`. (Remember that no package name component appears because the `Prompt` class is in the default package.)

> Note: Overloaded native method names, in addition to the above components, have an extra two underscores "__" appended to the method name followed by the argument signature. To illustrate, we created a second version of the Java program, `Prompt2.java`, and overloaded the `getLine` method by adding a second argument of type `int`. The two `getLine` method names in the `Prompt2.h` header file look as follows:

> >     Java_Prompt2_getLine__Ljava_lang_String_2
> >     Java_Prompt2_getLine__Ljava_lang_String_2I

Recall from Step 3: Create the .h File, each native method has two parameters in addition to those parameters that you declared 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 point. Your native method invokes specific JNI functions to access Java objects through the `JNIEnv *` pointer. The `jobject` parameter is a reference to the object itself (it is like the `this` pointer in Java).

Lastly, notice that the JNI has a set of type names, such as `jobject` and `jstring`, and each type corresponds to Java types. This is covered in the next section.

| Start of Tutorial > Start of Trail > Start of Lesson | Search