Contents | Prev | Next | Java Native Interface Specification

# 3 - JNI Types and Data Structures

This chapter discusses how the JNI maps Java types to native C types.

# Primitive Types

Table 3-1 describes Java primitive types and their machine-dependent native equivalents.

  #### Table 3-1 Primitive Types and Native Equivalents

  Java Type | Native Type | Description
  --- | --- | ---
  boolean | jboolean | unsigned 8 bits
  byte | jbyte | signed 8 bits
  char | jchar | unsigned 16 bits
  short | jshort | signed 16 bits
  int | jint | signed 32 bits
  long | jlong | signed 64 bits
  float | jfloat | 32 bits
  double | jdouble | 64 bits
  void | void | N/A

The following definition is provided for convenience.

        #define JNI_FALSE  0
        #define JNI_TRUE   1

The `jsize` integer type is used to describe cardinal indices and sizes:

        typedef jint jsize;

# Reference Types

The JNI includes a number of reference types that correspond to different kinds of Java objects. JNI reference types are organized in the hierarchy shown in Figure 3-1.

#### Figure 3-1 Reference Type Hierarchy

In C, all other JNI reference types are defined to be the same as jobject. For example:

        typedef jobject jclass;

In C++, JNI introduces a set of dummy classes to enforce the subtyping relationship. For example:

        class _jobject {};
        class _jclass : public _jobject {};
        ...
        typedef _jobject *jobject;
        typedef _jclass *jclass;

# Field and Method IDs

Method and field IDs are regular C pointer types:

        struct _jfieldID;              /* opaque structure */
        typedef struct _jfieldID *jfieldID;   /* field IDs */

        struct _jmethodID;              /* opaque structure */
        typedef struct _jmethodID *jmethodID; /* method IDs */

# The Value Type

The `jvalue` union type is used as the element type in argument arrays. It is declared as follows:

        typedef union jvalue {
            jboolean z;
            jbyte    b;
            jchar    c;
            jshort   s;
            jint     i;
            jlong    j;
            jfloat   f;
            jdouble  d;
            jobject  l;
        } jvalue;

# Type Signatures

The JNI uses the Java VM's representation of type signatures. Table 3-2 shows these type signatures.

  #### Table 3-2 Java VM Type Signatures

  Type Signature | Java Type
  --- | ---
  Z | boolean
  B | byte
  C | char
  S | short
  I | int
  J | long
  F | float
  D | double
  L fully-qualified-class ; | fully-qualified-class
  [ type | type[]
  ( arg-types ) ret-type | method type

For example, the Java method:

        long f (int n, String s, int[] arr);

has the following type signature:

        (ILjava/lang/String;[I)J

# UTF-8 Strings

The JNI uses UTF-8 strings to represent various string types. UTF-8 strings are the same as those used by the Java VM. UTF-8 strings are encoded so that character sequences that contain only nonnull ASCII characters can be represented using only one byte per character, but characters of up to 16 bits can be represented. All characters in the range `\u0001` to `\u007F` are represented by a single byte, as follows:

The seven bits of data in the byte give the value of the character that is represented. The null character (`\u000`) and characters in the range `\u0080 to \u07FF` are represented by a pair of bytes, x and y, as follows:

The bytes represent the character with the value `((x&0x1f)<<6)+(y&0x3f)`.

Characters in the range `\u0800` to `\uFFFF` are represented by three bytes, x, y, and z:

The character with the value `((x&0xf)<<12)+(y&0x3f)<<6)+(z&0x3f)` is represented by the three bytes.

There are two differences between this format and the "standard" UTF-8 format. First, the null byte `(byte)0` is encoded using the two-byte format rather than the one-byte format. This means that Java VM UTF-8 strings never have embedded nulls. Second, only the one-byte, two-byte, and three-byte formats are used. The Java VM does not recognize the longer UTF-8 formats.

Contents | Prev | Next

Java Native Interface Specification (HTML generated by dkramer on March 15, 1997)
Copyright © 1996, 1997 Sun Microsystems, Inc. All rights reserved
Please send any comments or corrections to jni@java.sun.com