http://journals.ecs.soton.ac.uk/java/tutorial/native1.1/implementing/index.html

 

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 objects, release Java objects, create new objects, call Java 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 Java program that calls various native methods implemented in C. The native methods, in turn, may call JNI functions to access the Java objects.

The section also shows you how to embed the Java Virtual Machine into a native application.

Declaring Native Methods

On the Java 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 take care when writing native methods to "match" the native function implementation with the method signature in Java. javah , explained in Step 3: Create the .h file , is a helpful tool to generate native function prototypes that match the Java native method declaration.

Mapping between Java and Native Types

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

Accessing Java Strings

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

Accessing Java Arrays

Arrays are another kind of frequently-used Java 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 method from the native code. You locate the method using its name and signature. You can invoke both static and instance (non-static) methods. javap is a helpful tool to generate JNI-style method signatures from class files.

Accessing Java Fields

The JNI allows you to locate the field using the field's name and type signature. You can get hold of both static and instance (non-static) fields. javap is a helpful tool 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 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 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. This lesson includes how to initialize the Java Virtual Machine and invoke Java methods. The Invocation API also allows native threads to attach to a running Java Virtual Machine and bootstrap themselves into Java 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 C++, the JNI presents a slightly cleaner interface and performs additional static type checking.