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</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</h2> 518 519 <p>All JNI 1.6 features are supported, with the following exceptions:</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 <li>"Weak global" references are implemented, but may only be passed 525 to <code>NewLocalRef</code>, <code>NewGlobalRef</code>, and 526 <code>DeleteWeakGlobalRef</code>. (The spec strongly encourages 527 programmers to create hard references to weak globals before doing 528 anything with them, so this should not be at all limiting.)</li> 529 <li><code>GetObjectRefType</code> (new in JNI 1.6) is implemented but not fully 530 functional — it can't always tell the difference between "local" and 531 "global" references.</li> 532 </ul> 533 534 <p>For backward compatibility, you may need to be aware of:</p> 535 <ul> 536 <li>Until Android 2.0 (Eclair), the '$' character was not properly 537 converted to "_00024" during searches for method names. Working 538 around this requires using explicit registration or moving the 539 native methods out of inner classes. 540 <li>Until Android 2.0 (Eclair), it was not possible to use a <code>pthread_key_create</code> 541 destructor function to avoid the "thread must be detached before 542 exit" check. (The runtime also uses a pthread key destructor function, 543 so it'd be a race to see which gets called first.) 544 <li>Until Android 2.2 (Froyo), weak global references were not implemented. 545 Older versions will vigorously reject attempts to use them. You can use 546 the Android platform version constants to test for support. 547 <li>Until Android 4.0 (Ice Cream Sandwich), JNI local references were 548 actually direct pointers. Ice Cream Sandwich added the indirection 549 necessary to support better garbage collectors, but this means that lots 550 of JNI bugs are undetectable on older releases. 551 </ul> 552 553 554 <a name="faq_ULE" id="faq_ULE"></a> 555 <h2>FAQ: Why do I get <code>UnsatisfiedLinkError</code>?</h2> 556 557 <p>When working on native code it's not uncommon to see a failure like this:</p> 558 <pre>java.lang.UnsatisfiedLinkError: Library foo not found</pre> 559 560 <p>In some cases it means what it says — the library wasn't found. In 561 other cases the library exists but couldn't be opened by <code>dlopen(3)</code>, and 562 the details of the failure can be found in the exception's detail message.</p> 563 564 <p>Common reasons why you might encounter "library not found" exceptions:</p> 565 <ul> 566 <li>The library doesn't exist or isn't accessible to the app. Use 567 <code>adb shell ls -l <path></code> to check its presence 568 and permissions. 569 <li>The library wasn't built with the NDK. This can result in 570 dependencies on functions or libraries that don't exist on the device. 571 </ul> 572 573 <p>Another class of <code>UnsatisfiedLinkError</code> failures looks like:</p> 574 <pre>java.lang.UnsatisfiedLinkError: myfunc 575 at Foo.myfunc(Native Method) 576 at Foo.main(Foo.java:10)</pre> 577 578 <p>In logcat, you'll see:</p> 579 <pre>W/dalvikvm( 880): No implementation found for native LFoo;.myfunc ()V</pre> 580 581 <p>This means that the runtime tried to find a matching method but was 582 unsuccessful. Some common reasons for this are:</p> 583 <ul> 584 <li>The library isn't getting loaded. Check the logcat output for 585 messages about library loading. 586 <li>The method isn't being found due to a name or signature mismatch. This 587 is commonly caused by: 588 <ul> 589 <li>For lazy method lookup, failing to declare C++ functions 590 with <code>extern "C"</code> and appropriate 591 visibility (<code>JNIEXPORT</code>). Note that prior to Ice Cream 592 Sandwich, the JNIEXPORT macro was incorrect, so using a new GCC with 593 an old <code>jni.h</code> won't work. 594 You can use <code>arm-eabi-nm</code> 595 to see the symbols as they appear in the library; if they look 596 mangled (something like <code>_Z15Java_Foo_myfuncP7_JNIEnvP7_jclass</code> 597 rather than <code>Java_Foo_myfunc</code>), or if the symbol type is 598 a lowercase 't' rather than an uppercase 'T', then you need to 599 adjust the declaration. 600 <li>For explicit registration, minor errors when entering the 601 method signature. Make sure that what you're passing to the 602 registration call matches the signature in the log file. 603 Remember that 'B' is <code>byte</code> and 'Z' is <code>boolean</code>. 604 Class name components in signatures start with 'L', end with ';', 605 use '/' to separate package/class names, and use '$' to separate 606 inner-class names (<code>Ljava/util/Map$Entry;</code>, say). 607 </ul> 608 </ul> 609 610 <p>Using <code>javah</code> to automatically generate JNI headers may help 611 avoid some problems. 612 613 614 <a name="faq_FindClass" id="faq_FindClass"></a> 615 <h2>FAQ: Why didn't <code>FindClass</code> find my class?</h2> 616 617 <p>Make sure that the class name string has the correct format. JNI class 618 names start with the package name and are separated with slashes, 619 such as <code>java/lang/String</code>. If you're looking up an array class, 620 you need to start with the appropriate number of square brackets and 621 must also wrap the class with 'L' and ';', so a one-dimensional array of 622 <code>String</code> would be <code>[Ljava/lang/String;</code>.</p> 623 624 <p>If the class name looks right, you could be running into a class loader 625 issue. <code>FindClass</code> wants to start the class search in the 626 class loader associated with your code. It examines the call stack, 627 which will look something like: 628 <pre> Foo.myfunc(Native Method) 629 Foo.main(Foo.java:10) 630 dalvik.system.NativeStart.main(Native Method)</pre> 631 632 <p>The topmost method is <code>Foo.myfunc</code>. <code>FindClass</code> 633 finds the <code>ClassLoader</code> object associated with the <code>Foo</code> 634 class and uses that.</p> 635 636 <p>This usually does what you want. You can get into trouble if you 637 create a thread yourself (perhaps by calling <code>pthread_create</code> 638 and then attaching it with <code>AttachCurrentThread</code>). 639 Now the stack trace looks like this:</p> 640 <pre> dalvik.system.NativeStart.run(Native Method)</pre> 641 642 <p>The topmost method is <code>NativeStart.run</code>, which isn't part of 643 your application. If you call <code>FindClass</code> from this thread, the 644 JavaVM will start in the "system" class loader instead of the one associated 645 with your application, so attempts to find app-specific classes will fail.</p> 646 647 <p>There are a few ways to work around this:</p> 648 <ul> 649 <li>Do your <code>FindClass</code> lookups once, in 650 <code>JNI_OnLoad</code>, and cache the class references for later 651 use. Any <code>FindClass</code> calls made as part of executing 652 <code>JNI_OnLoad</code> will use the class loader associated with 653 the function that called <code>System.loadLibrary</code> (this is a 654 special rule, provided to make library initialization more convenient). 655 If your app code is loading the library, <code>FindClass</code> 656 will use the correct class loader. 657 <li>Pass an instance of the class into the functions that need 658 it, by declaring your native method to take a Class argument and 659 then passing <code>Foo.class</code> in. 660 <li>Cache a reference to the <code>ClassLoader</code> object somewhere 661 handy, and issue <code>loadClass</code> calls directly. This requires 662 some effort. 663 </ul> 664 665 666 <a name="faq_sharing" id="faq_sharing"></a> 667 <h2>FAQ: How do I share raw data with native code?</h2> 668 669 <p>You may find yourself in a situation where you need to access a large 670 buffer of raw data from both managed and native code. Common examples 671 include manipulation of bitmaps or sound samples. There are two 672 basic approaches.</p> 673 674 <p>You can store the data in a <code>byte[]</code>. This allows very fast 675 access from managed code. On the native side, however, you're 676 not guaranteed to be able to access the data without having to copy it. In 677 some implementations, <code>GetByteArrayElements</code> and 678 <code>GetPrimitiveArrayCritical</code> will return actual pointers to the 679 raw data in the managed heap, but in others it will allocate a buffer 680 on the native heap and copy the data over.</p> 681 682 <p>The alternative is to store the data in a direct byte buffer. These 683 can be created with <code>java.nio.ByteBuffer.allocateDirect</code>, or 684 the JNI <code>NewDirectByteBuffer</code> function. Unlike regular 685 byte buffers, the storage is not allocated on the managed heap, and can 686 always be accessed directly from native code (get the address 687 with <code>GetDirectBufferAddress</code>). Depending on how direct 688 byte buffer access is implemented, accessing the data from managed code 689 can be very slow.</p> 690 691 <p>The choice of which to use depends on two factors:</p> 692 <ol> 693 <li>Will most of the data accesses happen from code written in Java 694 or in C/C++? 695 <li>If the data is eventually being passed to a system API, what form 696 must it be in? (For example, if the data is eventually passed to a 697 function that takes a byte[], doing processing in a direct 698 <code>ByteBuffer</code> might be unwise.) 699 </ol> 700 701 <p>If there's no clear winner, use a direct byte buffer. Support for them 702 is built directly into JNI, and performance should improve in future releases.</p> 703