Struct jni::JNIEnv

#[repr(C)]
pub struct JNIEnv<'a> { /* 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.

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<S>(&self, name: S) -> Result<JClass<'a>> where S: Into<JNIString>

Look up a class by name.

Example

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

fn get_superclass<T>(&self, class: T) -> Result<JClass> where T: Desc<'a, JClass<'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: Desc<'a, JClass<'a>>, U: Desc<'a, JClass<'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: Desc<'a, JClass<'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) -> !

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> where T: Desc<'a, JClass<'a>>

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

fn get_method_id<T, U, V>(&self,
                          class: T,
                          name: U,
                          sig: V)
                          -> Result<JMethodID<'a>> where T: Desc<'a, JClass<'a>>, U: Into<JNIString>, V: Into<JNIString>

Look up a method by class descriptor, name, and signature.

Example

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

fn get_static_method_id<T, U, V>(&self,
                                 class: T,
                                 name: U,
                                 sig: V)
                                 -> Result<JStaticMethodID<'a>> where T: Desc<'a, JClass<'a>>, U: Into<JNIString>, V: Into<JNIString>

Look up a static method by class descriptor, name, and signature.

Example

let method_id: JMethodID = env.get_static_method_id(
    "java/lang/String", "valueOf", "(I)Ljava/lang/String;",
);

fn get_field_id<T, U, V>(&self,
                         class: T,
                         name: U,
                         sig: V)
                         -> Result<JFieldID<'a>> where T: Desc<'a, JClass<'a>>, U: Into<JNIString>, V: Into<JNIString>

Look up the field ID for a class/name/type combination.

Example

let field_id = env.get_field_id("com/my/Class", "intField", "I");

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])
                                          -> Result<JValue> where T: Desc<'a, JClass<'a>>, U: Desc<'a, JStaticMethodID<'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])
                                -> Result<JValue> where T: Desc<'a, JMethodID<'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,
                     name: S,
                     sig: T,
                     args: &[JValue])
                     -> Result<JValue> 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])
                               -> Result<JValue> where T: Desc<'a, JClass<'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])
                    -> Result<JObject> where T: Desc<'a, JClass<'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(&self, obj: JObject<'a>) -> Result<JMap>

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<'a>) -> 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.

unsafe fn get_string_utf_chars(&self, obj: JString) -> Result<*const c_char>

Get a pointer to the character array beneath a JString. This is in Java's modified UTF-8 and will leak memory if release_string_utf_chars is never called.

unsafe fn release_string_utf_chars(&self,
                                   obj: JString,
                                   arr: *const c_char)
                                   -> Result<()>

Unpin the array returned by get_string_utf_chars.

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.

unsafe fn get_field_unsafe<T>(&self,
                              obj: JObject,
                              field: T,
                              ty: JavaType)
                              -> Result<JValue> where T: Desc<'a, JFieldID<'a>>

Get a field without checking the provided type against the actual field.

unsafe fn set_field_unsafe<T>(&self,
                              obj: JObject,
                              field: T,
                              val: JValue)
                              -> Result<()> where T: Desc<'a, JFieldID<'a>>

Set a field without any type checking.

fn get_field<S, T>(&self, obj: JObject, name: S, ty: T) -> Result<JValue> where S: Into<JNIString>, T: Into<JNIString> + AsRef<str>

Get a field. Requires an object class lookup and a field id lookup internally.

fn set_field<S, T>(&self,
                   obj: JObject,
                   name: S,
                   ty: T,
                   val: JValue)
                   -> Result<()> where S: Into<JNIString>, T: Into<JNIString> + AsRef<str>

Set a field. Does the same lookups as get_field and ensures that the type matches the given value.

unsafe fn set_rust_field<S, T>(&self,
                               obj: JObject,
                               field: S,
                               rust_object: T)
                               -> Result<()> where S: AsRef<str>, T: Send + 'static

Surrenders ownership of a rust object to Java. Requires an object with a long field to store the pointer. The Rust value will be wrapped in a Mutex since Java will be controlling where it'll be used thread-wise. Unsafe because it leaks memory if take_rust_field is never called (so be sure to make a finalizer).

DO NOT make a copy of the object containing one of these fields. If you've set up a finalizer to pass it back to Rust upon being GC'd, it will point to invalid memory and will likely attempt to be deallocated again.

unsafe fn get_rust_field<S, T>(&self,
                               obj: JObject,
                               field: S)
                               -> Result<MutexGuard<T>> where S: Into<JNIString>, T: Send + 'static

Gets a lock on a Rust value that's been given to a Java object. Java still retains ownership and take_rust_field will still need to be called at some point. Checks for a null pointer, but assumes that the data it ponts to is valid for T.

unsafe fn take_rust_field<S, T>(&self, obj: JObject, field: S) -> Result<T> where S: AsRef<str>, T: Send + 'static

Take a Rust field back from Java. Makes sure that the pointer is non-null, but still assumes that the data it points to is valid for T. Sets the field to a null pointer to signal that it's empty.

This will return an error in the event that there's an outstanding lock on the object.

fn lock_obj(&self, obj: JObject) -> Result<MonitorGuard<'a>>

Lock a Java object. The MonitorGuard that this returns is responsible for ensuring that it gets unlocked.

Trait Implementations

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

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

Performs the conversion.