Struct uni_tmp_jni::JNIEnv

#[repr(transparent)]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.

Exception handling

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.

null Java references

null Java references are handled by the following rules:

• If a null Java reference is passed to a method that expects a non-null argument, an Err result with the kind NullPtr is returned.
• If a JNI function returns null to indicate an error (e.g. new_int_array), it is converted to Err/NullPtr or, where possible, to a more applicable error type, such as MethodNotFound. If the JNI function also throws an exception, the JavaException error kind will be preferred.
• If a JNI function may return null Java reference as one of possible reference values (e.g., get_object_array_element or get_field_unchecked), it is converted to JObject::null().

Checked and unchecked methods

Some of the methods come in two versions: checked (e.g. call_method) and unchecked (e.g. call_method_unchecked). Under the hood, checked methods perform some checks to ensure the validity of provided signatures, names and arguments, and then call the corresponding unchecked method.

Checked methods are more flexible as they allow passing class names and method/field descriptors as strings and may perform lookups of class objects and method/field ids for you, also performing all the needed precondition checks. However, these lookup operations are expensive, so if you need to call the same method (or access the same field) multiple times, it is recommended to cache the instance of the class and the method/field id, e.g.

• in loops
• when calling the same Java callback repeatedly.

If you do not cache references to classes and method/field ids, you will not benefit from the unchecked methods.

Calling unchecked methods with invalid arguments and/or invalid class and method descriptors may lead to segmentation fault.

Implementations

impl<'a> JNIEnv<'a>

pub unsafe fn from_raw(ptr: *mut JNIEnv) -> Result<Self>

Create a JNIEnv from a raw pointer.

Safety

Expects a valid pointer retrieved from the GetEnv JNI function. Only does a null check.

pub fn get_version(&self) -> Result<JNIVersion>

Get the java version that we're being executed from.

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

Load a class from a buffer of raw class data. The name of the class must match the name encoded within the class file data.

pub fn define_unnamed_class<S>(
    &self,
    loader: JObject<'a>,
    buf: &[u8]
) -> Result<JClass<'a>> where
    S: Into<JNIString>, 

Load a class from a buffer of raw class data. The name of the class is inferred from the buffer.

pub 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");

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

Returns the superclass for a particular class OR JObject::null() for java.lang.Object or an interface. As with find_class, takes a descriptor.

pub fn is_assignable_from<'t, 'u, T, U>(
    &self,
    class1: T,
    class2: U
) -> Result<bool> where
    T: Desc<'a, JClass<'t>>,
    U: Desc<'a, JClass<'u>>, 

Tests whether class1 is assignable from class2.

pub fn is_instance_of<'c, O, T>(&self, object: O, class: T) -> Result<bool> where
    O: Into<JObject<'a>>,
    T: Desc<'a, JClass<'c>>, 

Returns true if the object reference can be cast to the given type.

NB: Unlike the operator instanceof, function IsInstanceOf returns true for all classes if object is null.

See JNI documentation for details.

pub fn is_same_object<'b, 'c, O, T>(&self, ref1: O, ref2: T) -> Result<bool> where
    O: Into<JObject<'b>>,
    T: Into<JObject<'c>>, 

Returns true if ref1 and ref2 refer to the same Java object, or are both NULL. Otherwise, returns false.

pub fn throw<'e, E>(&self, obj: E) -> Result<()> where
    E: Desc<'a, JThrowable<'e>>, 

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

Examples

let _ = env.throw(("java/lang/Exception", "something bad happened"));

Defaulting to "java/lang/Exception":

let _ = env.throw("something bad happened");

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

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

Example

let _ = env.throw_new("java/lang/Exception", "something bad happened");

pub fn exception_occurred(&self) -> Result<JThrowable<'a>>

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.

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

Print exception information to the console.

pub 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.

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

Abort the JVM with an error message.

pub 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.

pub fn new_direct_byte_buffer(&self, data: &mut [u8]) -> Result<JByteBuffer<'a>>

Create a new instance of a direct java.nio.ByteBuffer.

pub fn get_direct_buffer_address(
    &self,
    buf: JByteBuffer<'_>
) -> Result<&mut [u8]>

Returns the starting address of the memory of the direct java.nio.ByteBuffer.

pub fn get_direct_buffer_capacity(&self, buf: JByteBuffer<'_>) -> Result<jlong>

Returns the capacity of the direct java.nio.ByteBuffer.

pub fn new_global_ref<O>(&self, obj: O) -> Result<GlobalRef> where
    O: Into<JObject<'a>>, 

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.

pub fn new_weak_global_ref<O>(&self, obj: O) -> Result<WeakGlobalRef> where
    O: Into<JObject<'a>>, 

Turns an object into a weak global ref.

WeakGlobalRef doesn't prevent the underlying object from been garbage collected. It's not safe to access the underlying object via WeakGlobalRef. Instead, consider using upgrade_weak_global_ref for create GlobalRef and check the GlobalRef is not null.

pub fn upgrade_weak_global_ref(
    &self,
    weak_global_ref: &WeakGlobalRef
) -> Result<GlobalRef>

Try to upgrade a weak global ref into a global ref.

Returned GlobalRef may be null if the underlying object was garbage collected.

pub fn new_local_ref<T>(&self, obj: JObject<'a>) -> Result<JObject<'a>>

Create a new local ref to an object.

Note that the object passed to this is already a local ref. This creates yet another reference to it, which is most likely not what you want.

pub fn auto_local<'b, O>(&'b self, obj: O) -> AutoLocal<'a, 'b> where
    O: Into<JObject<'a>>, 

Creates a new auto-deleted local reference.

See also with_local_frame method that can be more convenient when you create a bounded number of local references but cannot rely on automatic de-allocation (e.g., in case of recursion, deep call stacks, permanently-attached native threads, etc.).

pub fn delete_local_ref(&self, obj: JObject<'_>) -> Result<()>

Deletes the local reference.

Local references are valid for the duration of a native method call. They are freed automatically after the native method returns. Each local reference costs some amount of Java Virtual Machine resource. Programmers need to make sure that native methods do not excessively allocate local references. Although local references are automatically freed after the native method returns to Java, excessive allocation of local references may cause the VM to run out of memory during the execution of a native method.

In most cases it is better to use AutoLocal (see auto_local method) or with_local_frame instead of direct delete_local_ref calls.

pub fn push_local_frame(&self, capacity: i32) -> Result<()>

Creates a new local reference frame, in which at least a given number of local references can be created.

Returns Err on failure, with a pending OutOfMemoryError.

Prefer to use with_local_frame instead of direct push_local_frame/pop_local_frame calls.

See also auto_local method and AutoLocal type — that approach can be more convenient in loops.

pub fn pop_local_frame(&self, result: JObject<'a>) -> Result<JObject<'a>>

Pops off the current local reference frame, frees all the local references allocated on the current stack frame, except the result, which is returned from this function and remains valid.

The resulting JObject will be NULL iff result is NULL.

pub fn with_local_frame<F>(&self, capacity: i32, f: F) -> Result<JObject<'a>> where
    F: FnOnce() -> Result<JObject<'a>>, 

Executes the given function in a new local reference frame, in which at least a given number of references can be created. Once this method returns, all references allocated in the frame are freed, except the one that the function returns, which remains valid.

If no new frames can be allocated, returns Err with a pending OutOfMemoryError.

See also auto_local method and AutoLocal type - that approach can be more convenient in loops.

pub fn alloc_object<'c, T>(&self, class: T) -> Result<JObject<'a>> where
    T: Desc<'a, JClass<'c>>, 

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

pub fn get_method_id<'c, T, U, V>(
    &self,
    class: T,
    name: U,
    sig: V
) -> Result<JMethodID<'a>> where
    T: Desc<'a, JClass<'c>>,
    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;");

pub fn get_static_method_id<'c, T, U, V>(
    &self,
    class: T,
    name: U,
    sig: V
) -> Result<JStaticMethodID<'a>> where
    T: Desc<'a, JClass<'c>>,
    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;");

pub fn get_field_id<'c, T, U, V>(
    &self,
    class: T,
    name: U,
    sig: V
) -> Result<JFieldID<'a>> where
    T: Desc<'a, JClass<'c>>,
    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");

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

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

Example

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

pub fn get_object_class<'b, O>(&self, obj: O) -> Result<JClass<'a>> where
    O: Into<JObject<'b>>, 

Get the class for an object.

pub fn call_static_method_unchecked<'c, 'm, T, U>(
    &self,
    class: T,
    method_id: U,
    ret: JavaType,
    args: &[JValue<'_>]
) -> Result<JValue<'a>> where
    T: Desc<'a, JClass<'c>>,
    U: Desc<'a, JStaticMethodID<'m>>, 

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.

pub fn call_method_unchecked<'m, O, T>(
    &self,
    obj: O,
    method_id: T,
    ret: JavaType,
    args: &[JValue<'_>]
) -> Result<JValue<'a>> where
    O: Into<JObject<'a>>,
    T: Desc<'a, JMethodID<'m>>, 

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.

pub fn call_method<O, S, T>(
    &self,
    obj: O,
    name: S,
    sig: T,
    args: &[JValue<'_>]
) -> Result<JValue<'a>> where
    O: Into<JObject<'a>>,
    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_unchecked 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.

pub fn call_static_method<'c, T, U, V>(
    &self,
    class: T,
    name: U,
    sig: V,
    args: &[JValue<'_>]
) -> Result<JValue<'a>> where
    T: Desc<'a, JClass<'c>>,
    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_unchecked 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.

pub fn new_object<'c, T, U>(
    &self,
    class: T,
    ctor_sig: U,
    ctor_args: &[JValue<'_>]
) -> Result<JObject<'a>> where
    T: Desc<'a, JClass<'c>>,
    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.

pub fn new_object_unchecked<'c, T>(
    &self,
    class: T,
    ctor_id: JMethodID<'_>,
    ctor_args: &[JValue<'_>]
) -> Result<JObject<'a>> where
    T: Desc<'a, JClass<'c>>, 

Create a new object using a constructor. Arguments aren't checked because of the JMethodID usage.

pub fn get_list(&self, obj: JObject<'a>) -> Result<JList<'a, '_>>

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

pub fn get_map(&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.

pub fn get_string(&self, obj: JString<'a>) -> Result<JavaStr<'a, '_>>

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.

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

Get a pointer to the character array beneath a JString.

Array contains Java's modified UTF-8.

Attention

This will leak memory if release_string_utf_chars is never called.

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

Unpin the array returned by get_string_utf_chars.

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

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.

pub fn get_array_length(&self, array: jarray) -> Result<jsize>

Get the length of a java array

pub fn new_object_array<'c, T, U>(
    &self,
    length: jsize,
    element_class: T,
    initial_element: U
) -> Result<jobjectArray> where
    T: Desc<'a, JClass<'c>>,
    U: Into<JObject<'a>>, 

Construct a new array holding objects in class element_class. All elements are initially set to initial_element.

This function returns a local reference, that must not be allocated excessively. See [Java documentation][1] for details. [1]: https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/design.html#global_and_local_references

pub fn get_object_array_element(
    &self,
    array: jobjectArray,
    index: jsize
) -> Result<JObject<'a>>

Returns an element of the jobjectArray array.

pub fn set_object_array_element<O>(
    &self,
    array: jobjectArray,
    index: jsize,
    value: O
) -> Result<()> where
    O: Into<JObject<'a>>, 

Sets an element of the jobjectArray array.

pub fn byte_array_from_slice(&self, buf: &[u8]) -> Result<jbyteArray>

Create a new java byte array from a rust byte slice.

pub fn convert_byte_array(&self, array: jbyteArray) -> Result<Vec<u8>>

Converts a java byte array to a rust vector of bytes.

pub fn new_boolean_array(&self, length: jsize) -> Result<jbooleanArray>

Create a new java boolean array of supplied length.

pub fn new_byte_array(&self, length: jsize) -> Result<jbyteArray>

Create a new java byte array of supplied length.

pub fn new_char_array(&self, length: jsize) -> Result<jcharArray>

Create a new java char array of supplied length.

pub fn new_short_array(&self, length: jsize) -> Result<jshortArray>

Create a new java short array of supplied length.

pub fn new_int_array(&self, length: jsize) -> Result<jintArray>

Create a new java int array of supplied length.

pub fn new_long_array(&self, length: jsize) -> Result<jlongArray>

Create a new java long array of supplied length.

pub fn new_float_array(&self, length: jsize) -> Result<jfloatArray>

Create a new java float array of supplied length.

pub fn new_double_array(&self, length: jsize) -> Result<jdoubleArray>

Create a new java double array of supplied length.

pub fn get_boolean_array_region(
    &self,
    array: jbooleanArray,
    start: jsize,
    buf: &mut [jboolean]
) -> Result<()>

Copy elements of the java boolean array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn get_byte_array_region(
    &self,
    array: jbyteArray,
    start: jsize,
    buf: &mut [jbyte]
) -> Result<()>

Copy elements of the java byte array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn get_char_array_region(
    &self,
    array: jcharArray,
    start: jsize,
    buf: &mut [jchar]
) -> Result<()>

Copy elements of the java char array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn get_short_array_region(
    &self,
    array: jshortArray,
    start: jsize,
    buf: &mut [jshort]
) -> Result<()>

Copy elements of the java short array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn get_int_array_region(
    &self,
    array: jintArray,
    start: jsize,
    buf: &mut [jint]
) -> Result<()>

Copy elements of the java int array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn get_long_array_region(
    &self,
    array: jlongArray,
    start: jsize,
    buf: &mut [jlong]
) -> Result<()>

Copy elements of the java long array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn get_float_array_region(
    &self,
    array: jfloatArray,
    start: jsize,
    buf: &mut [jfloat]
) -> Result<()>

Copy elements of the java float array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn get_double_array_region(
    &self,
    array: jdoubleArray,
    start: jsize,
    buf: &mut [jdouble]
) -> Result<()>

Copy elements of the java double array from the start index to the buf slice. The number of copied elements is equal to the buf length.

Errors

If start is negative or start + buf.len() is greater than array.length then no elements are copied, an ArrayIndexOutOfBoundsException is thrown, and Err is returned.

pub fn set_boolean_array_region(
    &self,
    array: jbooleanArray,
    start: jsize,
    buf: &[jboolean]
) -> Result<()>

Copy the contents of the buf slice to the java boolean array at the start index.

pub fn set_byte_array_region(
    &self,
    array: jbyteArray,
    start: jsize,
    buf: &[jbyte]
) -> Result<()>

Copy the contents of the buf slice to the java byte array at the start index.

pub fn set_char_array_region(
    &self,
    array: jcharArray,
    start: jsize,
    buf: &[jchar]
) -> Result<()>

Copy the contents of the buf slice to the java char array at the start index.

pub fn set_short_array_region(
    &self,
    array: jshortArray,
    start: jsize,
    buf: &[jshort]
) -> Result<()>

Copy the contents of the buf slice to the java short array at the start index.

pub fn set_int_array_region(
    &self,
    array: jintArray,
    start: jsize,
    buf: &[jint]
) -> Result<()>

Copy the contents of the buf slice to the java int array at the start index.

pub fn set_long_array_region(
    &self,
    array: jlongArray,
    start: jsize,
    buf: &[jlong]
) -> Result<()>

Copy the contents of the buf slice to the java long array at the start index.

pub fn set_float_array_region(
    &self,
    array: jfloatArray,
    start: jsize,
    buf: &[jfloat]
) -> Result<()>

Copy the contents of the buf slice to the java float array at the start index.

pub fn set_double_array_region(
    &self,
    array: jdoubleArray,
    start: jsize,
    buf: &[jdouble]
) -> Result<()>

Copy the contents of the buf slice to the java double array at the start index.

pub fn get_field_unchecked<'f, O, T>(
    &self,
    obj: O,
    field: T,
    ty: JavaType
) -> Result<JValue<'a>> where
    O: Into<JObject<'a>>,
    T: Desc<'a, JFieldID<'f>>, 

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

pub fn set_field_unchecked<'f, O, T>(
    &self,
    obj: O,
    field: T,
    val: JValue<'_>
) -> Result<()> where
    O: Into<JObject<'a>>,
    T: Desc<'a, JFieldID<'f>>, 

Set a field without any type checking.

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

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

pub fn set_field<O, S, T>(
    &self,
    obj: O,
    name: S,
    ty: T,
    val: JValue<'_>
) -> Result<()> where
    O: Into<JObject<'a>>,
    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.

pub fn get_static_field_unchecked<'c, 'f, T, U>(
    &self,
    class: T,
    field: U,
    ty: JavaType
) -> Result<JValue<'a>> where
    T: Desc<'a, JClass<'c>>,
    U: Desc<'a, JStaticFieldID<'f>>, 

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

pub fn get_static_field<'c, T, U, V>(
    &self,
    class: T,
    field: U,
    sig: V
) -> Result<JValue<'a>> where
    T: Desc<'a, JClass<'c>>,
    U: Into<JNIString>,
    V: Into<JNIString> + AsRef<str>, 

Get a static field. Requires a class lookup and a field id lookup internally.

pub fn set_static_field<'c, 'f, T, U>(
    &self,
    class: T,
    field: U,
    value: JValue<'_>
) -> Result<()> where
    T: Desc<'a, JClass<'c>>,
    U: Desc<'a, JStaticFieldID<'f>>, 

Set a static field. Requires a class lookup and a field id lookup internally.

pub fn set_rust_field<O, S, T>(
    &self,
    obj: O,
    field: S,
    rust_object: T
) -> Result<()> where
    O: Into<JObject<'a>>,
    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.

pub fn get_rust_field<O, S, T>(
    &self,
    obj: O,
    field: S
) -> Result<MutexGuard<'_, T>> where
    O: Into<JObject<'a>>,
    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.

pub fn take_rust_field<O, S, T>(&self, obj: O, field: S) -> Result<T> where
    O: Into<JObject<'a>>,
    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.

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

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

pub fn get_native_interface(&self) -> *mut JNIEnv

Returns underlying sys::JNIEnv interface.

pub fn get_java_vm(&self) -> Result<JavaVM>

Returns the Java VM interface.

pub fn ensure_local_capacity(&self, capacity: jint) -> Result<()>

Ensures that at least a given number of local references can be created in the current thread.

pub fn register_native_methods<'c, T>(
    &self,
    class: T,
    methods: &[NativeMethod]
) -> Result<()> where
    T: Desc<'a, JClass<'c>>, 

Bind function pointers to native methods of class according to method name and signature. For details see documentation.

pub fn unregister_native_methods<'c, T>(&self, class: T) -> Result<()> where
    T: Desc<'a, JClass<'c>>, 

Unbind all native methods of class.

pub fn get_byte_array_elements(
    &self,
    array: jbyteArray
) -> Result<(*mut jbyte, bool)>

Return a tuple with a pointer to elements of the given Java byte array as first element. The tuple's second element indicates if the pointed-to array is a copy or not.

The result is valid until the corresponding release_byte_array_elements() function is called. Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until release_byte_array_elements() is called.

See also [release_byte_array_elements](struct.JNIEnv.html#method. release_byte_array_elements)

pub fn release_byte_array_elements(
    &self,
    array: jbyteArray,
    elems: &mut jbyte,
    mode: ReleaseMode
) -> Result<()>

Release elements of the given byte array.

Informs the VM that the native code no longer needs access to elems. The elems argument is a pointer derived from array using the corresponding get_byte_array_elements() function. If necessary, this function copies back all changes made to elems to the original array.

The mode argument provides information on how the array buffer should be released. mode has no effect if elems is not a copy of the elements in array. Otherwise, mode has the following impact: CopyBack: Copy back the content and free the elems buffer. NoCopyBack: Free the buffer without copying back the possible changes Use commit_byte_array_elements to copy the elements without releasing the buffer (i.e. "commit mode").

In most cases, programmers pass “CopyBack” to the mode argument, to ensure consistent behavior for both pinned and copied arrays. The other option gives the programmer more control over memory management, and should be used with extreme care.

See also [commit_byte_array_elements](struct.JNIEnv.html#method. commit_byte_array_elements)

pub fn commit_byte_array_elements(
    &self,
    array: jbyteArray,
    elems: &mut jbyte
) -> Result<()>

Commit elements of the given byte array.

This function has no effect if elems is not a copy of the elements in array. Otherwise, this function copies back the content of the array (and does not free the elems buffer).

pub fn get_auto_byte_array_elements(
    &self,
    array: jbyteArray,
    mode: ReleaseMode
) -> Result<AutoByteArray<'_, '_>>

Return an AutoByteArray of the given Java byte array.

The result is valid until the AutoByteArray object goes out of scope, when the release happens automatically according to the mode parameter.

Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until release_array_elements() is called. AutoByteArray has a commit() method, to force a copy of the array if needed (and without releasing it).

See also [get_byte_array_elements](struct.JNIEnv.html#method. get_byte_array_elements)

pub fn get_primitive_array_critical(
    &self,
    array: jarray
) -> Result<(*mut c_void, bool)>

Return a tuple with a pointer to elements of the given Java primitive array as first element. The tuple's second element indicates if the pointed-to array is a copy or not.

The semantics of this function are very similar to the get_byte_array_elements function. If possible, the VM returns a pointer to the primitive array; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used.

After calling get_primitive_array_critical, the native code should not run for an extended period of time before it calls release_primitive_array_critical. We must treat the code inside this pair of functions as running in a "critical region." Inside a critical region, native code must not call other JNI functions, or any system call that may cause the current thread to block and wait for another Java thread. (For example, the current thread must not call read on a stream being written by another Java thread.)

These restrictions make it more likely that the native code will obtain an uncopied version of the array, even if the VM does not support pinning. For example, a VM may temporarily disable garbage collection when the native code is holding a pointer to an array obtained via get_primitive_array_critical.

Note that get_primitive_array_critical might still make a copy of the array if the VM internally represents arrays in a different format. Therefore, we need to check its return value against NULL for possible out of memory situations.

See also [get_byte_array_elements](struct.JNIEnv.html#method. get_byte_array_elements) See also [release_primitive_array_critical](struct. JNIEnv.html#method.release_primitive_array_critical)

pub fn release_primitive_array_critical(
    &self,
    array: jarray,
    elems: &mut c_void,
    mode: ReleaseMode
) -> Result<()>

Release elements of the given array.

See get_primitive_array_critical for a discussion on how these functions can be used.

See also [get_primitive_array_critical](struct.JNIEnv.html#method. get_primitive_array_critical) See also [commit_primitive_array_critical](struct. JNIEnv.html#method.commit_primitive_array_critical)

pub fn commit_primitive_array_critical(
    &self,
    array: jbyteArray,
    elems: &mut c_void
) -> Result<()>

Commit elements of the given primitive array.

This function has no effect if elems is not a copy of the elements in array. Otherwise, this function copies back the content of the array (and does not free the elems buffer).

pub fn get_auto_primitive_array_critical(
    &self,
    array: jarray,
    mode: ReleaseMode
) -> Result<AutoPrimitiveArray<'_, '_>>

Return an AutoPrimitiveArray of the given Java primitive array.

The result is valid until the corresponding AutoPrimitiveArray object goes out of scope, when the release happens automatically according to the mode parameter.

Given that Critical sections must be as short as possible, and that they come with a number of important restrictions (see get_primitive_array_critical), use this wrapper wisely, to avoid holding the array longer that strictly necessary. In any case, you can:

• Use the manual variants instead (i.e. get/release_primitive_array_critical).
• Use std::mem::drop explicitly, to force / anticipate resource release.
• Use a nested scope, to release the array at the nested scope's exit.

Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until release_primitive_array_critical() is called; which happens at AutoPrimitiveArray destruction. AutoPrimitiveArray also has a commit() method, to force a copy of the array if needed (without releasing it).

See also [get_primitive_array_critical](struct.JNIEnv.html#method. get_primitive_array_critical)

Trait Implementations

impl<'a> Clone for JNIEnv<'a>

fn clone(&self) -> JNIEnv<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for JNIEnv<'a>