This library provides a procedural macro to make easier to write JNI-compatible code in Rust.
It can perform automatic conversion of Rust-y input and output types (see the limitations).
toml
[dependencies]
robusta_jni = "0.2"
All that's needed is a couple of attributes in the right places.
First, a #[bridge] attribute on a module will enable it to be processed by robusta.
Then, we will need a struct for every class with a native method that will be implemented in Rust,
and each of these structs will have to be annotated with a #[package] attribute
with the name of the Java package the corresponding class belongs to.
After that, the functions implemented can be written as ordinary Rust functions, and the macro will
take care of converting to and from Java types for functions marked public and with a "jni" ABI. By default if a conversion fails a Java exception is thrown.
On the other hand, if you need to call Java function from Rust, you add a "java" ABI and add a &JNIEnv parameter after self/&self/&mut self (or as first parameter if the method is static), and leave the function body empty.
On these methods you can attach a call_type attribute that manages how conversions and errors are handled: by default, #[call_type(safe)] is implied,
but you can switch to #[call_type(unchecked)] at any time, most likely with few or no code changes.
You can also force a Java type on input arguments via #[input_type] attribute, which can be useful for Android JNI development for example.
You can find an example under ./robusta-example. To run it you should have java and javac on your PATH and then execute:
```bash $ cd robusta-example $ make java_run
make installed:$ cargo build && javac com/example/robusta/HelloWorld.java && RUST_BACKTRACE=full java -Djava.library.path=../target/debug com.example.robusta.HelloWorld ```
You can find an example of Robusta used for Android in ./robusta-android-example.
To run it, open the project robustaAndroidExample with Android Studio.
Cargo build is automatically run by grable.
The rust lib.rs is the image of the Java class RobustaAndroidExample.
This example only gets the files authorized path of the App.
```rust use robustajni::bridge; use robustajni::convert::Signature;
mod jni { #[derive(Signature)] #[package(com.example.robusta)] struct HelloWorld;
impl HelloWorld {
pub extern "jni" fn special(mut input1: Vec<i32>, input2: i32) -> Vec<String> {
input1.push(input2);
input1.iter().map(ToString::to_string).collect()
}
}
} ```
```java package com.example.robusta;
import java.util.*;
class HelloWorld {
private static native ArrayList
static {
System.loadLibrary("robusta_example");
}
public static void main(String[] args) {
ArrayList<String> output = HelloWorld.special(new ArrayList<Integer>(List.of(1, 2, 3)), 4);
System.out.println(output)
}
} ```
There are four traits that control how Rust types are converted to/from Java types:
(Try)FromJavaValue and (Try)IntoJavaValue.
These traits are used for input and output types respectively, and implementing them is necessary to allow the library to perform automatic type conversion.
These traits make use of type provided by the jni crate,
however to provide maximum compatibility with robusta, we suggest using the re-exported version under robusta_jni::jni.
You can make a Rust native method raise a Java exception simply by returning a jni::errors::Result with an Err variant.
| Rust | Java |
|------------------------------------------------------------------------------------|-----------------------------------|
| i32 | int |
| bool | boolean |
| char | char |
| i8 | byte |
| f32 | float |
| f64 | double |
| i64 | long |
| i16 | short |
| String | String |
| Vec\
† Type parameter T must implement proper conversion types
‡ The special 'env lifetime must be used
Currently there are some limitations in the conversion mechanism:
* Boxed types are supported only through the opaque JObject/jobject types
* Automatic type conversion is limited to the table outlined above, though easily extendable if needed.
I glady accept external contributions! :)