Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
j4rs
j4rs stands for 'Java for Rust' and allows effortless calls to Java code, from Rust.
Usage
Basics
use ;
// Create a JVM
let jvm = new.build.unwrap;
// Create a java.lang.String instance
let string_instance = jvm.create_instance.unwrap;
// The instances returned from invocations and instantiations can be viewed as pointers to Java Objects.
// They can be used for further Java calls.
// For example, the following invokes the `isEmpty` method of the created java.lang.String instance
let boolean_instance = jvm.invoke.unwrap;
// If we need to transform an `Instance` to Rust value, the `to_rust` should be called
let rust_boolean: bool = jvm.to_rust.unwrap;
println!;
// The above prints:
// The isEmpty() method of the java.lang.String instance returned true
// Static invocation
let _static_invocation_result = jvm.invoke_static.unwrap;
Callback support
j4rs
provides support for Java to Rust callbacks.
These callbacks come to the Rust world via Rust Channels.
In order to initialize a channel that will provide Java callback values, the Jvm::invoke_to_channel
should be called. It returns a result of InstanceReceiver
struct, which contains a Channel Receiver:
// Invoke of a method of a Java instance and get the returned value in a Rust Channel.
// Create an Instance of a class that supports Native Callbacks
// (the class just needs to extend the
// `org.astonbitecode.j4rs.api.invocation.NativeCallbackToRustChannelSupport`)
let i = jvm.create_instance
.unwrap;
// Invoke the method
let instance_receiver_res = jvm.invoke_to_channel;
// Wait for the response to come
let instance_receiver = instance_receiver_res.unwrap;
let _ = instance_receiver.rx.recv;
In the Java world, a Class that can do Native Callbacks must extend the
org.astonbitecode.j4rs.api.invocation.NativeCallbackToRustChannelSupport
For example, consider the following Java class.
The performCallback
method spawns a new Thread and invokes the doCallback
method in this Thread. The doCallback
method is inherited by the NativeCallbackToRustChannelSupport
class.
;
;
Passing arguments from Rust to Java
j4rs uses the InvocationArg
enum to pass arguments to the Java world.
Users can benefit of the existing From
implementations for several basic types:
let i1 = from; // Creates an arg of java.lang.String
let my_string = "a string".to_owned;
let i2 = from; // Creates an arg of java.lang.String
let i3 = from; // Creates an arg of java.lang.Boolean
let i4 = from; // Creates an arg of java.lang.Byte
let i5 = from; // Creates an arg of java.lang.Character
let i6 = from; // Creates an arg of java.lang.Short
let i7 = from; // Creates an arg of java.lang.Long
let i8 = from; // Creates an arg of java.lang.Float
let i9 = from; // Creates an arg of java.lang.Double
And for Vec
s:
let my_vec: = vec!;
let i10 = from;
The Instance
s returned by j4rs can be transformed to InvocationArg
s and be used for invoking methods as well:
let one_more_string_instance = jvm.create_instance.unwrap;
let i11 = from;
Casting
An Instance
may be casted to some other Class:
let instantiation_args = vec!;
let instance = jvm.create_instance.unwrap;
jvm.cast.unwrap;
Adding jars in the classpath
If we have one jar that needs to be accessed using j4rs
, we need to add it in the classpath during the JVM creation:
let entry = new;
let jvm: Jvm = new
.classpath_entry
.build
.unwrap;
j4rs Java library
The jar for j4rs
is available in the Maven Central. It may be used by adding the following dependency in a pom:
io.github.astonbitecode
j4rs
0.4.0
provided
Note that the scope
is provided
. This is because the j4rs
Java resources are always available with the j4rs
crate.
Use like this in order to avoid possible classloading errors.
j4rs Java library in Android
If you encounter any issues when using j4rs in Android, this may be caused by Java 8 compatibility problems. This is why there is a Java 7
version of j4rs
:
io.github.astonbitecode
j4rs
0.4.0-java7
Prerequisites for the compilation
- Rust is installed
- Java 8 or higher is installed
$JAVA_HOME
is set
Prerequisites for running an application that has j4rs
as dependency
- Rust is installed.
- Java 8 or higher is installed.
$LD_LIBRARY_PATH
is set and includes the directory that contains thelibjvm.so
shared library (jvm.dll
in Windows).
Note
The build script attempts to help setting up the environment as needed for the j4rs
to work. However, things can be different depending on the use case and the environment.
In a Linux host, the build script of j4rs
populates the $LD_LIBRARY_PATH
and exports it in the $CARGO_HOME/env
file. This means that it is enough to execute
source $CARGO_HOME/env
in order to export the correct $LD_LIBRARY_PATH
variable in your session.
Next?
- Implement macros to facilitate
j4rs
users
Possibly something like:
// Instantiation
let i12 = jnew!;
// Invocation
let i13 = j!;
- Improve documentation
Licence
At your option, under:
- Apache License, Version 2.0, (http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (http://opensource.org/licenses/MIT)