jni-toolbox/README.md

# jni-toolbox
[![Actions Status](https://github.com/hexedtech/jni-toolbox/actions/workflows/test.yml/badge.svg)](https://github.com/hexedtech/jni-toolbox/actions)
[![Crates.io Version](https://img.shields.io/crates/v/jni-toolbox)](https://crates.io/crates/jni-toolbox)
[![docs.rs](https://img.shields.io/docsrs/jni-toolbox)](https://docs.rs/jni-toolbox)

This is a simple crate built around [jni-rs](https://github.com/jni-rs/jni-rs) to automatically generate JNI-compatible extern functions.

It also wraps functions returning `Result<>`, making short-circuiting easy.

## Usage
Just specify package and class on your function, and done!

```rust
#[jni_toolbox::jni(package = "your.package.path", class = "ContainerClass")]
fn your_function_name(arg: String) -> Result<Vec<String>, String> {
  Ok(arg.split('/').map(|x| x.to_string()).collect())
}
```

### Conversions
Every type that is meant to be sent to Java must implement `IntoJavaObject` (or, unlikely, `IntoJavaPrimitive`); every type that is meant to be
received from Java must implement `FromJava`. Most primitives and a few common types should already be implemented.

```rust
impl<'j> IntoJavaObject for MyClass {
  type T = jni::objects::JObject<'j>
  fn into_java(self, env: &mut jni::JNIEnv<'j>) -> Result<Self::T, jni::errors::Error> {
    let hello = env.new_string("world")?;
    // TODO!!
  }
}
```

### Pointers
To return pointer type values, add the `ptr` attribute.

Note that, while it is possible to pass raw pointers to the JVM, it is not safe by default and must be done with extreme care.

### Exceptions
Errors are thrown automatically when a `Result` is an error. For your errors to work, you must implement the `JniToolboxError` trait for your errors,
(which just returns the path to your Java error class) and then make a Java error wrapper which can be constructed with a single string argument.

Functions returning `Result`s will automatically have their return value unwrapped and, if is an err, throw an exception and return early.

```rust
impl JniToolboxError for MyError {
  fn jclass(&self) -> String {
    "my/package/some/MyError".to_string()
  }
}
```

```java
package my.package.some;
public class MyError extends Throwable {
  public MyError(String x) {
    // TODO
  }
}
```

To throw simple exceptions, it's possible to use the `exception` attribute. Pass the exception's fully qualified name (must have a constructor
that takes in a single `String` argument).

### Examples
The following function:
```rust
#[jni(package = "mp.code", class = "Client", ptr)]
fn connect(config: Config) -> Result<Client, ConnectionError> {
  tokio().block_on(Client::connect(config))
}
```

generates a matching expanded function invoking it:

<details><summary>Show macro expansion</summary>

```rust
#[no_mangle]
#[allow(unused_mut)]
pub extern "system" fn Java_mp_code_Client_connect<'local>(
  mut env: jni::JNIEnv<'local>,
  _class: jni::objects::JClass<'local>,
  mut config: <Config as jni_toolbox::FromJava<'local>>::T,
) -> <Client as jni_toolbox::IntoJava<'local>>::T {
  use jni_toolbox::{FromJava, IntoJava, JniToolboxError};
  let mut env_copy = unsafe { env.unsafe_clone() };
  let config_new = match jni_toolbox::from_java_static::<Config>(&mut env, config) {
    Ok(x) => x,
    Err(e) => {
      let _ = env.throw_new(
        "java/lang/RuntimeException",
        $crate::__export::must_use({
          let res = $crate::fmt::format($crate::__export::format_args!("{e:?}"));
          res
        }),
      );
      return std::ptr::null_mut();
    }
  };
  match connect(config_new) {
    Err(e) => match env_copy.find_class(e.jclass()) {
      Err(e) => {
        $crate::panicking::panic_fmt($crate::const_format_args!(
          "error throwing Java exception -- failed resolving error class: {e}"
        ));
      }
      Ok(class) => match env_copy.new_string($crate::__export::must_use({
        let res = $crate::fmt::format($crate::__export::format_args!("{e:?}"));
        res
      })) {
        Err(e) => {
          $crate::panicking::panic_fmt($crate::const_format_args!(
            "error throwing Java exception --  failed creating error string: {e}"
          ));
        }
        Ok(msg) => match env_copy.new_object(
          class,
          "(Ljava/lang/String;)V",
          &[jni::objects::JValueGen::Object(&msg)],
        ) {
          Err(e) => {
            $crate::panicking::panic_fmt($crate::const_format_args!(
              "error throwing Java exception -- failed creating object: {e}"
            ));
          }
          Ok(obj) => match env_copy.throw(jni::objects::JThrowable::from(obj)) {
            Err(e) => {
              $crate::panicking::panic_fmt($crate::const_format_args!(
                "error throwing Java exception -- failed throwing: {e}"
              ));
            }
            Ok(_) => return std::ptr::null_mut(),
          },
        },
      },
    },
    Ok(ret) => match ret.into_java(&mut env_copy) {
      Ok(fin) => return fin,
      Err(e) => {
        let _ = env_copy.throw_new(
          "java/lang/RuntimeException",
          $crate::__export::must_use({
            let res = $crate::fmt::format($crate::__export::format_args!("{e:?}"));
            res
          }),
        );
        return std::ptr::null_mut();
      }
    },
  }
}
```
</details>


## Status
This crate is early and intended mostly to maintain [`codemp`](https://github.com/hexedtech/codemp)'s Java bindings, so things not used
there may be missing or slightly broken. However, the crate is also quite small and only runs at compile time, so trying it out in your
own project should not be a problem.