OpenParable
Skip to content
← Back to skills

Jni Type Conversion

Development
jni-type-conversion

Jni Type Conversion is an Agent Skill for development published in the chromium/chromium repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

How to use @JniType annotations for ergonomic JNI. Relevant for Java files that use @NativeMethods or @CalledByNative.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/chromium/chromium/blob/HEAD/agents/skills/jni-type-conversion/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/jni-type-conversion, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

JNI Type Conversion

This skill guides the process of replacing explicit JNI conversion logic (like ConvertJavaStringToUTF8) with @JniType annotations in Java and corresponding native types in C++.

Workflow

  1. Read third_party/jni_zero/README.chromium.md for a primer on JNI Zero.
  2. Identify Candidates: Look for JNI methods (annotated with @NativeMethods or @CalledByNative) that take or return types that are currently being explicitly converted in C++.
  3. Discovery (CRITICAL): To see if a type already has a @JniType conversion defined, search the codebase for FromJniType or ToJniType definitions for that C++ type:
    rg -g "*.h" "\binline .*(From|To)JniType"
    
    If a conversion exists, note the header file where it is defined; you will need to include it from any C++ files that require the conversion.
  4. Check C++ Implementation: Verify that the C++ side performs explicit conversions using functions like:
    • ConvertJavaStringToUTF8 -> std::string
    • ConvertJavaStringToUTF16 -> std::u16string
    • JavaIntArrayToIntVector -> std::vector<int32_t>
    • ToJavaArrayOfStrings -> std::vector<std::string>
    • base::android::ConvertJavaStringToUTF8 -> std::string
  5. Verify Constraints: Do NOT convert if:
    • The conversion is conditional (e.g., inside an if block that might skip it).
    • The conversion happens inside a lambda (e.g., TRACE_EVENT macros). Moving these to @JniType makes the conversion eager, which can impact performance.
  6. Annotate Java:
    • Add @JniType("cpp_type") to the parameter or return type.
    • For String parameters, @JniType("std::string") automatically converts Java null to C++ "". Prefer this over std::optional<std::string> unless the C++ logic specifically distinguishes between null and empty.
    • For all other types, use std::optional<T> if the Java parameter is @Nullable. Always maintain @Nullable annotations.
    • Binary Data: Use @JniType("std::vector<uint8_t>") for byte[].
    • Null Safety: Keep @Nullable in Java if the parameter can be null. For @Nullable String, using std::optional<std::string> in C++ will map null to std::nullopt.
    • Ensure org.jni_zero.JniType is imported.
  7. Update C++:
    • Change the C++ parameter type to the native type (e.g., const std::string&, std::vector<int32_t>&, base::OnceClosure).
    • Remove the explicit conversion calls and intermediate variables.
    • Remove Unused JNIEnv: If the JNIEnv* env parameter used to be used, but is no longer used after @JniType additions, it should be removed from the C++ function signature.
    • Remove Unused Callers: For non-static @NativeMethods, the caller parameter is usually unnecessary. Remove it from Java and C++ to reduce boilerplate.
    • Remove Unused using statements: Aliases of conversion functions might no longer have any uses. e.g.: "using base::android::ConvertJavaStringToUTF8"
    • Include Order: Specialization headers MUST be included before the generated _jni.h file.
    • Include the header file that defines the FromJniType / ToJniType conversion functions.
      • E.g.: Include base/android/jni_string.h for all string conversions.
      • E.g.: Include third_party/jni_zero/default_conversions.h for containers (std::vector, std::optional, base::span).
      • E.g.: Include base/android/callback_android.h for callback conversions.
  8. Validate (CRITICAL): Changes are INCOMPLETE until you have verified they build. Build all .cc and .java files to ensure JNI generation and compilation succeed.
    • Build using a command like: autoninja -C OUTPUT_DIR ../../path/to/foo.cc^ ../../path/to/Foo.java^ ...
      • Paths must be relative to OUTPUT_DIR (e.g. start with ../../)
      • The "^" suffix means "build all targets that have this input.
    • Do not guess the OUTPUT_DIR you must have been told it.
    • If you cannot build, you MUST state this clearly and summarize the changes made.

Common Recipes

base::Uuid Handling

Java: @JniType("std::string") String uuid C++: base::Uuid::ParseLowercase(uuid_string) (incoming) or uuid.AsLowercaseString() (outgoing).

Collection Return Types

@JniType("std::vector<...>") works for return types. C++ can return a std::vector and it will be automatically converted to a Java array or List.

Examples

Callback Parameter

Java:

void doSomething(@JniType("base::OnceClosure") Runnable callback);

C++:

#include "base/android/callback_android.h"
void JNI_MyClass_DoSomething(base::OnceClosure callback) {
    std::move(callback).Run();
}