About this tutorial

What is this tutorial about?

The Java Native Interface (JNI) is a native programming interface that is part of the Java Software Development Kit (SDK). JNI lets Java code use code and code libraries written in other languages, such as C and C++. The Invocation API, which is part of JNI, can be used to embed a Java virtual machine (JVM) into native applications, thereby allowing programmers to call Java code from within native code.

This tutorial deals with the two most common applications of JNI: calling C/C++ code from Java programs, and calling Java code from C/C++ programs. We'll cover both the essentials of the Java Native Interface and some of the more advanced programming challenges that can arise.

Should I take this tutorial?

This tutorial will walk you through the steps of using the Java Native Interface. You'll learn how to call native C/C++ code from within a Java application and how to call Java code from within a native C/C++ application.

All the examples use Java, C, and C++ code, and are written to be portable to both Windows and UNIX-based platforms. To follow the examples, you must have some experience programming in the Java language. In addition, you will also need some experience programming in C or C++. Strictly speaking, a JNI solution could be broken down between Java programming tasks and C/C++ programming tasks, with separate programmers doing each task. However, to fully understand how JNI works in both programming environments, you'll need to be able to understand both the Java and C/C++ code.

We'll also cover a number of advanced topics, including exception handling and multithreading with native methods. To get the most out of this part of the tutorial, you should be familiar with the Java platform's security model and have some experience in multithreaded application development.

The section on Advanced topics is separate from the more basic step-by-step introduction to JNI. Beginning Java programmers may benefit from taking the first two parts of the tutorial now and returning to the advanced topics at a later time.

See Resources for a listing of tutorials, articles, and other references that expand upon the material presented here.

Back to top

Tools and components

To run the examples in this tutorial, you will need the following tools and components:

• A Java compiler: javac.exe ships with the SDK.
  
  
• A Java virtual machine (JVM): java.exe ships with the SDK.
  
  
• A native method C file generator: javah.exe ships with the SDK.
  
  
• Library files and native header files that define JNI. The jni.h C header file, jvm.lib, and jvm.dll or jvm.so files all ship with the SDK.
  
  
• A C and C++ compiler that can create a shared library. The two most common C compilers are Visual C++ for Windows and cc for UNIX-based systems.

Although you may use any development environment you like, the examples we'll work with in this tutorial were written using the standard tools and components that ship with the SDK. See Resources to download the SDK, complete source files, and other tools essential for the completion of this tutorial. This tutorial specifically addresses Sun's implementation of JNI, which should be regarded as the standard for JNI solutions. The details of other JNI implementations are not addressed in this tutorial.

Back to top

Additional considerations

In the Java 2 SDK, the JVM and run-time support are located in the shared library file named jvm.dll (Windows) or libjvm.so (UNIX). In the Java 1.1 JDK, the JVM and run-time support were located in the shared library file named javai.dll (Windows) or libjava.so (UNIX). The version 1.1 shared libraries contained the runtime and some native methods for the class libraries, but in version 1.2, the runtime is removed and the native methods are in java.dll and libjava.so. This change is important in Java code that:

• Is written using non-JNI native methods (as with the old native method interface from the JDK 1.0 JDK)
  
  
• Uses an embedded JVM through the JNI Invocation Interface

In both cases, you'll need to relink your native libraries before they can be used with version 1.2. Note that this change should not affect JNI programmers implementing native methods -- only JNI code that invokes a JVM through the Invocation API.

If you use the jni.h file that comes with the SDK/JDK, that header file will use the default JVM in the JDK/SDK installation directory (jvm.dll or libjvm.so). Any implementation of a Java platform that supports JNI should do the same thing, or allow you to specify a JVM shared library; however the details of how this is done may be specific to that Java Platform/JVM implementation. Indeed, many implementations of JVMs do not support JNI at all.

1 of 8 | Next

Comments

Back to top

Table of contents

• About this tutorial
• Calling C/C++ code from Java programs
• Calling Java code from C/C++ programs
• Advanced topics
• Wrap-up
• Appendices
• Resources
• About the author

---

1 of 8 | Next

Next steps from IBM

Try the XL C/C++ compilers, downloadable for free.

---

• Try: XL C/C++ for AIX
• Community: Go to Rational C/C++ cafe to join the conversation.
• Buy: XL C/C++ for AIX

Dig deeper into Java on developerWorks

Discover knowledge paths

Skill-building guides for Java, Linux, open source, cloud, business analytics, and more.

Special offers