The Java Native InterfaceProgrammer’s Guide and Specification phần 10 pdf

JNI FUNCTIONS ReleaseArrayElements275 Linkage Indices in the JNIEnv interface function table.. ReleasePrimitiveArrayCritical JNI FUNCTIONSReleasePrimitiveArrayCritical jarray array, void

Trang 1

JNI FUNCTIONS Release<Type>ArrayElements

275

Linkage Indices in the JNIEnv interface function table.

Parameters env : the JNIEnv interface pointer.

array : a reference to an array object.

elems : a pointer to array elements.

mode : the release mode.

Trang 2

ReleasePrimitiveArrayCritical JNI FUNCTIONS

ReleasePrimitiveArrayCritical

jarray array, void *carray, jint mode);

Description Informs the virtual machine implementation that native code no

longer needs access to carray , the result of a previous

GetPrimitiveArrayCritical call If necessary, this function copies back all changes made to carray to the original array The mode argument provides information on how the array buffer should be released The mode argument has no effect if

carray is not a copy of the elements in array Otherwise, mode

has the following impact, as shown in the following table:

In most cases, programmers pass 0 to the mode argument to ensure consistent behavior for copied arrays The other options give the programmer more control over memory management and should be used with extreme care.

This function was introduced in Java 2 SDK release 1.2.

Linkage I ndex 223 in the JNIEnv interface function table.

array : a reference to an array object.

carray : a pointer to array elements.

mode : the release mode.

0 copy back and free the carray buffer

JNI_COMMIT copy back but do not free the carray buffer

JNI_ABORT free the buffer without copying back the

possible changes in the carray buffer

Trang 3

JNI FUNCTIONS ReleaseStringChars

277

ReleaseStringChars

jstring string, const jchar *chars);

longer needs access to chars The chars argument is a pointer obtained from string using GetStringChars

Linkage Index 166 in the JNIEnv interface function table.

string : a reference to a string object.

chars : a pointer to a Unicode string.

Trang 4

ReleaseStringCritical JNI FUNCTIONS

ReleaseStringCritical

jstring string, const jchar *carray);

longer needs access to carray The carray argument is a pointer obtained from string using GetStringCritical

In a code segment enclosed by GetStringCritical and

ReleaseStringCritical calls, native code must not issue trary JNI calls or cause the current thread to block and wait for another thread in the virtual machine instance.

arbi-This function was introduced in Java 2 SDK release 1.2.

chars : a pointer to a Unicode string.

Trang 5

JNI FUNCTIONS ReleaseStringUTFChars

279

ReleaseStringUTFChars

jstring string, const char *utf);

longer needs access to the native string utf The utf argument

is a pointer derived from string using GetStringUTFChars

utf : a pointer to a UTF-8 string.

Trang 6

Set<Type>ArrayRegion JNI FUNCTIONS

Set<Type>ArrayRegion

Prototype void Set<Type>ArrayRegion(JNIEnv *env,

<ArrayType> array, jsize start, jsize len, <NativeType> *buf);

Forms This family of functions consists of eight members.

Description Copies back a region of a primitive array from a buffer The

array reference and buf buffer must not be NULL

Set<Type>ArrayRegion <ArrayType> <NativeType>

Trang 7

JNI FUNCTIONS Set<Type>ArrayRegion

281

array : a reference to a primitive array to which the elements are copied.

start : the starting index in the primitive array.

len : the number of elements to be copied.

buf : the source buffer.

Exceptions ArrayIndexOutOfBoundsException : if one of the indices in

the region is not valid.

Trang 8

Set<Type>Field JNI FUNCTIONS

Set<Type>Field

Prototype void Set<Type>Field(JNIEnv *env, jobject obj,

jfieldID fieldID, <NativeType> value);

Forms This family of functions consists of nine members.

Description Sets the value of an instance field of an object The obj

refer-ence must not be NULL

Trang 9

JNI FUNCTIONS Set<Type>Field

283

obj : a reference to an object.

fieldID : a field ID.

value : the new value of the field.

Trang 10

SetObjectArrayElement JNI FUNCTIONS

SetObjectArrayElement

jobjectArray array, jsize index, jobject value);

Description Sets an element of an Object array The array reference must

not be NULL

array : a reference to an array whose element will be accessed.

index : index of the array element to be accessed.

value : the new value of the array element.

Exceptions ArrayIndexOutOfBoundsException : if index does not specify

a valid index in the array.

ArrayStoreException : if the class of value is not a subclass

of the element class of the array.

Trang 11

JNI FUNCTIONS SetStatic<Type>Field

285

SetStatic<Type>Field

Prototype void SetStatic<Type>Field(JNIEnv *env,

jclass clazz, jfieldID fieldID,

<NativeType> value);

Forms This family of functions consists of nine members.

Description Sets the value of a static field of a class or interface The field to

access is specified by a field ID.

Trang 12

SetStatic<Type>Field JNI FUNCTIONS

clazz : a reference to a class or interface whose static field will

be accessed.

fieldID : an ID denoting the static field to be accessed.

value : the new value of the field.

Trang 13

JNI FUNCTIONS Throw

287

Throw

Description Causes a java.lang.Throwable object to be thrown A thrown

exception will be pending in the current thread, but does not immediately disrupt native code execution.

obj : a java.lang.Throwable object.

Return Values Returns zero on success; otherwise, returns a negative value.

Exceptions The given java.lang.Throwable object.

Trang 14

ThrowNew JNI FUNCTIONS

ThrowNew

const char *message);

Description Constructs an exception object from the specified class with the

message specified by message and causes that exception to be thrown.

clazz : a subclass of java.lang.Throwable

message : the message used to construct the able object.

java.lang.Throw-Return Values Returns zero on success; otherwise, returns a negative value if

the specified exception cannot be thrown.

Exceptions The newly constructed java.lang.Throwable object, or any

exception that occurs in constructing this object.

Trang 15

JNI FUNCTIONS ToReflectedField

289

ToReflectedField

jfieldID fieldID, jboolean isStatic);

Description Converts a field ID derived from cls to an instance of the

java.lang.reflect.Field class.

cls : a reference to a class or interface.

fieldID : a JNI field ID.

isStatic : whether the field ID denotes a static field.

Return Values Returns an instance of the java.lang.reflect.Field class;

otherwise, returns NULL Returns NULL if and only if an tion of this function has thrown an exception.

invoca-Exceptions OutofMemoryError : if the system runs out of memory.

Trang 16

ToReflectedMethod JNI FUNCTIONS

ToReflectedMethod

jmethodID methodID, jboolean isStatic);

Description Converts a method ID derived from cls to an instance of the

java.lang.reflect.Method class or to an instance of the

java.lang.reflect.Constructor class.

cls : a reference to a class or interface.

methodID : a method ID.

isStatic: whether the method ID refers to a static method.

Return Values Returns an instance of the java.lang.reflect.Method class

or an instance of the java.lang.reflect.Constructor class; otherwise, returns NULL Returns NULL if and only if an invocation of this function has thrown an exception.

Exceptions OutofMemoryError : if the system runs out of memory.

Trang 17

JNI FUNCTIONS UnregisterNatives

291

UnregisterNatives

Description Unregisters native methods of a class The class goes back to

the state before it was linked or registered with its native method functions.

This function should not be used in normal native code Instead,

it provides special programs a way to reload and relink native libraries.

clazz : a reference to a class object whose native methods are to

be unregistered.

Return Values Returns zero on success; otherwise, returns a negative value.

Trang 19

function summary, 35 multi-dimensional, 39 object vs primitive, 33 simultaneous access, 160

calling convention, 153 programming language, 3

C shell, 17 C++

programming language, 3 programming the JNI in, 106 virtual function table, 153

caching field and method IDs, 53

at point of use, 53

in defining class, 56 needed for correctness, 135

Call<Type>Method, 47, 184 Call<Type>MethodA, 186 Call<Type>MethodV, 188

Trang 21

ClassCircularityError, 202, 215

classes, 4, 23

descriptors, 169 load through the JNI, 39

code examples

atol, 109attach.c, 89CacheThrow, 73CFunction, 118CMalloc, 117CPointer, 117HelloWorld, 11InstanceFieldAccess, 42, 54InstanceMethodCall, 46, 57IntArray, 33, 34, 35invoke.c, 83KeyInput, 127MyNewString, 51, 55, 62, 64, 71ObjectArrayTest, 38

Prompt, 21, 25, 29StaticFieldAccess, 45StaticMethodCall, 50 web download address, 9Win32.CreateFile, 111, 115

CreateFileA andCreateFileW, 115

Trang 22

in utility functions, 79 pending, 25, 75, 162

fields

accessing, 41 accessing static vs instance, 46 descriptor

See field descriptors

instance

See instance fields

name, 43 static

See static fields

Get<Type>ArrayElements, 35, 36, 219 Get<Type>ArrayRegion, 36, 221 Get<Type>Field, 223

Trang 23

See also Java platform

HTTP server, 89

I IDs vs references, 134

steps for calling, 47

InstanceFieldAccess example, 42, 54

InstanceMethodCall example, 46, 57 instances, 23

virtual machine, 173

InstantiationException, 181, 262, 263, 264

int, 23, 165

IntArray example, 33, 34, 35 interfaces

calling methods, 47 obtaining, 48

internationalized code, 99, 138 invocation interface, 5, 83

Trang 24

J

jarray, 166, 167

Java 2 SDK, 8 Java API

See Java Application Programming

Inter-face

Java application, 4

See also native application

Java Application Programming Interface, 4 Java Core Reflection API, 161

Java Development Kit, 7 Java Native Interface, 3

alternative solutions, 6 benefits, 8

design goals, 145 function table, 22 functions, 22 implications of using, 6 performance characteristics, 58 role of, 4

version evolution, 155, 179 when to use, 6

Java platform, 4

See also host environment

Java programming language, 3 Java Runtime Environment, 4

java runtime interpreter, 11, 83 Java virtual machine, 4

JavaVMAttachArgs, 182

JavaVMInitArgs, 85

JavaVMOption, 85

jboolean, 165 accidentally truncated, 132

See Java Native Interface

jni.h header file, 15, 165

JNI_ABORT constant, 171, 276

JNI_AttachCurrentThread, 92

Trang 25

See also-verbose:jni option freeing, 67

how to implement, 157 how to invalidate, 63 registry, 157 thread-local, 94 validity of, 141

Trang 26

memory leaks, 67 method descriptors, 48, 170

javap -s, 49

method IDs, 160, 168

caching, 53, 135 resolving, 160

methods

calling, 46 descriptor

See method descriptors

in superclasses, 51 instance

See instance methods

static

See static methods

Microsoft COM interface, 154, 174, 175 Microsoft Visual C++ compiler, 16

MonitorEnter, 94, 258

monitorenter instruction, 258, 259

MonitorExit, 94, 259

monitorexit instruction, 258 monitors, 94

msvcrt.dll, 113

mutex_lock, 97

MyNewString example, 51, 55, 62, 64, 71

N name encoding

long, 117, 152 short, 152

namespaces, 146 native application, 4

See also Java application

native code, 3

See also C, C++

native library, 5

creation, 15 loading, 146 shared library, 16 unloading, 151

native library path

See also-Djava.library.pathsetting, 16

registering, 101 steps in writing and running, 11

native method interface, 7

See also Java Native Interface

compatibility among releases, 8 problems in JDK 1.0, 7

native modifier, 13 native programming languages, 4 native thread model, 97

Trang 27

performance of JNI operations

accessing primitive arrays, 158 efficiency goal, 146

field access, 59 method call, 58

in caching field and method IDs, 54

in freeing native peers, 125

reference types, 166

references

comparing, 66 freeing, 66 global

See global references

local

See local references

opaque, 23, 156 rules for managing, 70 weak global

See weak global references

reflection, 105, 161

RegisterNatives, 101, 153, 273 uses of, 102

registry of local references, 157

Trang 28

native threads, 141 shared library, 16

Solaris C compiler, 16 standard shell, 17 static fields, 41

accessing, 44

static initializer, 13

invoked byFindClass, 214GetFieldID, 226GetMethodID, 228

static methods, 46

native, 23 steps in calling, 49

freeing resources, 25NULL-terminated C, 24 summary of functions, 29 Unicode, 24

UTF-8, 24, 168

Stroustrup, Bjarne, 4 stub functions, 112 subtyping, 106, 166 synchronization

in peer classes, 125

synchronized blocks, 94

System.loadLibrary, 101, 148 how to use, 13

Trang 29

303

threads, 93

constraints on programming, 93 thread-localJNIEnv, 153 validity of local references, 64

JNU_GetStringNativeChars, 100JNU_MonitorNotify, 96

JNU_MonitorNotifyAll, 96JNU_MonitorWait, 96JNU_NewStringNative, 99JNU_ThrowByName, 75

Win32

CreateFile API, 110 dynamic link library, 16

Win32.CreateFile example, 111, 115 wrapper classes, 109

X

-Xcheck:jni option, 131, 155

-Xmx option, 85

Tiêu đề	The Java Native Interface Programmer’s Guide and Specification phần 10
Trường học	University of Java Programming
Chuyên ngành	Computer Science
Thể loại	Hướng dẫn
Năm xuất bản	2002
Thành phố	New York

Định dạng
Số trang	30
Dung lượng	1,36 MB