World Library  
Flag as Inappropriate
Email this Article

Java Native Interface

Article Id: WHEBN0000230828
Reproduction Date:

Title: Java Native Interface  
Author: World Heritage Encyclopedia
Language: English
Subject: Java AWT Native Interface, Foreign function interface, Comparison of Java and C++, RNI, Java Virtual Machine Tools Interface
Collection: Java Platform
Publisher: World Heritage Encyclopedia

Java Native Interface

In computing, the Java Native Interface (JNI) is a programming framework that enables Java code running in a Java Virtual Machine (JVM) to call and be called by[1] native applications (programs specific to a hardware and operating system platform) and libraries written in other languages such as C, C++ and assembly.


  • Purpose and features 1
  • Pitfalls 2
  • How the JNI works 3
    • Mapping types 3.1
    • JNIEnv* 3.2
  • Advanced uses 4
    • Native AWT painting 4.1
    • Access to assembly code 4.2
  • Microsoft's J/Direct and RNI 5
  • Examples 6
    • HelloWorld 6.1
  • See also 7
  • References 8
  • Bibliography 9
  • External links 10

Purpose and features

JNI enables programmers to write native methods to handle situations when an application cannot be written entirely in the Java programming language, e.g. when the standard Java class (computer science) library does not support the platform-specific features or program library. It is also used to modify an existing application—written in another programming language—to be accessible to Java applications. Many of the standard library classes depend on JNI to provide functionality to the developer and the user, e.g. file I/O and sound capabilities. Including performance- and platform-sensitive API implementations in the standard library allows all Java applications to access this functionality in a safe and platform-independent manner.

The JNI framework lets a native method use Java objects in the same way that Java code uses these objects. A native method can create Java objects and then inspect and use these objects to perform its tasks. A native method can also inspect and use objects created by Java application code.


  • Subtle errors in the use of JNI can destabilize the entire JVM in ways that are very difficult to reproduce and debug.
  • Only applications and signed applets can invoke JNI.
  • An application that relies on JNI loses the platform portability Java offers (a partial workaround is to write a separate implementation of JNI code for each platform and have Java detect the operating system and load the correct one at runtime).
  • The JNI framework does not provide any automatic garbage collection for non-JVM memory resources allocated by code executing on the native side. Consequently, native side code (such as assembly language) assumes the responsibility for explicitly releasing any such memory resources that the native code acquires.
  • On Linux and Solaris platforms, if the native code registers itself as a signal handler, it could intercept signals intended for the JVM. A chain of responsibility can be used to allow native code to better inter-operate with the JVM.
  • On Windows platforms, Structured Exception Handling (SEH) may be employed to wrap native code in SEH try/catch blocks so as to capture machine (CPU/FPU) generated software interrupts (such as NULL pointer access violations and divide-by-zero operations), and to handle these situations before the interrupt is propagated back up into the JVM (i.e. Java side code), in all likelihood resulting in an unhandled exception.
  • The encoding used for the NewStringUTF, GetStringUTFLength, GetStringUTFChars, ReleaseStringUTFChars and GetStringUTFRegion functions is "modified UTF-8",[2] which is not valid UTF-8 for all inputs, but a different encoding really. The null character (U+0000) and codepoints not on the Basic Multilingual Plane (greater than or equal to U+10000, i.e. those represented as surrogate pairs in UTF-16) are encoded differently in modified UTF-8. Many programs actually use these functions incorrectly and treat the UTF-8 strings returned or passed into the functions as standard UTF-8 strings instead of modified UTF-8 strings. Programs should use the NewString, GetStringLength, GetStringChars, ReleaseStringChars, GetStringRegion, GetStringCritical and ReleaseStringCritical functions, which use UTF-16LE encoding on little-endian architectures and UTF-16BE on big-endian architectures, and then use a UTF-16 to UTF-8 conversion routine.
  • JNI incurs considerable overhead and performance loss under certain circumstances:[3]
    • Function calls to JNI methods are expensive, especially when calling a method repeatedly.
    • Native methods are not inlined by the JVM, nor can the method be JIT compiled, as the method is already compiled.
    • A Java array may be copied for access in native code, and later copied back. The cost can be linear in the size of the array.
    • If the method is passed an object, or needs to make a callback, then the native method will likely be making its own calls to the JVM. Accessing Java fields, methods and types from the native code requires something similar to reflection. Signatures are specified in strings and queried from the JVM. This is both slow and error-prone.
    • Java Strings are objects, have length and are encoded. Accessing or creating a string may require an O(n) copy.

How the JNI works

In the JNI framework, native functions are implemented in separate .c or .cpp files. (C++ provides a slightly simpler interface with JNI.) When the JVM invokes the function, it passes a JNIEnv pointer, a jobject pointer, and any Java arguments declared by the Java method. A JNI function may look like this:

JNIEXPORT void JNICALL Java_ClassName_MethodName
  (JNIEnv *env, jobject obj)
    /*Implement Native Method Here*/

The env pointer is a structure that contains the interface to the JVM. It includes all of the functions necessary to interact with the JVM and to work with Java objects. Example JNI functions are converting native arrays to/from Java arrays, converting native strings to/from Java strings, instantiating objects, throwing exceptions, etc. Basically, anything that Java code can do can be done using JNIEnv, albeit with considerably less ease.

The argument obj is a reference to the Java object inside which this native method has been declared.

For example, the following converts a Java string to a native string:

//C++ code
extern "C"
JNIEXPORT void JNICALL Java_ClassName_MethodName
  (JNIEnv *env, jobject obj, jstring javaString)
    //Get the native string from javaString
    const char *nativeString = env->GetStringUTFChars(javaString, 0);

    //Do something with the nativeString

    env->ReleaseStringUTFChars(javaString, nativeString);
/*C code*/
JNIEXPORT void JNICALL Java_ClassName_MethodName
  (JNIEnv *env, jobject obj, jstring javaString)
    /*Get the native string from javaString*/
    const char *nativeString = (*env)->GetStringUTFChars(env, javaString, 0);

    /*Do something with the nativeString*/

    (*env)->ReleaseStringUTFChars(env, javaString, nativeString);
/*Objective-C code*/
JNIEXPORT void JNICALL Java_ClassName_MethodName
  (JNIEnv *env, jobject obj, jstring javaString)

    /*Get the native string from javaString*/
    NSString* nativeString = JNFJavaToNSString(env, javaString);

    /*Do something with the nativeString*/


Native data types can be mapped to/from Java data types. For compound types such as objects, arrays and strings the native code must explicitly convert the data by calling methods in the JNIEnv.

Mapping types

The following table shows the mapping of types between Java (JNI) and native code.

Native Type Java Language Type Description Type signature
unsigned char jboolean unsigned 8 bits Z
signed char jbyte signed 8 bits B
unsigned short jchar unsigned 16 bits C
short jshort signed 16 bits S
long jint signed 32 bits I

long long

jlong signed 64 bits J
float jfloat 32 bits F
double jdouble 64 bits D
void V

In addition, the signature "L fully-qualified-class ;" would mean the class uniquely specified by that name; e.g., the signature "Ljava/lang/String;" refers to the class java.lang.String. Also, prefixing [ to the signature makes the array of that type; for example, [I means the int array type. Finally, a void signature uses the V code.

Here, these types are interchangeable. You can use jint where you normally use an int, and vice versa, without any typecasting required.

However, mapping between Java Strings and arrays to native strings and arrays is different. If you use a jstring in where a char * would be, your code could crash the JVM.

/*C code*/
JNIEXPORT void JNICALL Java_ClassName_MethodName
        (JNIEnv *env, jobject obj, jstring javaString) {
    // printf("%s", javaString);        // INCORRECT: Could crash VM!

    // Correct way: Create and release native string from Java string
    const char *nativeString = (*env)->GetStringUTFChars(env, javaString, 0);
    printf("%s", nativeString);
    (*env)->ReleaseStringUTFChars(env, javaString, nativeString);

This is similar with Java arrays, as illustrated in the example below that takes the sum of all the elements in an array.

JNIEXPORT jint JNICALL Java_IntArray_sumArray
        (JNIEnv *env, jobject obj, jintArray arr) {
    jint buf[10];
    jint i, sum = 0;
    // This line is necessary, since Java arrays are not guaranteed
    // to have a continuous memory layout like C arrays.
    env->GetIntArrayRegion(arr, 0, 10, buf);
    for (i = 0; i < 10; i++) {
        sum += buf[i];
    return sum;

Of course, there is much more to it than this. Look for links below for more information.


A JNI environment pointer (JNIEnv*) is passed as an argument for each native function mapped to a Java method, allowing for interaction with the JNI environment within the native method. This JNI interface pointer can be stored, but remains valid only in the current thread. Other threads must first call AttachCurrentThread() to attach themselves to the VM and obtain a JNI interface pointer. Once attached, a native thread works like a regular Java thread running within a native method. The native thread remains attached to the VM until it calls DetachCurrentThread() to detach itself.[4]

To attach to the current thread and get a JNI interface pointer:

 JNIEnv *env;
 (*g_vm)->AttachCurrentThread (g_vm, (void **) &env, NULL);

To detach from the current thread:

 (*g_vm)->DetachCurrentThread (g_vm);

Advanced uses

Native AWT painting

Not only can native code interface with Java, it can also draw on a Java Canvas, which is possible with the Java AWT Native Interface. The process is almost the same, with just a few changes. The Java AWT Native Interface is only available since J2SE 1.3.

Access to assembly code

JNI also allows direct access to assembly code, without even going through a C bridge.[5] Accessing Java applications from assembly is also possible in the same way.[6]

Microsoft's J/Direct and RNI

Microsoft's discontinued proprietary implementation of a Java Virtual Machine (Visual J++) has a similar mechanism for calling native code from Java, called the Raw Native Interface (RNI). In addition, it has an easy way to call existing native code that isn't itself aware of Java, such as (but not limited to) the Windows API, called J/Direct. However, following the Sun - Microsoft litigation about this implementation, Visual J++ is no longer maintained.

RNI was less clumsy to use than JNI, because no bookkeeping with a Java environment pointer was needed. Instead, all Java objects could be accessed directly. To facilitate this, a tool was used that generated header files from Java classes. Similarly, J/Direct was easier to use than using the necessary intermediate native library and JNI, although at present JNA is an alternative.




# Linux 2.6.32-358.el6.x86_64
# gcc 4.4.7
# openjdk 1.7.0

javah HelloWorld
gcc -shared -fPIC libHelloWorld.c -o
java HelloWorld


:: Microsoft Visual Studio 2012 Visual C++ compiler
SET VC=C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC
:: Microsoft Windows SDK for Windows 7 and .NET Framework 4 
SET MSDK=C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1A
:: Java 1.7.0 update 21
SET JAVA_HOME=C:\Program Files (x86)\Java\jdk1.7.0_21
:: Add compiler tools folder to the PATH variable.  Do not run this too many times or the PATH will exceed the maximum limit.
call "%VC%\vcvarsall.bat"

javah HelloWorld
:: On Windows, the JNI library should not have a "lib" prefix
%VC%\bin\cl "/I%JAVA_HOME%\include" "/I%JAVA_HOME%\include\win32" "/I%VC%\include" "/I%VC%\lib" "/I%MSDK%\Lib" "libHelloWorld.c" "/FeHelloWorld.dll" /LD
java HelloWorld

class HelloWorld
    private native void print();
    public static void main(String[] args)
        new HelloWorld().print();
    static {


/* DO NOT EDIT THIS FILE - it is machine generated */
/* Header for class HelloWorld */

#ifndef _Included_HelloWorld
#define _Included_HelloWorld
#ifdef __cplusplus
extern "C" {
 * Class:     HelloWorld
 * Method:    print
 * Signature: ()V
JNIEXPORT void JNICALL Java_HelloWorld_print
  (JNIEnv *, jobject);

#ifdef __cplusplus


 #include "HelloWorld.h"

 Java_HelloWorld_print(JNIEnv *env, jobject obj)
     printf("Hello World!\n");


$ chmod +x
$ ./

See also

  • Java AWT Native Interface
  • Gluegen, a Java tool which automatically generates the Java and JNI code necessary to call C libraries from Java code
  • P/Invoke, the .NET Framework method of calling native applications
  • SWIG, a multilanguage interface-generator for C and C++ libraries that can generate JNI code
  • GIWS, a wrapper generator to simplify calling Java from C or C++, essentially the opposite of SWIG.
  • Java Native Access provides Java programs easy access to native shared libraries without writing boilerplate code


  1. ^ "Role of the JNI". The Java Native Interface Programmer's Guide and Specification. Retrieved 2008-02-27. 
  2. ^ Modified UTF-8 Strings
  3. ^
  4. ^ The Invocation API. Sun Microsystems.
  5. ^ "Invoking Assembly Language Programs from Java". 2006-10-19. Retrieved 2007-10-06. 
  6. ^ "Launch Java Applications from Assembly Language Programs". 2006-10-19. Retrieved 2007-10-04. 


  • Gordon, Rob (March 1998). Essential Jni: Java Native Interface (1st ed.).  
  • Liang, Sheng (June 20, 1999). Java(TM) Native Interface: Programmer's Guide and Specification (1st ed.).  

External links

  • Oracle's JNI page for Java 6, including the JNI Specification
  • Java Native Interface: Programmer's Guide and Specification – a book, copyright 2002
  • Best practices for using the Java Native Interface
  • JNI Complete tutorial with examples
  • GNU CNI Tutorial
  • Multi-platform JNI Tutorial at
  • A JNI Tutorial at (Microsoft specific)
  • JNI Tutorial at
  • Larger JNI example from Sun
  • JNI video tutorial with Eclipse and Visual Studio
  • JNI in XCode from Apple
  • Exception handling in JNI
  • HawtJNI – simplifies creating JNI libraries by code generating the JNI implementations using declarative annotations placed on your Java code
  • J/Link – lets you call Java from Mathematica in a completely transparent way, and it also lets you use and control the Mathematica kernel from a Java program (commercial)
  • Jace – a toolkit designed to make it easy to write JNI-based programs
  • JNIWrapper – provides simplified access to native code from Java applications without using Java Native Interface
  • Java to Native Interface – LGPL library to call native functions from Java
  • Java Native Access – access to native libraries from Java without JNI
  • NLink – another library for access to native libraries without JNI
  • NativeCall – call native methods from Java without JNI – a library to access native code without JNI
  • JNIEasy – transparent Native Programming for C/C++, pure Java alternative to JNI using POJOS and JDO/JPA development style
  • jni4net – a bridge between Java and .NET (intraprocess, fast, object oriented, open-source)
  • Object-Oriented JNI Advanced Add-in for VC6 – an Object-Oriented JNI with a number of helpers that includes the standard JNI SDK for regular C++ (commercial)
  • Object-Oriented JNI for .NET1.1 (low-level) – an Object-Oriented JNI with a number of helpers that includes the standard JNI SDK for C#, Managed C++, VB#, J# (commercial)
  • Object-Oriented JNI for .NET2.0 (low-level) – an Object-Oriented JNI with a number of helpers that includes the standard JNI SDK for C#, Managed C++, VB#, J# (commercial)
  • OOJNI Add-in (C#,VB#) for VS2005/2008 – generates object-oriented JNI code in C# or VB# for Java classes selected, implements Java interfaces and Java native methods in VB# and C#. Java Class methods and fields (which are represented as .NET Class properties) to be wrapped can be filtered. (commercial)
  • DB JNItremeXe – uses Java annotations and reflection to enable Java applications to call the eXtremeDB database (written in C) without reliance on an external database definition language
  • JavaToDPR – a Delphi Project (.dpr) Stub File Generator that allows one to write an Embarcadero Delphi DLL to handle the native methods declared in a Java .class file
  • PyJNIus — a Python library to allow calling java code from CPython, and implement java interfaces from CPython, using JNI and java instrospection to wrap class automatically in python objects.
This article was sourced from Creative Commons Attribution-ShareAlike License; additional terms may apply. World Heritage Encyclopedia content is assembled from numerous content providers, Open Access Publishing, and in compliance with The Fair Access to Science and Technology Research Act (FASTR), Wikimedia Foundation, Inc., Public Library of Science, The Encyclopedia of Life, Open Book Publishers (OBP), PubMed, U.S. National Library of Medicine, National Center for Biotechnology Information, U.S. National Library of Medicine, National Institutes of Health (NIH), U.S. Department of Health & Human Services, and, which sources content from all federal, state, local, tribal, and territorial government publication portals (.gov, .mil, .edu). Funding for and content contributors is made possible from the U.S. Congress, E-Government Act of 2002.
Crowd sourced content that is contributed to World Heritage Encyclopedia is peer reviewed and edited by our editorial staff to ensure quality scholarly research articles.
By using this site, you agree to the Terms of Use and Privacy Policy. World Heritage Encyclopedia™ is a registered trademark of the World Public Library Association, a non-profit organization.

Copyright © World Library Foundation. All rights reserved. eBooks from Project Gutenberg are sponsored by the World Library Foundation,
a 501c(4) Member's Support Non-Profit Organization, and is NOT affiliated with any governmental agency or department.