From 40f3271c2dd386878c9a180462c75c890913e9b4 Mon Sep 17 00:00:00 2001 From: Andy McFadden Date: Tue, 22 Sep 2009 13:55:42 -0700 Subject: [PATCH] More doc changes. Some content changes inspired by external developer feedback, plus some corrections of long-standing typos. --- docs/jni-tips.html | 54 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/docs/jni-tips.html b/docs/jni-tips.html index 13461b55d..e85434b52 100644 --- a/docs/jni-tips.html +++ b/docs/jni-tips.html @@ -14,7 +14,7 @@
  • JavaVM and JNIEnv
    • -
  • jclassID, jmethodID, and jfieldID +
  • jclass, jmethodID, and jfieldID
  • Local vs. Global References
    • @@ -79,7 +79,7 @@ header file requires "#ifdef __cplusplus", you may have to do some extra work if that header refers to JNIEnv.)

    -

    jclassID, jmethodID, and jfieldID

    +

    jclass, jmethodID, and jfieldID

    If you want to access an object's field from native code, you would do the following:

    @@ -104,7 +104,8 @@ to store this data in a static local structure.

    The class references, field IDs, and method IDs are guaranteed valid until the class is unloaded. Classes are only unloaded if all classes associated with a ClassLoader can be garbage collected, -which is rare but will not be impossible in our system. The jclassID +which is rare but will not be impossible in our system. Note however that +the jclass is a class reference and must be protected with a call to NewGlobalRef (see the next section).

    @@ -145,23 +146,25 @@ for an example in our source tree.) Every object that JNI returns is a "local reference". This means that it's valid for the duration of the current native method in the current thread. Even if the object itself continues to live on after the native method returns, the reference is not valid. -This applies to all sub-classes of jobject, including jclass and jarray. -(Dalvik VM will warn you about this when -Xcheck:jni is enabled.) +This applies to all sub-classes of jobject, including +jclass, jstring, and jarray. +(Dalvik VM will warn you about most reference mis-uses when extended JNI +checks are enabled.)

    -If you want to hold on to a reference for a longer period, you must use a "global" reference. -The NewGlobalRef function takes the local reference as -an argument and returns a global one: +If you want to hold on to a reference for a longer period, you must use +a "global" reference. The NewGlobalRef function takes the +local reference as an argument and returns a global one. +The global reference is guaranteed to be valid until you call +DeleteGlobalRef. -

    jobject* localRef = [...];
-jobject* globalRef;
-globalRef = env->NewGlobalRef(localRef);
+
    
+This pattern is commonly used when caching copies of class objects obtained
+from FindClass, e.g.:
+
    jclass* localClass = env->FindClass("MyClass");
+jclass* globalClass = (jclass*) env->NewGlobalRef(localClass);
 
    
 
-The global reference is guaranteed to be valid until you call
-DeleteGlobalRef.  This pattern is frequently used for
-cached copies of class objects obtained from FindClass.
-
    
 
    
 All JNI methods accept both local and global references as arguments.
 It's possible for references to the same object to have different values;
@@ -172,11 +175,11 @@ you must use the IsSameObject function.  Never compare
 references with "==" in native code.
 
    
 One consequence of this is that you
-must not assume object references are constant
+must not assume object references are constant or unique
 in native code.  The 32-bit value representing an object may be different
 from one invocation of a method to the next, and it's possible that two
-different objects could have the same 32-bit value at different times.  Do
-not use jobjects as keys.
+different objects could have the same 32-bit value on consecutive calls.  Do
+not use jobject values as keys.
 
    
 Programmers are required to "not excessively allocate" local references.  In practical terms this means
 that if you're creating large numbers of local references, perhaps while running through an array of
@@ -194,8 +197,8 @@ and GetByteArrayElements are also not objects.
 One unusual case deserves separate mention.  If you attach a native
 thread to the VM with AttachCurrentThread, the code you are running will
 never "return" to the VM until the thread detaches from the VM.  Any local
-references you create will have to be deleted manually unless the thread
-is about to exit or detach.
+references you create will have to be deleted manually unless you're going
+to detach the thread soon.
 
    
 
    
 
    
@@ -382,7 +385,7 @@ hand to printf or a LOG macro.
 
    
 
     Extended Checking 
    
 
    
-JNI does very little error checking.  Calling SetFieldInt
+JNI does very little error checking.  Calling SetIntField
 on an Object field will succeed, even if the field is marked
 private and final.  The
 goal is to minimize the overhead on the assumption that, if you've written it in native code,
@@ -451,7 +454,10 @@ You can load native code from shared libraries with the standard
 preferred way to get at your native code is:

    You can also call System.load() with the full path name of the -shared library. For Android apps, you can get the full path to the -application's private data storage area from the context object. +shared library. For Android apps, you may find it useful to get the full +path to the application's private data storage area from the context object.

    This is the recommended approach, but not the only approach. The VM does not require explicit registration, nor that you provide a -- 2.11.0