| Java Native Interface Programming

## Declaring Native Methods

> 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 a `main` method which is used to invoke the program. In addition, there is a `getLine` 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. The `native` 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 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 prototype in the header file. Always include `JNIEXPORT` and `JNICALL` in your native method function prototypes. `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

> (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 by `Java_Prompt_getLine` in native code. (There is no package name component because the `Prompt` 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 the `JNIEnv *` pointer. The `jobject` parameter is a reference to the object itself (it is like the `this` 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