Trait jni::descriptors::Desc

pub unsafe trait Desc<'local, T> {
    type Output: AsRef<T>;

    // Required method
    fn lookup(self, _: &mut JNIEnv<'local>) -> Result<Self::Output>;
}

Trait for things that can be looked up through the JNI via a descriptor. This will be something like the fully-qualified class name java/lang/String or a tuple containing a class descriptor, method name, and method signature. For convenience, this is also implemented for the concrete types themselves in addition to their descriptors.

Safety

Implementations of this trait must return the correct value from the lookup method. It must not, for example, return a random JMethodID or the JClass of a class other than the one requested. Returning such an incorrect value results in undefined behavior. This requirement also applies to the returned value’s implementation of AsRef<T>.

Required Associated Types

type Output: AsRef<T>

The type that this Desc returns.

Required Methods

fn lookup(self, _: &mut JNIEnv<'local>) -> Result<Self::Output>

Look up the concrete type from the JVM.

Note that this method does not return exactly T. Instead, it returns some type that implements AsRef<T>. For this reason, it is often necessary to use turbofish syntax when calling this method:

// The value returned by `lookup` is not exactly `JClass`.
let class/*: impl AsRef<JClass> */ =
    Desc::<JClass>::lookup("java/lang/Object", env)?;

// But `&JClass` can be borrowed from it.
let class: &JClass = class.as_ref();

Warning: Many built-in implementations of this trait return AutoLocal from this method. If you then call JObject::as_raw on the returned object reference, this may result in the reference being deleted before it is used, causing undefined behavior.

For example, don’t do this:

// Undefined behavior: the `JClass` is dropped before the raw pointer
// is passed to `some_function`!
some_function(Desc::<JClass>::lookup("java/lang/Object", env)?.as_raw());

Instead, do this:

let class = Desc::<JClass>::lookup("java/lang/Object", env)?;

some_function(class.as_raw());

drop(class);

This will still work without the call to drop at the end, but calling drop ensures that the reference is not accidentally dropped earlier than it should be.

Implementations on Foreign Types

impl<'local, 'other_local, T, U, V> Desc<'local, JFieldID> for (T, U, V)where T: Desc<'local, JClass<'other_local>>, U: Into<JNIString>, V: Into<JNIString>,

type Output = JFieldID

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local, 'other_local, T, U, V> Desc<'local, JStaticMethodID> for (T, U, V)where T: Desc<'local, JClass<'other_local>>, U: Into<JNIString>, V: Into<JNIString>,

type Output = JStaticMethodID

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local, 'other_local, C, M> Desc<'local, JThrowable<'local>> for (C, M)where C: Desc<'local, JClass<'other_local>>, M: Into<JNIString>,

type Output = AutoLocal<'local, JThrowable<'local>>

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local> Desc<'local, JThrowable<'local>> for String

type Output = AutoLocal<'local, JThrowable<'local>>

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local, 'other_local, T, U, V> Desc<'local, JMethodID> for (T, U, V)where T: Desc<'local, JClass<'other_local>>, U: Into<JNIString>, V: Into<JNIString>,

type Output = JMethodID

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local, 't_ref, T> Desc<'local, T> for &'t_ref Twhere T: AsRef<T>,

type Output = &'t_ref T

fn lookup(self, _: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local, 'str_ref> Desc<'local, JThrowable<'local>> for &'str_ref str

type Output = AutoLocal<'local, JThrowable<'local>>

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local, 'other_local, T, U, V> Desc<'local, JStaticFieldID> for (T, U, V)where T: Desc<'local, JClass<'other_local>>, U: Into<JNIString>, V: Into<JNIString>,

type Output = JStaticFieldID

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

impl<'local, 'other_local, T, Signature> Desc<'local, JMethodID> for (T, Signature)where T: Desc<'local, JClass<'other_local>>, Signature: Into<JNIString>,

type Output = JMethodID

fn lookup(self, env: &mut JNIEnv<'local>) -> Result<Self::Output>

Implementors

impl<'local> Desc<'local, JThrowable<'local>> for Exception

type Output = AutoLocal<'local, JThrowable<'local>>

impl<'local> Desc<'local, JThrowable<'local>> for JNIString

type Output = AutoLocal<'local, JThrowable<'local>>

impl<'local, 'obj_ref> Desc<'local, JClass<'static>> for &'obj_ref GlobalRef

This conversion assumes that the GlobalRef is a pointer to a class object.

type Output = &'obj_ref JClass<'static>

impl<'local, 'other_local, 'obj_ref, T> Desc<'local, T> for &'obj_ref AutoLocal<'other_local, T>where T: AsRef<T> + Into<JObject<'other_local>>,

type Output = &'obj_ref AutoLocal<'other_local, T>

impl<'local, 'other_local, T> Desc<'local, T> for AutoLocal<'other_local, T>where T: AsRef<T> + Into<JObject<'other_local>>,

type Output = AutoLocal<'other_local, T>

impl<'local, T> Desc<'local, JClass<'local>> for Twhere T: Into<JNIString>,

type Output = AutoLocal<'local, JClass<'local>>

impl<'local, T> Desc<'local, T> for Twhere T: AsRef<T>,

type Output = T