he Java Native Interface (JNI) is used to call code written in another language—such as C or C++—from a Java program. As such, it is often used when a Java program needs to call pre-existing code in another language or to call code that could be written in Java but needs to be written in C/C++ for some reason. Data structures implemented in C or C++ can often be faster—and use less space—than the equivalent data structures in Java.

This article investigates the use of the JNI for accessing a data structure implemented in C++. The data structure I'll be implementing is a hashtable called JNativeHash. It's implementation is based on the map class from the Standard Template Libraries (STL). Unlike Java, C++ does not emphasize the use of run-time type identification, so it's not as easy to create a hashtable that maps arbitrary objects to arbitrary objects. Instead, I'll be creating a hashtable that maps strings to strings.

What You Need

• A recent JDK from Sun Microsystems, or a compatible Java development kit. • An Integrated Development Environment (IDE) for Java or a suitable command shell.

The Test Program
To test the code I'll simply load up the data structure with a lot of data and see how it performs. The test program simply loads the hashtable with 1,000,000 entries, like this:

JNativeHash jnh = JNativeHash.create();
for (int i=0; i<1000000; ++i) {
  jnh.put( "jnh"+i, i+"jnh" );
}

This code maps the string "jnh0" to the string "0jnh", "jnh1" to "1jnh", and so on.

There are two versions of the test program—JNHTest, which uses the native hashtable, and RegularTest, which uses a regular Java hashtable. These programs can be used to compare the space and time efficiency of the data structures.

In the next section, I'll review the overall structure of the code.

Code Structure
The code consists of the following source files:

• NativeHash.cc ( Listing 1): implements the hashtable, using STL
• NativeHash.h ( Listing 2): header file for NativeHash.cc
• JNativeHash.cc ( Listing 3): JNI interface to NativeHash.cc
• JNativeHash.h: header file for JNativeHash.cc—this is generated by the 'javah' tool, so it's not included here.
• JNativeHash.java ( Listing 4): Java interface to NativeHash.cc
• JNHTest.java ( Listing 5): test program for JNativeHash
• RegularTest.java ( Listing 6): test program from regular Java hashtable
• Err.cc ( Listing 7): support for C++ exceptions
• Err.h ( Listing 8): support for C++ exceptions

The first two files, NativeHash.cc and NativeHash.h, implement the hashtable data structuring using STL. This code is entirely independent from Java and could be used in a C++-only program.

The next two files, JNativeHash.cc and JNativeHash.h, implement the JNI interface to NativeHash.cc. The code is relatively straightforward: Each method in NativeHash has a corresponding method in JNativeHash. The methods in JNativeHash do little more than gather the arguments from the Java data structures and pass them on to the C++ code.

JNativeHash.java is the Java interface to NativeHash. This is the only file that a user of JNativeHash really has to know about. It contains all the appropriate methods for storing and retrieving hashtable values. Many of its methods are marked 'native'; these methods are implemented in JNativeHash.cc.

The next two files, JNHTest.java and RegularTest.java, are used to test the space and time efficiency of the code, as described above.

Finally, the last two files, Err.cc and Err.h, contain support code to allow the native C++ code to throw exceptions to the Java code that called it.

Let's take a look at the implementation of the core data structure.