Download Real Time Systems LAB. Calling Java Methods

JNI: Java Native Interface
October 31, 2001
Kyung-Yim, Kim
JNI: Java Native Interface
(1/32)
Real Time Systems LAB.
Agenda
• JNI Types and Functions
– Accessing Java Strings in Native methods
– Accessing Java Arrays in Native methods
– Calling Java Methods
• Conclusion
JNI: Java Native Interface
(2/32)
Real Time Systems LAB.
JNI Types and Functions
• Mapping between JNI and Native Types
– References Types
– Primitive Types and Native equivalents
– Encoding for Java Type signatures
• Handling Functions
–
–
–
–
–
–
JNI
JNI
JNI
JNI
JNI
JNI
String
Array
Method
Member Variable
Exception
Local and Global Reference
• JNI Thread Synchronization Functions
JNI: Java Native Interface
(3/32)
Real Time Systems LAB.
Mapping between JNI and Native Types(1)
• JNI References Types
JNI: Java Native Interface
(4/32)
Real Time Systems LAB.
Mapping between JNI and Native Types(2)
JNI: Java Native Interface
(5/32)
Real Time Systems LAB.
Mapping between JNI and Native Types(3)
JNI: Java Native Interface
(6/32)
Real Time Systems LAB.
Accessing Java Strings in Native methods
•
•
•
The JNI supports the conversion to...native Unicode and UTF-8 strings
If your code tries to print a jstring directly, it'll result in a VM crash!!!
JNI functions for Accessing Java Strings
– GetStringUTFChars
• converts unicode representation of a java string into a UTF-8 string,
• then can directly pass the string to regular C language functions, such as
“printf”
• In Java, UTF-8 strings are always 0 terminated
– ReleaseStringUTFChars
• When finish using the UTF-8 string, must call this function
• Then VM can free the memory taken by the UTF-8 string
– NewString
• Constructs a new java.lang.String object from an array of Unicode
characters
– GetStringUTFLength
• Returns the length of a string, represented in the UTF-8 format
JNI: Java Native Interface
(7/32)
Real Time Systems LAB.
Declaring Native Methods
• Declaring Native Methods
• Mapping Between Java and Native types
JNI: Java Native Interface
(8/32)
Real Time Systems LAB.
Using the JNIEnv Interface Pointer
• In native method, using the ‘env’ pointer to reference the
JNI function
• Access and manipulate Java objects, such as strings, throuth
the env interface pointer
JNI: Java Native Interface
(9/32)
Real Time Systems LAB.
JNI String Handling Functions
• GetStringChars : the Unicode
• GetStringUTFChars : the UTF-8 format
• GetStringLength
• GetStringUTFLength
• NewString
• NewStringUTF
• ReleaseStringChars
• ReleaseStringUTFChars
JNI: Java Native Interface
(10/32)
Real Time Systems LAB.
Example in Java side
JNI: Java Native Interface
(11/32)
Real Time Systems LAB.
Example in Native code side
JNI: Java Native Interface
(12/32)
Real Time Systems LAB.
Example in JNI header file
• Prompt.h
JNI: Java Native Interface
(13/32)
Real Time Systems LAB.
Accessing Java Arrays in Native methods(1)
•
The JNI uses the jarray type to represent references to Java arrays
•
Similar to jstring, can’t directly access jarray types in native method C code
•
JNI functions provide that to allow obtain pointers to the individual
elements of (integer…) arrays
– To get the length of the array (GetArrayLength)
– To obtain a pointer a pointer to the individual elements of the array, then,
can retrieve the elements (GetIntArrayElements)
– To release the array memory (ReleaseIntArrayElements)
JNI: Java Native Interface
(14/32)
Real Time Systems LAB.
Accessing Java Arrays in Native methods(2)
•
Get<type>Length
– To get the length of the array
– Carry length information of java arrays
•
Get<type>ArrayElements
– To obtain a pointer to the elements of the array
– Then, can retrieve the elements
– Once, obtain the pointer, can use normal C language operations
•
Release<type>ArrayElements
– To release array memory
•
Get<type>ArrayRegion & Set<type>ArrayRegion
– To accessing, via copying, a Small set of elements in an array
• GetObjectArrayElement & SetObjectArrayElement
– To access elements of object arrays
– To get & set individual object array elements
– Can’t get all the object array elements at once!!
JNI: Java Native Interface
(15/32)
Real Time Systems LAB.
JNI Array Handling Functions
• GetArrayLength
• Get<type>ArrayElements
–
–
–
–
–
–
–
–
GetBooleanArrayElements
GetByteArrayElements
GetCharArrayElements
GetDoubleArrayElements
GetFloatArrayElements
GetIntArrayElements
GetLongArrayElements
GetShortArrayElements
• Release<type>ArrayElements
• Get<type>ArrayRegion
• Set<type>ArrayRegion
• GetObjectArrayElement
• SetObjectArrayElement
JNI: Java Native Interface
(16/32)
Real Time Systems LAB.
Example in Java side
JNI: Java Native Interface
(17/32)
Real Time Systems LAB.
Example in Native code side
JNI: Java Native Interface
(18/32)
Real Time Systems LAB.
Calling Java Methods
• Shows calling native language functions from a Java applications
• Shows how a legacy C program can use the JNI to link with Java
libraries, call Java methods, use Java classes, etc
JNI: Java Native Interface
(19/32)
Real Time Systems LAB.
Calling a Java Method from Native Code
• The JNI supports a complete set of “callback” operations that allow
you to invoke a Java method from the Native code
– Locate the method using method name & method signature
– Can also invoke both class & instance methods
– Use the ‘javap’ tool to generate JNI style method signatures from class
files
JNI: Java Native Interface
(20/32)
Real Time Systems LAB.
Instance method invocation
•
Call an instance method by three steps
1.
JNI function “GetObjectClass”
•
2.
JNI function “GetMethodID”
•
•
•
3.
Returns the Java class object that’s the type of the Java object
Performs a lookup for the Java method in a given class
The lookup is based on the name of the method as well as the method
signature
If the method doesn’t exit, ‘GetMethodID’ returns ‘0’, immediately
return from the native method at that point causes a
‘NoSuchMethodError’ to be thrown in the Java application code
JNI function “CallVoidMethod”
•
•
Invokes an instance method that has ‘void’ return type,
pass the ‘object’, ‘methodID’, & the ‘actual arguments’ to
CallVoidMethod
JNI: Java Native Interface
(21/32)
Real Time Systems LAB.
Forming the Method Name and Method Signature(1)
• The JNI performs a symbolic lookup based on the methods’s name
& type signature
• Method type signature
– “(argument-types)return-type”
JNI: Java Native Interface
(22/32)
Real Time Systems LAB.
Forming the Method Name and Method Signature(2)
• Using ‘javap’ tool to Generate Method Signatures
– To print out member variables and method signatures for specified
classes
– ‘javap –s –p Prompt’
– ‘-s’ flag : to generate the member variable signatures from class
files
– ‘-p’ flag : to include private members
– The method name is the Java method name in UTF-8 form
– Specify the constructor of a class as “<init>”
JNI: Java Native Interface
(23/32)
Real Time Systems LAB.
JNI Method Handling Functions
•
•
•
•
GetObjectClass
GetMethodID
GetStaticMethodID
Call<returntype>Method
–
–
–
–
–
–
–
–
–
–
•
•
•
•
CallBooleanMethod
CallByteMethod
CallCharMethod
CallDoubleMethod
CallFloatMethod
CallIntMethod
CallLongMethod
CallObjectMethod
CallShortMethod
CallVoidMethod
CallStatic<returntype>Method
CallNonvirtual<returntype>Method
Call<returntype>MethodV
Call<returntype>MethodA
JNI: Java Native Interface
(24/32)
Real Time Systems LAB.
Example in Java side
• Accessing Java Member Variables
JNI: Java Native Interface
(25/32)
Real Time Systems LAB.
Example in Native code side(1)
• To ‘get’ & ‘set’ Java member variables from native language method
JNI: Java Native Interface
(26/32)
Real Time Systems LAB.
Example in Native code side(1)
• To ‘get’ & ‘set’ Java member variables from native language method
JNI: Java Native Interface
(27/32)
Real Time Systems LAB.
JNI Member Variable Handling Functions
• GetFieldID
• GetStaticFieldID
• Get<type>Field
–
–
–
–
–
–
–
–
–
GetBooleanField
GetByteField
GetCharField
GetDoubleField
GetFloatField
GetIntField
GetLongField
GetObjectField
GetShortField
• Set<type>Field
• GetStatic<type>Field
• SetStatic<type>Field
JNI: Java Native Interface
(28/32)
Real Time Systems LAB.
JNI Exception Handling Functions
• ExceptionClear
• ExceptionDescribe
• ExceptionOccurred
JNI: Java Native Interface
(29/32)
Real Time Systems LAB.
JNI Local and Global Reference Handling Functions
• NewGlobalRef
• DeleteGlobalRef
• DeleteLocalRef
JNI: Java Native Interface
(30/32)
Real Time Systems LAB.
JNI Thread Synchronization Functions
• MonitorEnter
• MonitorExit
JNI: Java Native Interface
(31/32)
Real Time Systems LAB.
Conclusion
• Consideration of JDK upper version’s JNI
improvements
• JNI Thread Synchronization
• Invoking the JVM into a native application
JNI: Java Native Interface
(32/32)
Real Time Systems LAB.