The JavaTM Tutorial

| 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.

- `GetStringChars` takes the Java string and returns a pointer to an array of Unicode characters that comprise the string.
- `ReleaseStringChars` releases the pointer to the array of Unicode characters.
- `NewString` constructs a new `java.lang.String` object from an array of Unicode characters.
- `GetStringLength` returns the length of a string that is comprised of an array of Unicode characters.
- `GetStringUTFLength` returns the length of a string if it is represented in the UTF-8 format.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2004 Sun Microsystems, Inc. All rights reserved.