Struct rust_jni::NoException

pub struct NoException<'env> { /* fields omitted */ }

A token that represents that there is no pending Java exception in the current thread.

Pending exceptions

When a JNI function is called, it can throw an exception. Then the current thread is said to have a pending exception. Most JNI functions must not be called when there is a pending exception. Read more about exception handling in JNI documentation.

Exception tokens

rust-jni tries to push as many programming errors as possible from run-time to compile-time. To not allow a caller to call JNI methods when there is a pending exception, these methods will require the caller to provide a NoException token. The caller can obtain the token after attaching the thread to the Java VM:

use rust_jni::{AttachArguments, InitArguments, JavaVM, JniVersion};

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();
let token = env.token();

Once obtained, the token can be used to call JNI methods:

let token = env.token();
let string = java::lang::String::empty(&env, &token).unwrap();

rust-jni follows Java semantics, where a method either returns a result or throws an exception. All Java methods return a JavaResult value, which is either an actual result or a Throwable value representing the exception thrown by this method call. Java methods never leave a pending exception, so they never consume the NoException token, but they always require it to be presented:

let token = env.token();
let string = java::lang::Class::find(&env, "java/lang/String", &token).unwrap();
let exception = java::lang::Class::find(&env, "invalid", &token).unwrap_err();

A token can not be obtained twice from a JniEnv value:

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

There is no possible way to obtain a token when there is a pending exception. The token is bound to the JniEnv object, so it can't outlive it:

let token = {
    let env = vm.attach(&AttachArguments::new(&init_arguments)).unwrap();
    let token = env.token();
    token
}; // doesn't compile!

Some JNI methods can throw exceptions themselves. In this case the token will be consumed:

let token = env.token();
let exception = java::lang::String::empty(&env, &token).unwrap_err();
exception.throw(token);
java::lang::String::empty(&env, &token); // doesn't compile! Can't use the token any more.

Methods that consume the token will always return an Exception token. The Exception token can be unwrap-ped into a new NoException token and a Throwable value with the pending exception. Unwrapping the Exception token will clear the pending exception, so it is again safe to call JNI methods:

let token = env.token();
let exception = java::lang::Class::find(&env, "invalid", &token).unwrap_err();
let exception_token = exception.throw(token); // there is a pending exception now.
let (exception, new_token) = exception_token.unwrap();
java::lang::String::empty(&env, &new_token); // can call Java methods again.

Trait Implementations

impl<'env> Debug for NoException<'env>

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

Formats the value using the given formatter.