The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Trail: Java Native Interface
Lesson: Interacting with Java from the Native Side

Accessing Java Strings in Native Methods

When a Java application passes a string to a native method, it passes the string as a jstring type. This jstring type is different from the regular C string type (char *). If your code tries to print a jstring directly, it will likely result in a VM crash. For example, the following code segment incorrectly tries to print a jstring and may result in a VM crash: 
/* DO NOT USE jstring THIS WAY !!! */
JNIEXPORT jstring JNICALL
Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt)
{
    printf("%s", prompt);
    ...

Your native method code must use JNI functions to convert Java strings to native strings. The JNI supports the conversion to and from native Unicode and UTF-8 strings. In particular, UTF-8 strings use the highest bit-to-signal multibyte characters; they are therefore upwards-compatible with 7-bit ASCII. In Java, UTF-8 strings are always 0-terminated.

Accessing Java Strings

Your native method needs to call GetStringUTFChars to correctly print the string passed to it from a Java application. GetStringUTFChars converts the built-in Unicode representation of a Java string into a UTF-8 string. Once you are certain that the string only contains 7-bit ASCII characters, you can directly pass the string to regular C language functions, such as printf, as is shown in Prompt.c: 
JNIEXPORT jstring JNICALL
Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt)
{
    char buf[128];
    const char *str = (*env)->GetStringUTFChars(env, prompt, 0);
    printf("%s", str);
    (*env)->ReleaseStringUTFChars(env, prompt, str);
    ...
Note:  When your native code is finished using the UTF-8 string, it must call ReleaseStringUTFChars. ReleaseStringUTFChars informs the VM that the native method is finished with the string so that the VM can free the memory taken by the UTF-8 string. Failing to call ReleaseStringUTFChars results in a memory leak. This will ultimately lead to system memory exhaustion.

The native method can also construct a new string using the JNI function NewStringUTF. The following lines of code from Java_Prompt_getLine show this: 

    ...
    scanf("%s", buf);
    return (*env)->NewStringUTF(env, buf);
}

Using the JNIEnv Interface Pointer

Native methods must access and manipulate Java objects, such as strings, through the env interface pointer. In C, this requires using the env pointer to reference the JNI function. Notice how the native method uses the env interface pointer to reference the two functions, GetStringUTFChars and ReleaseStringUTFChars, that it calls. Not only does the native method use env as an interface pointer, env is passed as the first parameter to these functions.


This figure has been reduced to fit on the page.
Click the image to view it at its natural size.

Other JNI Functions for Accessing Java Strings

The JNI also provides functions to obtain the Unicode representation of Java strings. This is useful, for example, on those operating systems that support Unicode as the native format. There are also utility functions to obtain both the UTF-8 and Unicode length of Java strings.