Struct Local 

pub struct Local<'env, T: ReferenceType> { /* private fields */ }

A Local, non-null, reference to a Java object (+ Env) limited to the current thread/stack.

Including the env allows for the convenient execution of methods without having to individually pass the env as an argument to each and every one. Since this is limited to the current thread/stack, these cannot be sanely stored in any kind of static storage, nor shared between threads - instead use a Global if you need to do either.

Will DeleteLocalRef when dropped, invalidating the jobject but ensuring threads that rarely or never return to Java may run without being guaranteed to eventually exhaust their local reference limit. If this is not desired, convert to a plain Ref with:

let local = Local::leak(local);

Not FFI Safe: #[repr(rust)], and exact layout is likely to change - depending on exact features used - in the future. Specifically, on Android, since we’re guaranteed to only have a single ambient VM, we can likely store the *const JNIEnv in thread local storage instead of lugging it around in every Local. Of course, there’s no guarantee that’s actually an optimization…

Implementations

impl<'env, T: ReferenceType> Local<'env, T>

pub unsafe fn from_raw(env: Env<'env>, object: jobject) -> Self

Wraps an owned raw JNI local reference, taking the ownership.

Safety

• object must be an owned non-null JNI local reference that belongs to env, not to be deleted by another wrapper.
• object references an instance of type T.

pub fn env(&self) -> Env<'env>

Gets the Env under which the JNI reference is valid.

pub fn as_raw(&self) -> jobject

Returns the raw JNI reference pointer.

pub fn into_raw(self) -> jobject

Leaks the Local and turns it into a raw pointer, preserving the ownership of one JNI local reference; prevents DeleteLocalRef from being called on dropping. See Local::leak.

pub fn leak(self) -> Ref<'env, T>

Leaks the Local, prevents DeleteLocalRef from being called on dropping.

If the current thread is a Java thread, it will be freed when the control flow returns to Java; otherwise it will be freed when the native thread exits.

NOTE: some JVM implementations have a strict limitation of local reference capacity, an uncatchable error will be thrown if the capacity is full.

pub fn as_global(&self) -> Global<T>

Returns a new JNI global reference of the same Java object.

pub fn as_return(&self) -> Return<'env, T>

Creates and leaks a new local reference to be returned from the JNI extern callback function. It will be freed as soon as the control flow returns to Java.

pub fn into_return(self) -> Return<'env, T>

Leaks the local reference to be returned from the JNI extern callback function. It will be freed as soon as the control flow returns to Java.

pub fn cast<U: ReferenceType>(self) -> Result<Local<'env, U>, CastError>

Tries to cast itself to a JNI reference of type U.

pub fn upcast<U: ReferenceType>(self) -> Local<'env, U>

where T: AssignableTo<U>,

Casts itself towards a super class type, without the cost of runtime checking.

Methods from Deref<Target = Ref<'env, T>>

pub fn env(&self) -> Env<'env>

Gets the Env under which the JNI reference is valid.

pub fn as_raw(&self) -> jobject

Returns the raw JNI reference pointer.

pub fn as_global(&self) -> Global<T>

Returns a new JNI global reference of the same Java object.

pub fn as_local(&self) -> Local<'env, T>

Returns a new JNI local reference of the same Java object.

pub fn as_monitor(&'env self) -> Monitor<'env, T>

Enters monitored mode or increments the JNI monitor counter in this thread for the referenced Java object. See Monitor for the limited locking functionality.

pub fn is_same_object<O: ReferenceType>(&self, other: &Ref<'_, O>) -> bool

Tests whether two JNI references refer to the same Java object.

pub unsafe fn cast_ref_unchecked<U: ReferenceType>(&self) -> &Ref<'env, U>

Casts the borrowed Ref to a JNI reference of type U forcefully, without the cost of runtime checking.

Safety

• self references an instance of type U.

pub fn cast_ref<U: ReferenceType>(&self) -> Result<&Ref<'env, U>, CastError>

Tries to cast the borrowed Ref to a JNI reference of type U.

pub fn upcast_ref<U: ReferenceType>(&self) -> &Ref<'env, U>

where T: AssignableTo<U>,

Casts the borrowed Ref towards a super class type, without the cost of runtime checking.

Trait Implementations

impl<T: ReferenceType, U: AssignableTo<T>> AsArg<T> for Local<'_, U>

fn as_arg(&self) -> jobject

impl<'env, T: ReferenceType> AsRef<Ref<'env, T>> for Local<'env, T>

fn as_ref(&self) -> &Ref<'env, T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'env, T: ReferenceType> Clone for Local<'env, T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'env, T: JavaDebug> Debug for Local<'env, T>

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

Formats the value using the given formatter.

impl<'env, T: ReferenceType> Deref for Local<'env, T>

type Target = Ref<'env, T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'env, T: JavaDisplay> Display for Local<'env, T>

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

Formats the value using the given formatter.

impl<'env, T: ReferenceType> Drop for Local<'env, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'env, T: ReferenceType> From<&Local<'env, T>> for Global<T>

fn from(x: &Local<'env, T>) -> Self

Converts to this type from the input type.

impl<'env, T: ReferenceType> From<&Local<'env, T>> for Local<'env, T>

fn from(x: &Local<'env, T>) -> Self

Converts to this type from the input type.

impl<'env, T: ReferenceType> From<&Ref<'env, T>> for Local<'env, T>

fn from(x: &Ref<'env, T>) -> Self

Converts to this type from the input type.

impl<'env, T: ReferenceType> From<Local<'env, T>> for Global<T>

fn from(x: Local<'env, T>) -> Self

Converts to this type from the input type.

impl<'env, T: ReferenceType> From<Ref<'env, T>> for Local<'env, T>

fn from(x: Ref<'env, T>) -> Self

Converts to this type from the input type.