Struct jni::JNIEnv

pub struct JNIEnv<'a> {
    pub internal: *mut JNIEnv,
    // some fields omitted
}

FFI-compatible JNIEnv struct. You can safely use this as the JNIEnv argument to exported methods that will be called by java. This is where most of the magic happens. All methods on this object are wrappers around JNI functions, so the documentation on their behavior is still pretty applicable.

Since we're calling into the JVM with this, many methods also have the potential to cause an exception to get thrown. If this is the case, an Err result will be returned with the error kind JavaException. Note that this will not clear the exception - it's up to the caller to decide whether to do so or to let it continue being thrown.

Because null pointers are a thing in Java, this also converts them to an Err result with the kind NullPtr. This may occur when either a null argument is passed to a method or when a null would be returned. Where applicable, the null error is changed to a more applicable error type, such as MethodNotFound.

Fields

internal: *mut JNIEnv

Methods

impl<'a> JNIEnv<'a>

fn get_version(&self) -> Result<jint>

Get the java version that we're being executed from. This is encoded and will need to be checked against constants from the sys module.

TODO: convert this to something more usable.

fn define_class<S>(&self,
                   name: S,
                   loader: JObject,
                   buf: &[u8])
                   -> Result<JClass> where S: Into<JNIString>

Define a new java class. See the JNI docs for more details - I've never had occasion to use this and haven't researched it fully.

fn find_class<T>(&self, name: T) -> Result<JClass<'a>> where T: IntoClassDesc<'a>

Look up a class by name. The argument to this will be something like java/lang/String. This can also take a concrete JClass, in which case it simply returns it after doing a null check. This is so that it can be generic over both concrete classes and class descriptor strings. Methods with class arguments should therefore take IntoClassDesc instead, and use ths when an actual class is needed. That way, optimizations such as reusing a class object to look up multiple methods can be done.

Example

let class: JClass<'a> = env.find_class("java/lang/String");

fn get_superclass<T>(&self, class: T) -> Result<JClass<'a>> where T: IntoClassDesc<'a>

Get the superclass for a particular class. As with find_class, takes a descriptor.

fn is_assignable_from<T, U>(&self, class1: T, class2: U) -> Result<bool> where T: IntoClassDesc<'a>, U: IntoClassDesc<'a>

Tests whether class1 is assignable from class2.

fn throw(&self, obj: JThrowable) -> Result<()>

Raise an exception from an existing object. This will continue being thrown in java unless exception_clear is called.

fn throw_new<S, T>(&self, class: T, msg: S) -> Result<()> where S: Into<JNIString>, T: IntoClassDesc<'a>

Create and throw a new exception from a class descriptor and an error message.

fn exception_occurred(&self) -> Result<JThrowable>

Check whether or not an exception is currently in the process of being thrown. An exception is in this state from the time it gets thrown and not caught in a java function until exception_clear is called.

fn exception_describe(&self) -> Result<()>

Print exception information to the console.

fn exception_clear(&self) -> Result<()>

Clear an exception in the process of being thrown. If this is never called, the exception will continue being thrown when control is returned to java.

fn fatal_error<S: Into<JNIString>>(&self, msg: S) -> Result<()>

Abort the JVM with an error message.

fn exception_check(&self) -> Result<bool>

Check to see if an exception is being thrown. This only differs from exception_occurred in that it doesn't return the actual thrown exception.

fn new_global_ref(&self, obj: JObject) -> Result<GlobalRef>

Turns an object into a global ref. This has the benefit of removing the lifetime bounds since it's guaranteed to not get GC'd by java. It releases the GC pin upon being dropped.

fn alloc_object<T>(&self, class: T) -> Result<JObject<'a>> where T: IntoClassDesc<'a>

Allocates a new object from a class descriptor without running a constructor.

fn get_method_id<T>(&self, desc: T) -> Result<JMethodID<'a>> where T: IntoMethodDesc<'a>

Look up a method by class descriptor (or concrete class), name, and signature. Like find_class, this is generic over descriptors and concrete JMethodID objects and can take both. If given a concrete object, it simply returns it.

Example

let method_id: JMethodID = env.get_method_id(
    ("java/lang/String", "getString", "()Ljava/lang/String;"),
);

fn get_object_class(&self, obj: JObject) -> Result<JClass>

Get the class for an object.

unsafe fn call_static_method_unsafe<T, U>(&self,
                                          class: T,
                                          method_id: U,
                                          ret: JavaType,
                                          args: &[JValue<'a>])
                                          -> Result<JValue<'a>> where T: IntoClassDesc<'a>, U: IntoMethodDesc<'a>

Call a static method in an unsafe manner. This does nothing to check whether the method is valid to call on the class, whether the return type is correct, or whether the number of args is valid for the method.

Under the hood, this simply calls the CallStatic<Type>MethodA method with the provided arguments.

unsafe fn call_method_unsafe<T>(&self,
                                obj: JObject,
                                method_id: T,
                                ret: JavaType,
                                args: &[JValue<'a>])
                                -> Result<JValue<'a>> where T: IntoMethodDesc<'a>

Call an object method in an unsafe manner. This does nothing to check whether the method is valid to call on the object, whether the return type is correct, or whether the number of args is valid for the method.

Under the hood, this simply calls the Call<Type>MethodA method with the provided arguments.

fn call_method<S, T>(&'a self,
                     obj: JObject<'a>,
                     name: S,
                     sig: T,
                     args: &[JValue<'a>])
                     -> Result<JValue<'a>> where S: Into<JNIString>, T: Into<JNIString> + AsRef<str>

Calls an object method safely. This comes with a number of lookups/checks. It

• Parses the type signature to find the number of arguments and return type
• Looks up the JClass for the given object.
• Looks up the JMethodID for the class/name/signature combination
• Ensures that the number of args matches the signature
• Calls call_method_unsafe with the verified safe arguments.

Note: this may cause a java exception if the arguments are the wrong type, in addition to if the method itself throws.

fn call_static_method<T, U, V>(&self,
                               class: T,
                               name: U,
                               sig: V,
                               args: &[JValue<'a>])
                               -> Result<JValue<'a>> where T: IntoClassDesc<'a>, U: Into<JNIString>, V: Into<JNIString> + AsRef<str>

Calls a static method safely. This comes with a number of lookups/checks. It

• Parses the type signature to find the number of arguments and return type
• Looks up the JMethodID for the class/name/signature combination
• Ensures that the number of args matches the signature
• Calls call_method_unsafe with the verified safe arguments.

Note: this may cause a java exception if the arguments are the wrong type, in addition to if the method itself throws.

fn new_object<T, U>(&self,
                    class: T,
                    ctor_sig: U,
                    ctor_args: &[JValue<'a>])
                    -> Result<JObject<'a>> where T: IntoClassDesc<'a>, U: Into<JNIString> + AsRef<str>

Create a new object using a constructor. This is done safely using checks similar to those in call_static_method.

fn get_map(&'a self, obj: JObject<'a>) -> Result<JMap<'a>>

Cast a JObject to a JMap. This won't throw exceptions or return errors in the event that the object isn't actually a map, but the methods on the resulting map object will.

fn get_string(&self, obj: JString) -> Result<JavaStr>

Get a JavaStr from a JString. This allows conversions from java string objects to rust strings.

This entails a call to GetStringUTFChars and only decodes java's modified UTF-8 format on conversion to a rust-compatible string.

fn new_string<S: Into<JNIString>>(&self, from: S) -> Result<JString>

Create a new java string object from a rust string. This requires a re-encoding of rusts real UTF-8 strings to java's modified UTF-8 format.

Trait Implementations

impl<'a> From<*mut JNIEnv> for JNIEnv<'a>

fn from(other: *mut JNIEnv) -> Self

Performs the conversion.