Struct rust_jni::JniEnv

pub struct JniEnv<'vm> { /* fields omitted */ }

The interface for interacting with Java. All calls to Java are performed through this interface. JNI methods can only be called from threads, explicitly attached to the Java VM. JniEnv represents such a thread.

JNI documentation

Examples

use rust_jni::{AttachArguments, InitArguments, JavaVM, JniEnv, JniVersion};
use std::ptr;

let init_arguments = InitArguments::get_default(JniVersion::V8).unwrap();
let vm = JavaVM::create(&init_arguments).unwrap();
let env = vm.attach(&AttachArguments::new(&init_arguments)).unwrap();
unsafe {
    assert_ne!(env.raw_env(), ptr::null_mut());
}

JniEnv is !Send. It means it can't be passed between threads:

let env = vm.attach(&AttachArguments::new(&init_arguments)).unwrap();
{
    ::std::thread::spawn(move || {
        unsafe { env.raw_env() }; // doesn't compile!
    });
}

Instead, you need to attach each new thread to the VM:

use std::sync::Arc;

let init_arguments = InitArguments::get_default(JniVersion::V8).unwrap();
let vm = Arc::new(JavaVM::create(&init_arguments).unwrap());
let env = vm.attach(&AttachArguments::new(&init_arguments)).unwrap();
{
    let vm = vm.clone();
    ::std::thread::spawn(move || {
        let env = vm.attach(&AttachArguments::new(&init_arguments)).unwrap();
        unsafe {
            assert_ne!(env.raw_env(), ptr::null_mut());
        }
    });
}
unsafe {
    assert_ne!(env.raw_env(), ptr::null_mut());
}

The thread is automatically detached once the JniEnv is dropped.

JniEnv can't outlive the parent JavaVM. This code is not allowed:

let env = {
    let init_arguments = InitArguments::get_default(JniVersion::V8).unwrap();
    let vm = JavaVM::create(&init_arguments).unwrap();
    vm.attach(&AttachArguments::new(&init_arguments)).unwrap() // doesn't compile!
};

JniEnv represents a thread, attached to the Java VM. Thus there can't be two JniEnv-s per thread. JavaVM::attach will panic if you attempt to do so:

let env = vm.attach(&AttachArguments::new(&init_arguments)).unwrap();
let env = vm.attach(&AttachArguments::new(&init_arguments)).unwrap(); // panics!

Methods

impl<'vm> JniEnv<'vm>

pub unsafe fn raw_jvm(&self) -> *mut JavaVM

Get the raw Java VM pointer.

This function provides low-level access to all of JNI and thus is unsafe.

pub unsafe fn raw_env(&self) -> *mut JNIEnv

Get the raw JNI environment pointer.

This function provides low-level access to all of JNI and thus is unsafe.

pub fn token(&self) -> NoException

Get a NoException token indicating that there is no pending exception in this thread.

Read more about tokens in NoException documentation.

pub fn version(&self) -> JniVersion

Get JNI version.

JNI documentation

Trait Implementations

impl<'vm> Debug for JniEnv<'vm>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'vm> Drop for JniEnv<'vm>

Drop detaches the current thread from the Java VM. It's not safe to do so with an exception pending, so it panics if this happens.

JNI documentation

fn drop(&mut self)

Executes the destructor for this type.