KNI Scope

Chapter 3 KNI Scope

KNI is designed to be a logical subset of the Java Native Interface (JNI). The scope of KNI compared to JNI is presented in TABLE 1 below. For a summary of the JNI Scope, refer to the Java Native Interface Programmer’s Guide and Specification, pages 175–179.

TABLE 1 – JNI vs. KNI Scope
JNI Function Categories	Supported by KNI (YES/NO)
Version Information	YES
Class and Interface Operations	YES
Exceptions	YES
Global and Local References	NO
Object Operations	YES
Instance Field Access	YES
Static Field Access	YES
Instance Method Calls	NO
Static Method Calls	NO
String Operations	YES
Array Operations	YES
Native Method Registration	NO
Monitor Operations	NO
JavaVM Interface	NO
Reflection Support	NO

In addition, KNI introduces a set of new operations for method parameter (operand stack) access, and for manipulating handles to objects. These operations are KNI-specific and not available in the JNI.

Each of the supported function categories is introduced in more detail below. Note that the naming of these functions is different from JNI. Each function supported by the KNI uses a prefix “KNI_” in front of the function name.

3.1 Version Information

KNI_GetVersion function returns the version of the KNI interface.

3.2 Class and Interface Operations

KNI_FindClass returns a reference to a class or interface type of a given name.

KNI_GetSuperClass function returns the superclass of a given class or interface.

KNI_IsAssignableFrom function checks if an instance of one class or interface can be assigned to an instance of another class or interface. This function is useful for runtime type checking.

3.3 Exceptions

KNI_ThrowNew function raises an exception in the current thread.

KNI_FatalError function prints a descriptive message and terminates the current virtual machine instance.

3.4 Object Operations

KNI_GetObjectClass function returns the class of a given instance.

KNI_IsInstanceOf function checks whether an object is an instance of a given class or interface.

3.5 Instance Field Access

KNI_GetFieldID function performs a symbolic lookup on a given class and returns the field ID of a named instance field.

KNI_Get<Type>Field and KNI_Set<Type>Field functions access the instance fields of primitive or reference types.

3.6 Static Field Access

KNI_GetStaticFieldID function performs a symbolic lookup on a given class and returns the field ID of a named static field.

KNI_GetStatic<Type>Field and KNI_SetStatic<Type>Field functions access the static fields of primitive or reference types.

3.7 String Operations

KNI_GetStringLength function returns the number of Unicode characters in a string represented by a java.lang.String object.

KNI_GetStringRegion function provides access to the content of a java.lang.String object.

KNI_NewString function creates a java.lang.String object from the given Unicode string.

KNI_NewStringUTF function creates a java.lang.String object from the given UTF-8 string.

3.8 Array Operations

KNI_GetArrayLength function returns the number of elements in an array.

KNI_Get<Type>ArrayElement and KNI_Set<Type>ArrayElement functions allow a native method to access arrays elements of primitive or reference types.

KNI_GetRawArrayRegion and KNI_SetRawArrayRegion functions copy multiple elements in or out of arrays of primitive types.

3.9 Parameter (Operand Stack) Access

KNI_GetParameterAs<Type> functions allow a native method to access the method parameters (local variables) in the operand stack.

KNI_GetThisPointer function allows a non-static native method to access the ‘this’ pointer in the current stack frame.

KNI_GetClassPointer function allows a static native method to access the class pointer.

KNI_Return<Type> functions allow a native method to return a value of a primitive type.

3.10 Handle Operations

KNI_StartHandles function allocates space for a specified number of handles that can be used for holding object pointers inside a native function.

KNI_DeclareHandle function defines a local handle that can hold an object pointer inside a native function.

KNI_IsNullHandle function checks if a handle is null, i.e., not pointing to any object at the time.

KNI_IsSameObject function checks if two handles refer to the same object.

KNI_ReleaseHandle function sets the value of a handle to null.

KNI_EndHandles function undeclares and deallocates the handles that were allocated earlier by the matching KNI_StartHandles call.

KNI_EndHandlesAndReturnObject function undeclares and deallocates the handles that were allocated earlier by the matching KNI_StartHandles call, and returns a value of a reference type.

KNI Specification
K Native Interface (KNI), 1.0