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. After the jstring has been converted to a UTF-8 string, you can directly pass the string to most 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);
    ...
If the original string contained only characters in the ASCII range of Unicode, then all standard C library functions will work on the UTF-8 string exactly as they would on the corresponding ASCII string (because in this case, they are identical strings). If the original string contained non-ASCII characters, some library functions may not behave as expected if passed the converted, UTF-8 string. For example, the result of passing such a UTF-8 string to the strlen function will not be the number of Unicode characters in the string.
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.

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.