mirror of
https://github.com/hexedtech/jni-toolbox.git
synced 2024-10-22 18:19:19 +02:00
128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
# 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())
|
|
}
|
|
```
|
|
|
|
every type that must go into/from Java must implement `IntoJava` or `FromJava` (methods will receive a `&mut JNIEnv` and can return errors).
|
|
most primitives already have them implemented. conversions are automatic and the wrapper function will invoke IntoJava/FromJava for every type,
|
|
passing an environment reference.
|
|
|
|
|
|
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.
|
|
|
|
to throw simple exceptions, it's possible to use the `exception` attribute. just pass your exception's path (must be constructable with a single string argument!)
|
|
|
|
to return pointer type values, add the `ptr` attribute
|
|
|
|
|
|
## 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))
|
|
}
|
|
```
|
|
|
|
gets turned into these two functions:
|
|
|
|
<details><summary>show macro expansion</summary>
|
|
|
|
```rust
|
|
fn connect(config: Config) -> Result<Client, ConnectionError> {
|
|
tokio().block_on(Client::connect(config))
|
|
}
|
|
|
|
#[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 rather early and intended mostly to maintain [`codemp`](https://github.com/hexedtech/codemp) java bindings, however it's also quite small and only runs at comptime, so should be rather safe to use
|