reisxd/tizentubecobalt/jni-zero

JNI Zero Guidance

JNI Zero is a code generator that lives at //third_party/jni_zero. It's written in Python and has both C++ and Java APIs. The main reference is in //third_party/jni_zero/README.md.

Guidance for GN

• Use _jni as a suffix for all generate_jni() and generate_jar_jni()

targets.

• generate_jni() targets should be in the same BUILD.gn as the

android_library() that owns the sources.

• Ensure that all android_library() targets that have a .java file that is

listed in a generate_jni() target also contain a deps entry onto the foo_jni_java target.

Guidance for C++

Generated headers:

• Are generated at

{OUTPUT_DIR}/gen/jni_headers/{BUILD_GN_SUBDIR}/{TARGET_NAME}/{JavaClass}_jni.h

• Omit the gen/jni_headers prefix when #include'ing them.
• #includes of _jni.h headers from .cc files should come after all other

#includes and be preceded with the comment:

• // Must come after headers that provide symbols used by @JniType.
• #includes of _jni.h headers from .h files should always use the

_shared_jni.h variants.

API Usage:

• When returning or passing a null JavaRef, use nullptr rather than calling

a constructor.

• Prefer JArray<jobject> over jobjectArray, as well as for other array types

(JArray<*> over j*Array)

• Use the jni_zero:: namespace instead of the base::android:: aliases (e.g.

for *JavaRef, and AttachBaseContext())

• To call static Java methods, do not call the Java_Clazz_method() functions

directly. Call them through their typed wrappers: ClazzJni::method()

• To call constructors methods, use ClazzJni::New()
• To call member functions given a JavaRef<jobject>, use Java_Clazz_method()
• To call member functions given a JavaRef<JFoo>, use foo->method()

Defining native entry point methods:

• Use the signatures from the examples within the generated _jni.h files
• Omit the JNIEnv* parameter if it will be unused.

Guidance for Java

• Name all @NativeMethods interfaces "Natives", and make them package-private.
• Use @JniType() on as many parameters and return types as possible.
• Parameters and return types that may be null must be annotated as

@Nullable to avoid a runtime null-check.

• A Java class owns a native object if it creates it via JNI.
• A native object owns a Java class if it creates it via JNI.
• If a Java class owns a native object, ensure that there is an onDestroy()

method that calls delete via JNI, and sets the field 0.

• If a native object owns a Java object, ensure that its destructor sets the

Java object's native pointer field to 0 from its destructor.

Guidance for @JniType

• Search all .h files for FromJniType or ToJniType to discover which types

are currently supported.

• Strings are either std::string or std::u16string.
• Use std::optional for @Nullable types except when the type itself contains

a null-state (e.g. GURL, Callback, Strings where "" is not a valid value).

• Prefer to use List<> over typed object arrays.

Converting From jobject to Correctly-Typed jobject Subclasses

Core Steps

1. Type Conversion

• Change JavaRef<jobject> and ScopedJavaLocalRef<jobject> to use generated

classes that extend jobject.

• E.g., JavaRef<jobject> for a FooBar class becomes JavaRef<JFooBar>.
• Special Cases:
• java.lang.Object maps to jobject
• java.lang.String maps to jstring
• java.lang.Throwable maps to jthrowable
• java.lang.Class maps to jclass
• Use .As<JFoo>() to convert from JavaRef<jobject> to a specific generated

type.

• Convert ScopedJavaLocalRef<jobject>() (empty constructor) to nullptr.

2. Method Calls

• Instance Methods: Replace Java_MyClass_method(env, ref, ...) with

ref->method(env, ...).

• Static Methods: Replace Java_MyClass_method(env, ...) with

JMyClassClass::method(env, ...).

• Methods taking java.lang.Object will take jobject. If you have a

JavaRef<jobject>, you can pass it directly.

3. Namespaces and Aliases

• JNI types often have long namespaces (e.g., ::org::chromium::base::JFoo).
• If a using statement isn't already in the _jni.h file, add an alias at the

top of the .cc file.

• E.g., using ::org::chromium::base::JLogo;.
• Avoid fully-qualified names in method signatures within .cc files when an

alias is available.

4. Headers and Dependencies

• If a type JFoo is used in a .h file:
• Include foo_shared_jni.h.
• In the BUILD.gn, add a public_dep onto the generate_jni() target that

produces it.

• Do NOT include _shared_jni.h in .cc files; use regular _jni.h headers

there.

• For system classes (List, Set, Map):
• Add a dependency on //third_party/jni_zero:system_jni.
• Use generated headers from that target.

Examples

See examples.md for concrete before/after snippets.

Validation

Build all affected .cc and .java files using autoninja:

autoninja -C {OUTPUT_DIR} ../../path/to/foo.cc^ ../../path/to/Foo.java^

Note: Use the specified `OUTPUT_DIR` (typically `out/Default` or `out/Debug`).