(THIS CODING RULE OR GUIDELINE IS UNDER CONSTRUCTION)

To allow for the proper operation of the garbage collector in Java, the JVM must keep track of all Java objects passed to native code. Consequently, JNI uses local references and global references, see [JNISpec 2014] Chapter 2: Design Overview. While at least one local or global reference to a Java object exists, the object cannot be removed by the garbage collector. However, if the object is moved in memory by the garbage collector then the reference to the object remains valid. Local references are freed automatically when the function in which the local reference is defined returns (although a user may free a local reference before the function returns if they wish). Global references maintain a valid reference to the Java object until they are explicitly freed by the user. (JNI also uses weak global references which are similar to global references but allow the referenced object to be removed by the garbage collector, see: [JNISpec 2014] Chapter 4: JNI Functions.)

Attempting to use a direct pointer to a Java object in native code, rather than a local, global or weak global reference, may have erroneous results because the Java object may be moved or removed by the garbage collector while the direct pointer still exists.

Noncompliant Code Example

This noncompliant code example shows an example where a direct pointer to a Java object is used with erroneous results.

Compliant Solution

In this compliant solution ...

Risk Assessment

If a direct pointer to a Java object is used then erroneous results may be obtained that could lead to the code crashing. This, in turn, could be used to mount a denial of service attack.  In some circumstances, the direct pointer could become a "dangling pointer" which could result in sensitive information being leaked or malicious execution of arbitrary code.

Automated Detection

Direct pointers to Java objects can be detected and replaced by indirect handles automatically.

Android Implementation Details

Before Android version 4.0, "Ice Cream Sandwich", direct pointers to Java objects were used in native code. However, Ice Cream Sandwich introduced the use of indirect handles. This is to facilitate the introduction of a compacting garbage collector in the future. Such a garbage collector moves objects in memory so direct pointers to objects may no longer be valid after a compacting garbage collector has run.  For more information on this see  [Verify], section "Preventing JNI Issues" and [Hughes 2011].

Applicability

Android Version Applicability 

Applies to Android API versions 14 (ICE_CREAM_SANDWICH) and above, with Native Development Kit (NDK) 7.

Bibliography