Java Native Interface Programming

The JDK1.1 supports the Java Native Interface (JNI). On one hand, the JNI defines a standard naming and calling convention so that the Java Virtual Machine (VM) can locate and invoke your native methods. On the other hand, the JNI offers a set of standard interface functions. You call JNI functions from your native method code to do such things as access and manipulate Java programming language objects, release Java programming language objects, create new objects, call Java programming language methods, and so on.
This section shows you how to follow the JNI naming and calling conventions, and how to use JNI functions from a native method. Each example consists of a program written in the Java programming language that calls various native methods implemented in the C programming language. The native methods, in turn, may call JNI functions to access the Java programming language objects.
This section also shows you how to embed the Java Virtual Machine into a native application. Embedding the JVM into your native application gives the native application the full power of the JVM. For example, you might want to do this if your application is a web browser that supports the execution of Java applets.

Declaring Native Methods

On the Java programming language side, you declare a native method with the native keyword and an empty method body. On the native language side, you provide an implementation for the native method. You must be careful when writing native methods to "match" the native function implementation with the method signature in the Java header file. The javah tool, which is explained in Step 3: Create the .h file, helps you to generate native function prototypes that match the Java programming language native method declaration.

Mapping between Java and Native Types

The JNI defines a mapping of Java programming language types and native language (C/C++) types. This section introduces the native types corresponding to both primitive Java programming language types, such as int and double, and Java programming language objects, including strings and arrays.

Accessing Java Strings

Strings are a particularly useful kind of Java programming language objects. The JNI provides a set of string manipulation functions to ease the task of handling Java programming language strings in native code. The programmer can translate between Java programming language strings and native strings in Unicode and UTF-8 formats.

Accessing Java Arrays

Arrays are another kind of frequently-used Java programming language object. You can use JNI array manipulation functions to create arrays and access array elements.

Calling Java Methods

The JNI supports a complete set of "callback" operations that allow you to invoke a Java programming language method from the native code. You locate the method using its name and signature. You can also invoke both static and instance (non-static) methods. Use the javap tool to generate JNI-style method signatures from class files.

Accessing Java Fields

The JNI allows you to locate a Java programming language field using the field's name and type signature. You can locate and access both static and instance (non-static) fields. The javap tool helps you to generate JNI-style field signatures from class files.

Catching and Throwing Exceptions

This section teaches you how to deal with exceptions from within a native method implementation. Your native method can catch, throw, and clear exceptions.

Local and Global References

Native code can refer to Java programming language objects using either local or global references. Local references are only valid within a native method invocation. They are freed automatically after the native method returns. You must explicitly allocate and free global references.

Threads and Native Methods

This section describes the implications of running native methods in the multi-threaded Java programming language environment. The JNI offers basic synchronization constructs for native methods.

Invoking the Java Virtual Machine

This section shows you how to load the Java Virtual Machine from a native library into a native application. It includes instructions on how to initialize the Java Virtual Machine and invoke Java programming language methods. The Invocation API also allows native threads to attach to a running Java Virtual Machine and bootstrap themselves into Java programming language threads. Currently, the JDK only supports attaching native threads on Win32. The support for Solaris native threads will be available in a future release.

JNI Programming in C++

In the C++ programming language , the JNI presents a slightly cleaner interface and performs additional static type checking.

Contents