1 page.title=JNI Tips 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7 <h2>In this document</h2> 8 <ol> 9 <li><a href="#JavaVM_and_JNIEnv">JavaVM and JNIEnv</a></li> 10 <li><a href="#threads">Threads</a></li> 11 <li><a href="#jclass_jmethodID_and_jfieldID">jclass, jmethodID, and jfieldID</a></li> 12 <li><a href="#local_and_global_references">Local and Global References</a></li> 13 <li><a href="#UTF_8_and_UTF_16_strings">UTF-8 and UTF-16 Strings</a></li> 14 <li><a href="#arrays">Primitive Arrays</a></li> 15 <li><a href="#region_calls">Region Calls</a></li> 16 <li><a href="#exceptions">Exceptions</a></li> 17 <li><a href="#extended_checking">Extended Checking</a> </li> 18 <li><a href="#native_libraries">Native Libraries</a></li> 19 <li><a href="#64_bit">64-bit Considerations</a></li> 20 <li><a href="#unsupported">Unsupported Features/Backwards Compatibility</a></li> 21 <li><a href="#faq_ULE">FAQ: Why do I get <code>UnsatisfiedLinkError</code></a></li> 22 <li><a href="#faq_FindClass">FAQ: Why didn't <code>FindClass</code> find my class?</a></li> 23 <li><a href="#faq_sharing">FAQ: How do I share raw data with native code?</a></li> 24 </ol> 25 26 </div> 27 </div> 28 29 <p>JNI is the Java Native Interface. It defines a way for managed code 30 (written in the Java programming language) to interact with native 31 code (written in C/C++). It's vendor-neutral, has support for loading code from 32 dynamic shared libraries, and while cumbersome at times is reasonably efficient.</p> 33 34 <p>You really should read through the 35 <a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html">JNI spec for J2SE 6</a> 36 to get a sense for how JNI works and what features are available. Some 37 aspects of the interface aren't immediately obvious on 38 first reading, so you may find the next few sections handy. 39 There's a more detailed <a href="http://java.sun.com/docs/books/jni/html/jniTOC.html">JNI Programmer's Guide and Specification</a>.</p> 40 41 42 <a name="JavaVM_and_JNIEnv" id="JavaVM_and_JNIEnv"></a> 43 <h2>JavaVM and JNIEnv</h2> 44 45 <p>JNI defines two key data structures, "JavaVM" and "JNIEnv". Both of these are essentially 46 pointers to pointers to function tables. (In the C++ version, they're classes with a 47 pointer to a function table and a member function for each JNI function that indirects through 48 the table.) The JavaVM provides the "invocation interface" functions, 49 which allow you to create and destroy a JavaVM. In theory you can have multiple JavaVMs per process, 50 but Android only allows one.</p> 51 52 <p>The JNIEnv provides most of the JNI functions. Your native functions all receive a JNIEnv as 53 the first argument.</p> 54 55 <p>The JNIEnv is used for thread-local storage. For this reason, <strong>you cannot share a JNIEnv between threads</strong>. 56 If a piece of code has no other way to get its JNIEnv, you should share 57 the JavaVM, and use <code>GetEnv</code> to discover the thread's JNIEnv. (Assuming it has one; see <code>AttachCurrentThread</code> below.)</p> 58 59 <p>The C declarations of JNIEnv and JavaVM are different from the C++ 60 declarations. The <code>"jni.h"</code> include file provides different typedefs 61 depending on whether it's included into C or C++. For this reason it's a bad idea to 62 include JNIEnv arguments in header files included by both languages. (Put another way: if your 63 header file requires <code>#ifdef __cplusplus</code>, you may have to do some extra work if anything in 64 that header refers to JNIEnv.)</p> 65 66 <a name="threads" id="threads"></a> 67 <h2>Threads</h2> 68 69 <p>All threads are Linux threads, scheduled by the kernel. They're usually 70 started from managed code (using <code>Thread.start</code>), 71 but they can also be created elsewhere and then attached to the JavaVM. For 72 example, a thread started with <code>pthread_create</code> can be attached 73 with the JNI <code>AttachCurrentThread</code> or 74 <code>AttachCurrentThreadAsDaemon</code> functions. Until a thread is 75 attached, it has no JNIEnv, and <strong>cannot make JNI calls</strong>.</p> 76 77 <p>Attaching a natively-created thread causes a <code>java.lang.Thread</code> 78 object to be constructed and added to the "main" <code>ThreadGroup</code>, 79 making it visible to the debugger. Calling <code>AttachCurrentThread</code> 80 on an already-attached thread is a no-op.</p> 81 82 <p>Android does not suspend threads executing native code. If 83 garbage collection is in progress, or the debugger has issued a suspend 84 request, Android will pause the thread the next time it makes a JNI call.</p> 85 86 <p>Threads attached through JNI <strong>must call 87 <code>DetachCurrentThread</code> before they exit</strong>. 88 If coding this directly is awkward, in Android 2.0 (Eclair) and higher you 89 can use <code>pthread_key_create</code> to define a destructor 90 function that will be called before the thread exits, and 91 call <code>DetachCurrentThread</code> from there. (Use that 92 key with <code>pthread_setspecific</code> to store the JNIEnv in 93 thread-local-storage; that way it'll be passed into your destructor as 94 the argument.)</p> 95 96 97 <a name="jclass_jmethodID_and_jfieldID" id="jclass_jmethodID_and_jfieldID"></a> 98 <h2>jclass, jmethodID, and jfieldID</h2> 99 100 <p>If you want to access an object's field from native code, you would do the following:</p> 101 102 <ul> 103 <li> Get the class object reference for the class with <code>FindClass</code></li> 104 <li> Get the field ID for the field with <code>GetFieldID</code></li> 105 <li> Get the contents of the field with something appropriate, such as 106 <code>GetIntField</code></li> 107 </ul> 108 109 <p>Similarly, to call a method, you'd first get a class object reference and then a method ID. The IDs are often just 110 pointers to internal runtime data structures. Looking them up may require several string 111 comparisons, but once you have them the actual call to get the field or invoke the method 112 is very quick.</p> 113 114 <p>If performance is important, it's useful to look the values up once and cache the results 115 in your native code. Because there is a limit of one JavaVM per process, it's reasonable 116 to store this data in a static local structure.</p> 117 118 <p>The class references, field IDs, and method IDs are guaranteed valid until the class is unloaded. Classes 119 are only unloaded if all classes associated with a ClassLoader can be garbage collected, 120 which is rare but will not be impossible in Android. Note however that 121 the <code>jclass</code> 122 is a class reference and <strong>must be protected</strong> with a call 123 to <code>NewGlobalRef</code> (see the next section).</p> 124 125 <p>If you would like to cache the IDs when a class is loaded, and automatically re-cache them 126 if the class is ever unloaded and reloaded, the correct way to initialize 127 the IDs is to add a piece of code that looks like this to the appropriate class:</p> 128 129 <pre> /* 130 * We use a class initializer to allow the native code to cache some 131 * field offsets. This native function looks up and caches interesting 132 * class/field/method IDs. Throws on failure. 133 */ 134 private static native void nativeInit(); 135 136 static { 137 nativeInit(); 138 }</pre> 139 140 <p>Create a <code>nativeClassInit</code> method in your C/C++ code that performs the ID lookups. The code 141 will be executed once, when the class is initialized. If the class is ever unloaded and 142 then reloaded, it will be executed again.</p> 143 144 <a name="local_and_global_references" id="local_and_global_references"></a> 145 <h2>Local and Global References</h2> 146 147 <p>Every argument passed to a native method, and almost every object returned 148 by a JNI function is a "local reference". This means that it's valid for the 149 duration of the current native method in the current thread. 150 <strong>Even if the object itself continues to live on after the native method 151 returns, the reference is not valid.</strong> 152 <p>This applies to all sub-classes of <code>jobject</code>, including 153 <code>jclass</code>, <code>jstring</code>, and <code>jarray</code>. 154 (The runtime will warn you about most reference mis-uses when extended JNI 155 checks are enabled.)</p> 156 <p>The only way to get non-local references is via the functions 157 <code>NewGlobalRef</code> and <code>NewWeakGlobalRef</code>. 158 159 <p>If you want to hold on to a reference for a longer period, you must use 160 a "global" reference. The <code>NewGlobalRef</code> function takes the 161 local reference as an argument and returns a global one. 162 The global reference is guaranteed to be valid until you call 163 <code>DeleteGlobalRef</code>.</p> 164 165 <p>This pattern is commonly used when caching a jclass returned 166 from <code>FindClass</code>, e.g.:</p> 167 <pre>jclass localClass = env->FindClass("MyClass"); 168 jclass globalClass = reinterpret_cast<jclass>(env->NewGlobalRef(localClass));</pre> 169 170 <p>All JNI methods accept both local and global references as arguments. 171 It's possible for references to the same object to have different values. 172 For example, the return values from consecutive calls to 173 <code>NewGlobalRef</code> on the same object may be different. 174 <strong>To see if two references refer to the same object, 175 you must use the <code>IsSameObject</code> function.</strong> Never compare 176 references with <code>==</code> in native code.</p> 177 178 <p>One consequence of this is that you 179 <strong>must not assume object references are constant or unique</strong> 180 in native code. The 32-bit value representing an object may be different 181 from one invocation of a method to the next, and it's possible that two 182 different objects could have the same 32-bit value on consecutive calls. Do 183 not use <code>jobject</code> values as keys.</p> 184 185 <p>Programmers are required to "not excessively allocate" local references. In practical terms this means 186 that if you're creating large numbers of local references, perhaps while running through an array of 187 objects, you should free them manually with 188 <code>DeleteLocalRef</code> instead of letting JNI do it for you. The 189 implementation is only required to reserve slots for 190 16 local references, so if you need more than that you should either delete as you go or use 191 <code>EnsureLocalCapacity</code>/<code>PushLocalFrame</code> to reserve more.</p> 192 193 <p>Note that <code>jfieldID</code>s and <code>jmethodID</code>s are opaque 194 types, not object references, and should not be passed to 195 <code>NewGlobalRef</code>. The raw data 196 pointers returned by functions like <code>GetStringUTFChars</code> 197 and <code>GetByteArrayElements</code> are also not objects. (They may be passed 198 between threads, and are valid until the matching Release call.)</p> 199 200 <p>One unusual case deserves separate mention. If you attach a native 201 thread with <code>AttachCurrentThread</code>, the code you are running will 202 never automatically free local references until the thread detaches. Any local 203 references you create will have to be deleted manually. In general, any native 204 code that creates local references in a loop probably needs to do some manual 205 deletion.</p> 206 207 <a name="UTF_8_and_UTF_16_strings" id="UTF_8_and_UTF_16_strings"></a> 208 <h2>UTF-8 and UTF-16 Strings</h2> 209 210 <p>The Java programming language uses UTF-16. For convenience, JNI provides methods that work with <a href="http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8">Modified UTF-8</a> as well. The 211 modified encoding is useful for C code because it encodes \u0000 as 0xc0 0x80 instead of 0x00. 212 The nice thing about this is that you can count on having C-style zero-terminated strings, 213 suitable for use with standard libc string functions. The down side is that you cannot pass 214 arbitrary UTF-8 data to JNI and expect it to work correctly.</p> 215 216 <p>If possible, it's usually faster to operate with UTF-16 strings. Android 217 currently does not require a copy in <code>GetStringChars</code>, whereas 218 <code>GetStringUTFChars</code> requires an allocation and a conversion to 219 UTF-8. Note that 220 <strong>UTF-16 strings are not zero-terminated</strong>, and \u0000 is allowed, 221 so you need to hang on to the string length as well as 222 the jchar pointer.</p> 223 224 <p><strong>Don't forget to <code>Release</code> the strings you <code>Get</code></strong>. The 225 string functions return <code>jchar*</code> or <code>jbyte*</code>, which 226 are C-style pointers to primitive data rather than local references. They 227 are guaranteed valid until <code>Release</code> is called, which means they are not 228 released when the native method returns.</p> 229 230 <p><strong>Data passed to NewStringUTF must be in Modified UTF-8 format</strong>. A 231 common mistake is reading character data from a file or network stream 232 and handing it to <code>NewStringUTF</code> without filtering it. 233 Unless you know the data is 7-bit ASCII, you need to strip out high-ASCII 234 characters or convert them to proper Modified UTF-8 form. If you don't, 235 the UTF-16 conversion will likely not be what you expect. The extended 236 JNI checks will scan strings and warn you about invalid data, but they 237 won't catch everything.</p> 238 239 <a name="arrays" id="arrays"></a> 240 <h2>Primitive Arrays</h2> 241 242 <p>JNI provides functions for accessing the contents of array objects. 243 While arrays of objects must be accessed one entry at a time, arrays of 244 primitives can be read and written directly as if they were declared in C.</p> 245 246 <p>To make the interface as efficient as possible without constraining 247 the VM implementation, the <code>Get<PrimitiveType>ArrayElements</code> 248 family of calls allows the runtime to either return a pointer to the actual elements, or 249 allocate some memory and make a copy. Either way, the raw pointer returned 250 is guaranteed to be valid until the corresponding <code>Release</code> call 251 is issued (which implies that, if the data wasn't copied, the array object 252 will be pinned down and can't be relocated as part of compacting the heap). 253 <strong>You must <code>Release</code> every array you <code>Get</code>.</strong> Also, if the <code>Get</code> 254 call fails, you must ensure that your code doesn't try to <code>Release</code> a NULL 255 pointer later.</p> 256 257 <p>You can determine whether or not the data was copied by passing in a 258 non-NULL pointer for the <code>isCopy</code> argument. This is rarely 259 useful.</p> 260 261 <p>The <code>Release</code> call takes a <code>mode</code> argument that can 262 have one of three values. The actions performed by the runtime depend upon 263 whether it returned a pointer to the actual data or a copy of it:</p> 264 265 <ul> 266 <li><code>0</code> 267 <ul> 268 <li>Actual: the array object is un-pinned. 269 <li>Copy: data is copied back. The buffer with the copy is freed. 270 </ul> 271 <li><code>JNI_COMMIT</code> 272 <ul> 273 <li>Actual: does nothing. 274 <li>Copy: data is copied back. The buffer with the copy 275 <strong>is not freed</strong>. 276 </ul> 277 <li><code>JNI_ABORT</code> 278 <ul> 279 <li>Actual: the array object is un-pinned. Earlier 280 writes are <strong>not</strong> aborted. 281 <li>Copy: the buffer with the copy is freed; any changes to it are lost. 282 </ul> 283 </ul> 284 285 <p>One reason for checking the <code>isCopy</code> flag is to know if 286 you need to call <code>Release</code> with <code>JNI_COMMIT</code> 287 after making changes to an array — if you're alternating between making 288 changes and executing code that uses the contents of the array, you may be 289 able to 290 skip the no-op commit. Another possible reason for checking the flag is for 291 efficient handling of <code>JNI_ABORT</code>. For example, you might want 292 to get an array, modify it in place, pass pieces to other functions, and 293 then discard the changes. If you know that JNI is making a new copy for 294 you, there's no need to create another "editable" copy. If JNI is passing 295 you the original, then you do need to make your own copy.</p> 296 297 <p>It is a common mistake (repeated in example code) to assume that you can skip the <code>Release</code> call if 298 <code>*isCopy</code> is false. This is not the case. If no copy buffer was 299 allocated, then the original memory must be pinned down and can't be moved by 300 the garbage collector.</p> 301 302 <p>Also note that the <code>JNI_COMMIT</code> flag does <strong>not</strong> release the array, 303 and you will need to call <code>Release</code> again with a different flag 304 eventually.</p> 305 306 307 <a name="region_calls" id="region_calls"></a> 308 <h2>Region Calls</h2> 309 310 <p>There is an alternative to calls like <code>Get<Type>ArrayElements</code> 311 and <code>GetStringChars</code> that may be very helpful when all you want 312 to do is copy data in or out. Consider the following:</p> 313 314 <pre> jbyte* data = env->GetByteArrayElements(array, NULL); 315 if (data != NULL) { 316 memcpy(buffer, data, len); 317 env->ReleaseByteArrayElements(array, data, JNI_ABORT); 318 }</pre> 319 320 <p>This grabs the array, copies the first <code>len</code> byte 321 elements out of it, and then releases the array. Depending upon the 322 implementation, the <code>Get</code> call will either pin or copy the array 323 contents. 324 The code copies the data (for perhaps a second time), then calls <code>Release</code>; in this case 325 <code>JNI_ABORT</code> ensures there's no chance of a third copy.</p> 326 327 <p>One can accomplish the same thing more simply:</p> 328 <pre> env->GetByteArrayRegion(array, 0, len, buffer);</pre> 329 330 <p>This has several advantages:</p> 331 <ul> 332 <li>Requires one JNI call instead of 2, reducing overhead. 333 <li>Doesn't require pinning or extra data copies. 334 <li>Reduces the risk of programmer error — no risk of forgetting 335 to call <code>Release</code> after something fails. 336 </ul> 337 338 <p>Similarly, you can use the <code>Set<Type>ArrayRegion</code> call 339 to copy data into an array, and <code>GetStringRegion</code> or 340 <code>GetStringUTFRegion</code> to copy characters out of a 341 <code>String</code>. 342 343 344 <a name="exceptions" id="exceptions"></a> 345 <h2>Exceptions</h2> 346 347 <p><strong>You must not call most JNI functions while an exception is pending.</strong> 348 Your code is expected to notice the exception (via the function's return value, 349 <code>ExceptionCheck</code>, or <code>ExceptionOccurred</code>) and return, 350 or clear the exception and handle it.</p> 351 352 <p>The only JNI functions that you are allowed to call while an exception is 353 pending are:</p> 354 <ul> 355 <li><code>DeleteGlobalRef</code> 356 <li><code>DeleteLocalRef</code> 357 <li><code>DeleteWeakGlobalRef</code> 358 <li><code>ExceptionCheck</code> 359 <li><code>ExceptionClear</code> 360 <li><code>ExceptionDescribe</code> 361 <li><code>ExceptionOccurred</code> 362 <li><code>MonitorExit</code> 363 <li><code>PopLocalFrame</code> 364 <li><code>PushLocalFrame</code> 365 <li><code>Release<PrimitiveType>ArrayElements</code> 366 <li><code>ReleasePrimitiveArrayCritical</code> 367 <li><code>ReleaseStringChars</code> 368 <li><code>ReleaseStringCritical</code> 369 <li><code>ReleaseStringUTFChars</code> 370 </ul> 371 372 <p>Many JNI calls can throw an exception, but often provide a simpler way 373 of checking for failure. For example, if <code>NewString</code> returns 374 a non-NULL value, you don't need to check for an exception. However, if 375 you call a method (using a function like <code>CallObjectMethod</code>), 376 you must always check for an exception, because the return value is not 377 going to be valid if an exception was thrown.</p> 378 379 <p>Note that exceptions thrown by interpreted code do not unwind native stack 380 frames, and Android does not yet support C++ exceptions. 381 The JNI <code>Throw</code> and <code>ThrowNew</code> instructions just 382 set an exception pointer in the current thread. Upon returning to managed 383 from native code, the exception will be noted and handled appropriately.</p> 384 385 <p>Native code can "catch" an exception by calling <code>ExceptionCheck</code> or 386 <code>ExceptionOccurred</code>, and clear it with 387 <code>ExceptionClear</code>. As usual, 388 discarding exceptions without handling them can lead to problems.</p> 389 390 <p>There are no built-in functions for manipulating the <code>Throwable</code> object 391 itself, so if you want to (say) get the exception string you will need to 392 find the <code>Throwable</code> class, look up the method ID for 393 <code>getMessage "()Ljava/lang/String;"</code>, invoke it, and if the result 394 is non-NULL use <code>GetStringUTFChars</code> to get something you can 395 hand to <code>printf(3)</code> or equivalent.</p> 396 397 398 <a name="extended_checking" id="extended_checking"></a> 399 <h2>Extended Checking</h2> 400 401 <p>JNI does very little error checking. Errors usually result in a crash. Android also offers a mode called CheckJNI, where the JavaVM and JNIEnv function table pointers are switched to tables of functions that perform an extended series of checks before calling the standard implementation.</p> 402 403 <p>The additional checks include:</p> 404 405 <ul> 406 <li>Arrays: attempting to allocate a negative-sized array.</li> 407 <li>Bad pointers: passing a bad jarray/jclass/jobject/jstring to a JNI call, or passing a NULL pointer to a JNI call with a non-nullable argument.</li> 408 <li>Class names: passing anything but the java/lang/String style of class name to a JNI call.</li> 409 <li>Critical calls: making a JNI call between a critical get and its corresponding release.</li> 410 <li>Direct ByteBuffers: passing bad arguments to <code>NewDirectByteBuffer</code>.</li> 411 <li>Exceptions: making a JNI call while theres an exception pending.</li> 412 <li>JNIEnv*s: using a JNIEnv* from the wrong thread.</li> 413 <li>jfieldIDs: using a NULL jfieldID, or using a jfieldID to set a field to a value of the wrong type (trying to assign a StringBuilder to a String field, say), or using a jfieldID for a static field to set an instance field or vice versa, or using a jfieldID from one class with instances of another class.</li> 414 <li>jmethodIDs: using the wrong kind of jmethodID when making a <code>Call*Method</code> JNI call: incorrect return type, static/non-static mismatch, wrong type for this (for non-static calls) or wrong class (for static calls).</li> 415 <li>References: using <code>DeleteGlobalRef</code>/<code>DeleteLocalRef</code> on the wrong kind of reference.</li> 416 <li>Release modes: passing a bad release mode to a release call (something other than <code>0</code>, <code>JNI_ABORT</code>, or <code>JNI_COMMIT</code>).</li> 417 <li>Type safety: returning an incompatible type from your native method (returning a StringBuilder from a method declared to return a String, say).</li> 418 <li>UTF-8: passing an invalid <a href="http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8">Modified UTF-8</a> byte sequence to a JNI call.</li> 419 </ul> 420 421 <p>(Accessibility of methods and fields is still not checked: access restrictions don't apply to native code.)</p> 422 423 <p>There are several ways to enable CheckJNI.</p> 424 425 <p>If youre using the emulator, CheckJNI is on by default.</p> 426 427 <p>If you have a rooted device, you can use the following sequence of commands to restart the runtime with CheckJNI enabled:</p> 428 429 <pre>adb shell stop 430 adb shell setprop dalvik.vm.checkjni true 431 adb shell start</pre> 432 433 <p>In either of these cases, youll see something like this in your logcat output when the runtime starts:</p> 434 435 <pre>D AndroidRuntime: CheckJNI is ON</pre> 436 437 <p>If you have a regular device, you can use the following command:</p> 438 439 <pre>adb shell setprop debug.checkjni 1</pre> 440 441 <p>This wont affect already-running apps, but any app launched from that point on will have CheckJNI enabled. (Change the property to any other value or simply rebooting will disable CheckJNI again.) In this case, youll see something like this in your logcat output the next time an app starts:</p> 442 443 <pre>D Late-enabling CheckJNI</pre> 444 445 446 447 448 <a name="native_libraries" id="native_libraries"></a> 449 <h2>Native Libraries</h2> 450 451 <p>You can load native code from shared libraries with the standard 452 <code>System.loadLibrary</code> call. The 453 preferred way to get at your native code is:</p> 454 455 <ul> 456 <li> Call <code>System.loadLibrary</code> from a static class 457 initializer. (See the earlier example, where one is used to call 458 <code>nativeClassInit</code>.) The argument is the "undecorated" 459 library name, so to load "libfubar.so" you would pass in "fubar".</li> 460 <li> Provide a native function: <code><strong>jint JNI_OnLoad(JavaVM* vm, void* reserved)</strong></code></li> 461 <li>In <code>JNI_OnLoad</code>, register all of your native methods. You 462 should declare 463 the methods "static" so the names don't take up space in the symbol table 464 on the device.</li> 465 </ul> 466 467 <p>The <code>JNI_OnLoad</code> function should look something like this if 468 written in C++:</p> 469 <pre>jint JNI_OnLoad(JavaVM* vm, void* reserved) 470 { 471 JNIEnv* env; 472 if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) { 473 return -1; 474 } 475 476 // Get jclass with env->FindClass. 477 // Register methods with env->RegisterNatives. 478 479 return JNI_VERSION_1_6; 480 }</pre> 481 482 <p>You can also call <code>System.load</code> with the full path name of the 483 shared library. For Android apps, you may find it useful to get the full 484 path to the application's private data storage area from the context object.</p> 485 486 <p>This is the recommended approach, but not the only approach. Explicit 487 registration is not required, nor is it necessary that you provide a 488 <code>JNI_OnLoad</code> function. 489 You can instead use "discovery" of native methods that are named in a 490 specific way (see <a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp615">the JNI spec</a> for details), though this is less desirable because if a method signature is wrong you won't know 491 about it until the first time the method is actually used.</p> 492 493 <p>One other note about <code>JNI_OnLoad</code>: any <code>FindClass</code> 494 calls you make from there will happen in the context of the class loader 495 that was used to load the shared library. Normally <code>FindClass</code> 496 uses the loader associated with the method at the top of the interpreted 497 stack, or if there isn't one (because the thread was just attached) it uses 498 the "system" class loader. This makes 499 <code>JNI_OnLoad</code> a convenient place to look up and cache class 500 object references.</p> 501 502 503 <a name="64_bit" id="64_bit"></a> 504 <h2>64-bit Considerations</h2> 505 506 <p>Android is currently expected to run on 32-bit platforms. In theory it 507 could be built for a 64-bit system, but that is not a goal at this time. 508 For the most part this isn't something that you will need to worry about 509 when interacting with native code, 510 but it becomes significant if you plan to store pointers to native 511 structures in integer fields in an object. To support architectures 512 that use 64-bit pointers, <strong>you need to stash your native pointers in a 513 <code>long</code> field rather than an <code>int</code></strong>. 514 515 516 <a name="unsupported" id="unsupported"></a> 517 <h2>Unsupported Features/Backwards Compatibility</h2> 518 519 <p>All JNI 1.6 features are supported, with the following exception:</p> 520 <ul> 521 <li><code>DefineClass</code> is not implemented. Android does not use 522 Java bytecodes or class files, so passing in binary class data 523 doesn't work.</li> 524 </ul> 525 526 <p>For backward compatibility with older Android releases, you may need to 527 be aware of:</p> 528 <ul> 529 <li><b>Dynamic lookup of native functions</b> 530 <p>Until Android 2.0 (Eclair), the '$' character was not properly 531 converted to "_00024" during searches for method names. Working 532 around this requires using explicit registration or moving the 533 native methods out of inner classes. 534 <li><b>Detaching threads</b> 535 <p>Until Android 2.0 (Eclair), it was not possible to use a <code>pthread_key_create</code> 536 destructor function to avoid the "thread must be detached before 537 exit" check. (The runtime also uses a pthread key destructor function, 538 so it'd be a race to see which gets called first.) 539 <li><b>Weak global references</b> 540 <p>Until Android 2.2 (Froyo), weak global references were not implemented. 541 Older versions will vigorously reject attempts to use them. You can use 542 the Android platform version constants to test for support. 543 <p>Until Android 4.0 (Ice Cream Sandwich), weak global references could only 544 be passed to <code>NewLocalRef</code>, <code>NewGlobalRef</code>, and 545 <code>DeleteWeakGlobalRef</code>. (The spec strongly encourages 546 programmers to create hard references to weak globals before doing 547 anything with them, so this should not be at all limiting.) 548 <p>From Android 4.0 (Ice Cream Sandwich) on, weak global references can be 549 used like any other JNI references.</li> 550 <li><b>Local references</b> 551 <p>Until Android 4.0 (Ice Cream Sandwich), local references were 552 actually direct pointers. Ice Cream Sandwich added the indirection 553 necessary to support better garbage collectors, but this means that lots 554 of JNI bugs are undetectable on older releases. See 555 <a href="http://android-developers.blogspot.com/2011/11/jni-local-reference-changes-in-ics.html">JNI Local Reference Changes in ICS</a> for more details. 556 <li><b>Determining reference type with <code>GetObjectRefType</code></b> 557 <p>Until Android 4.0 (Ice Cream Sandwich), as a consequence of the use of 558 direct pointers (see above), it was impossible to implement 559 <code>GetObjectRefType</code> correctly. Instead we used a heuristic 560 that looked through the weak globals table, the arguments, the locals 561 table, and the globals table in that order. The first time it found your 562 direct pointer, it would report that your reference was of the type it 563 happened to be examining. This meant, for example, that if 564 you called <code>GetObjectRefType</code> on a global jclass that happened 565 to be the same as the jclass passed as an implicit argument to your static 566 native method, you'd get <code>JNILocalRefType</code> rather than 567 <code>JNIGlobalRefType</code>. 568 </ul> 569 570 571 <a name="faq_ULE" id="faq_ULE"></a> 572 <h2>FAQ: Why do I get <code>UnsatisfiedLinkError</code>?</h2> 573 574 <p>When working on native code it's not uncommon to see a failure like this:</p> 575 <pre>java.lang.UnsatisfiedLinkError: Library foo not found</pre> 576 577 <p>In some cases it means what it says — the library wasn't found. In 578 other cases the library exists but couldn't be opened by <code>dlopen(3)</code>, and 579 the details of the failure can be found in the exception's detail message.</p> 580 581 <p>Common reasons why you might encounter "library not found" exceptions:</p> 582 <ul> 583 <li>The library doesn't exist or isn't accessible to the app. Use 584 <code>adb shell ls -l <path></code> to check its presence 585 and permissions. 586 <li>The library wasn't built with the NDK. This can result in 587 dependencies on functions or libraries that don't exist on the device. 588 </ul> 589 590 <p>Another class of <code>UnsatisfiedLinkError</code> failures looks like:</p> 591 <pre>java.lang.UnsatisfiedLinkError: myfunc 592 at Foo.myfunc(Native Method) 593 at Foo.main(Foo.java:10)</pre> 594 595 <p>In logcat, you'll see:</p> 596 <pre>W/dalvikvm( 880): No implementation found for native LFoo;.myfunc ()V</pre> 597 598 <p>This means that the runtime tried to find a matching method but was 599 unsuccessful. Some common reasons for this are:</p> 600 <ul> 601 <li>The library isn't getting loaded. Check the logcat output for 602 messages about library loading. 603 <li>The method isn't being found due to a name or signature mismatch. This 604 is commonly caused by: 605 <ul> 606 <li>For lazy method lookup, failing to declare C++ functions 607 with <code>extern "C"</code> and appropriate 608 visibility (<code>JNIEXPORT</code>). Note that prior to Ice Cream 609 Sandwich, the JNIEXPORT macro was incorrect, so using a new GCC with 610 an old <code>jni.h</code> won't work. 611 You can use <code>arm-eabi-nm</code> 612 to see the symbols as they appear in the library; if they look 613 mangled (something like <code>_Z15Java_Foo_myfuncP7_JNIEnvP7_jclass</code> 614 rather than <code>Java_Foo_myfunc</code>), or if the symbol type is 615 a lowercase 't' rather than an uppercase 'T', then you need to 616 adjust the declaration. 617 <li>For explicit registration, minor errors when entering the 618 method signature. Make sure that what you're passing to the 619 registration call matches the signature in the log file. 620 Remember that 'B' is <code>byte</code> and 'Z' is <code>boolean</code>. 621 Class name components in signatures start with 'L', end with ';', 622 use '/' to separate package/class names, and use '$' to separate 623 inner-class names (<code>Ljava/util/Map$Entry;</code>, say). 624 </ul> 625 </ul> 626 627 <p>Using <code>javah</code> to automatically generate JNI headers may help 628 avoid some problems. 629 630 631 <a name="faq_FindClass" id="faq_FindClass"></a> 632 <h2>FAQ: Why didn't <code>FindClass</code> find my class?</h2> 633 634 <p>Make sure that the class name string has the correct format. JNI class 635 names start with the package name and are separated with slashes, 636 such as <code>java/lang/String</code>. If you're looking up an array class, 637 you need to start with the appropriate number of square brackets and 638 must also wrap the class with 'L' and ';', so a one-dimensional array of 639 <code>String</code> would be <code>[Ljava/lang/String;</code>.</p> 640 641 <p>If the class name looks right, you could be running into a class loader 642 issue. <code>FindClass</code> wants to start the class search in the 643 class loader associated with your code. It examines the call stack, 644 which will look something like: 645 <pre> Foo.myfunc(Native Method) 646 Foo.main(Foo.java:10) 647 dalvik.system.NativeStart.main(Native Method)</pre> 648 649 <p>The topmost method is <code>Foo.myfunc</code>. <code>FindClass</code> 650 finds the <code>ClassLoader</code> object associated with the <code>Foo</code> 651 class and uses that.</p> 652 653 <p>This usually does what you want. You can get into trouble if you 654 create a thread yourself (perhaps by calling <code>pthread_create</code> 655 and then attaching it with <code>AttachCurrentThread</code>). 656 Now the stack trace looks like this:</p> 657 <pre> dalvik.system.NativeStart.run(Native Method)</pre> 658 659 <p>The topmost method is <code>NativeStart.run</code>, which isn't part of 660 your application. If you call <code>FindClass</code> from this thread, the 661 JavaVM will start in the "system" class loader instead of the one associated 662 with your application, so attempts to find app-specific classes will fail.</p> 663 664 <p>There are a few ways to work around this:</p> 665 <ul> 666 <li>Do your <code>FindClass</code> lookups once, in 667 <code>JNI_OnLoad</code>, and cache the class references for later 668 use. Any <code>FindClass</code> calls made as part of executing 669 <code>JNI_OnLoad</code> will use the class loader associated with 670 the function that called <code>System.loadLibrary</code> (this is a 671 special rule, provided to make library initialization more convenient). 672 If your app code is loading the library, <code>FindClass</code> 673 will use the correct class loader. 674 <li>Pass an instance of the class into the functions that need 675 it, by declaring your native method to take a Class argument and 676 then passing <code>Foo.class</code> in. 677 <li>Cache a reference to the <code>ClassLoader</code> object somewhere 678 handy, and issue <code>loadClass</code> calls directly. This requires 679 some effort. 680 </ul> 681 682 683 <a name="faq_sharing" id="faq_sharing"></a> 684 <h2>FAQ: How do I share raw data with native code?</h2> 685 686 <p>You may find yourself in a situation where you need to access a large 687 buffer of raw data from both managed and native code. Common examples 688 include manipulation of bitmaps or sound samples. There are two 689 basic approaches.</p> 690 691 <p>You can store the data in a <code>byte[]</code>. This allows very fast 692 access from managed code. On the native side, however, you're 693 not guaranteed to be able to access the data without having to copy it. In 694 some implementations, <code>GetByteArrayElements</code> and 695 <code>GetPrimitiveArrayCritical</code> will return actual pointers to the 696 raw data in the managed heap, but in others it will allocate a buffer 697 on the native heap and copy the data over.</p> 698 699 <p>The alternative is to store the data in a direct byte buffer. These 700 can be created with <code>java.nio.ByteBuffer.allocateDirect</code>, or 701 the JNI <code>NewDirectByteBuffer</code> function. Unlike regular 702 byte buffers, the storage is not allocated on the managed heap, and can 703 always be accessed directly from native code (get the address 704 with <code>GetDirectBufferAddress</code>). Depending on how direct 705 byte buffer access is implemented, accessing the data from managed code 706 can be very slow.</p> 707 708 <p>The choice of which to use depends on two factors:</p> 709 <ol> 710 <li>Will most of the data accesses happen from code written in Java 711 or in C/C++? 712 <li>If the data is eventually being passed to a system API, what form 713 must it be in? (For example, if the data is eventually passed to a 714 function that takes a byte[], doing processing in a direct 715 <code>ByteBuffer</code> might be unwise.) 716 </ol> 717 718 <p>If there's no clear winner, use a direct byte buffer. Support for them 719 is built directly into JNI, and performance should improve in future releases.</p> 720