jni-rs

jni (the jni-rs project) provides complete, mostly-safe Rust bindings to the Java Native Interface (JNI), the standard mechanism for bridging Rust and the JVM. It lets you implement native Java methods in Rust, call arbitrary Java and Kotlin code from Rust, and even embed a full JVM inside a Rust application.

Built on the raw jni-sys FFI layer, the crate wraps the JNI’s error-prone C API in ergonomic, memory-managed Rust types for object references, strings, arrays, and method signatures. It powers native Android libraries, JVM extensions, and cross-language systems where Rust performance meets the Java ecosystem.

What You Get

• Safe wrappers over the JNI C API with automatic management of local and global object references
• Both directions of interop: implement native methods for the JVM/Android and call Java or Kotlin code from Rust
• An optional invocation feature to spawn and embed a JVM directly inside a Rust process
• Procedural macros for binding Java types and exporting native methods with correct name mangling
• Ergonomic handling of Java strings (CESU-8), arrays, collections (JList/JMap), and method/field signatures

Common Use Cases

• Writing high-performance native Android libraries in Rust that back Java/Kotlin apps
• Implementing native methods for a JVM application to offload hot paths to Rust
• Embedding a JVM in a Rust program to reuse existing Java libraries and frameworks

Under The Hood

Architecture

The crate is organized as a Cargo workspace under crates/, with the public jni crate depending on jni-macros (proc-macros) and the raw jni-sys FFI layer. Core execution flows through env.rs, which wraps the JNI environment pointer in an Env/EnvUnowned type that mediates every call into the JVM; supporting modules split concerns cleanly — objects/ and refs/ model Java object references and local/global reference lifetimes, strings/ handles CESU-8 Java string conversion, signature.rs and descriptors/ encode JNI type signatures, exceptions.rs/errors.rs map Java exceptions to Rust Results, and vm/ implements the optional JVM invocation path.

Tech Stack

Written in Rust (98%+ of the codebase) targeting the JNI C ABI via jni-sys. Dependencies are lean and purposeful: simd_cesu8 for fast Java string encoding, thiserror for error types, log for diagnostics, and cfg-if for platform branching. The optional invocation feature pulls in java-locator and libloading to find and dynamically load a JVM. Java glue for tests and examples is compiled with javac via a Makefile.

Code Quality

Quality is high and well-guarded: the crate sets #![warn(missing_docs)] and #![deny(missing_debug_implementations)], and ships an extensive test suite — roughly 47 test files covering the API surface, native-method binding, global/weak references, thread attach/detach, collections, and trybuild UI tests that assert compile-time macro diagnostics. Errors are modeled explicitly through typed Results rather than panics, and the extensive rustdoc includes runnable examples.

API Design

The public API is deliberately ergonomic for an inherently unsafe domain. Managed reference types and RAII guards remove most manual reference bookkeeping, and the jni-macros bind_java_type/native-method macros generate correctly mangled JNI exports so users avoid hand-writing FFI signatures. Naming is consistent (JObject, JString, JClass, GlobalRef), the README walks through a complete native-method example, and a dedicated examples/ directory plus thorough docs.rs coverage lower the barrier to a genuinely complex interface.