Using the JNI

by Beth Stearns

The lessons in this trail show you how to integrate native code with programs written in the Java programming language. You will also learn how to write Java programming language native methods. Native methods are implemented in another programming language such as C.
The Java Native Interface (JNI) is the native programming interface for the Java programming language that is part of the Java Developer's Kit (JDK). By writing programs using the JNI, you ensure that your code is completely portable across all platforms.
The JNI allows Java programming language code that runs within a Java Virtual Machine (VM) to operate with applications and libraries written in other programming languages, such as C, C++ , and assembly. In addition, the Invocation API allows you to embed the Java Virtual Machine into your native applications.
Programmers use the JNI to write native methods to handle those situations when an application cannot be written entirely in the Java programming language. For example, you may need to use native methods and the JNI in the following situations:

The standard Java programming language class library may not support the platform-dependent features needed by your application.

You may already have a library or application written in another programming language and you wish to make it accessible to Java applications.

You may want to implement a small portion of time-critical code in a lower-level programming language, such as assembly, and then have your Java application call these functions.

Programming through the JNI framework lets you use native methods to do many operations. Native methods are methods written in a programming language native to the platform, such as C and C++. Native methods may represent legacy applications or they may be written explicitly to solve a problem that is best handled outside of the Java programming environment.
The JNI framework lets your native method utilize Java programming language objects in the same way that Java programming language code uses these objects. A native method can create Java programming language objects, including arrays and strings, and then inspect and use these objects to perform its tasks. It can also inspect and use objects created by Java application code. It can even update Java programming language objects that it created or that were passed to it, and these updated objects are available to the Java application. Thus, both the native language side and the Java programming language side of an application can create, update, and access Java programming language objects and then share these objects between them.
Native methods can also easily call Java programming language methods. Often, you will already have developed a library of Java programming language methods. There is no need for your native method, when it needs to perform this same functionality, to "re-invent the wheel." The native method, using the JNI framework, can call the existing Java programming language method, pass it the required parameters, and get the results back when the method completes.
The JNI enables you to use the advantages of the Java programming language from your native method. In particular, you can catch and throw exceptions from the native method and have these exceptions handled in the Java application. Native methods can also get information about Java programming language classes. There are JNI functions that enable native methods to load Java programming language classes and obtain class information. Finally, native methods can use the JNI to perform runtime type checking.
For example, the following figure shows how a legacy C program can use the JNI to link with Java programming language libraries, call Java programming language methods, use Java programming language classes, and so on.
The next figure illustrates calling native language functions from a Java application. This diagram shows the many possibilities for utilizing the JNI from a Java program, including calling C routines, using C++ classes, calling assembler routines, and so on.
The JNI is for programmers who must take advantage of platform-specific functionality outside of the Java Virtual Machine. Because of this, it is recommended that only experienced programmers should attempt to write native methods or use the Invocation API!

Step By Step walks you step by step through a simple example (the "Hello World!" of native methods) to illustrate how to write, compile, and run a Java program with native methods.
Java Native Interface Programming shows you how to implement both the Java programming language side and the native language side of a native method. This lesson includes information about passing arguments of various data types into a native method and returning values of various data types from a native method. This lesson also describes many useful functions that your native language code can use to access Java objects and their members, create Java objects, throw exceptions, invoke the Java Virtual Machine, and more.

Security consideration: Note that the ability to load dynamic libraries is subject to approval by the current security manager. When working with native methods, you must load dynamic libraries. Some applets may not be able to use native methods because the browser or viewer they are running in restricts the ability to load dynamic libraries. See Security Restrictions for information about the security restrictions placed on applets.
Note: MacOS programmers should refer to MacOS Runtime for Java (MRJ).

Programmers interested in writing native methods in releases prior to 1.1 can download the old version of this trail. It describes native methods for the 1.0.2 release of the JDK.

Contents