repository·main·Indexed 42 days ago
https://github.com/duchess-rs/duchessA Rust crate providing ergonomic and efficient interoperability with Java. It allows developers to reflect Java classes into Rust using the `java_package!` macro, invoke Java methods with Rust-idiomatic snake_case syntax via lazy `JvmOp` execution, and implement Java native methods in Rust.
Duchess allows you to reflect Java classes into Rust and invoke methods on Java objects safely and efficiently. You can instantiate Java classes and call their methods using a syntax that maps Java's object-oriented patterns to Rust's ergonomic patterns.
Key workflow steps:
.new().execute()? to get a Java<T> handle.java::util::Date::new())..execute()? at the end of method calls to perform the actual interop operation.// Example: Calling Java methods from Rust
let logger: Java<log::Logger> = log::Logger::new().execute()?;
logger
.add_event(
log::Event::builder()
.with_time(java::util::Date::new())
.with_name("foo")
.build(),
)
.execute()?;The test-crates directory contains crates designed to test the end-to-end behavior of duchess. This setup is specifically used to validate different CLASSPATH configurations and to test integration with real-world libraries that are too large to be bundled directly in the repository.
Tests are organized into two main categories based on which language initiates the application:
ui (Rust-initiated): Rust tests that verify the ability of applications started in Rust to interoperate with Java.java_ui (Java-initiated): Java tests that verify the ability of applications started in Java to interoperate with Rust.Execution Order:
java_ui tests are run after the completion of the Rust ui tests. This sequence is required because the Rust tests in the ui directory are compiled into .so files, which the Java tests then consume.
The JavaObject trait is an unsafe trait used to represent Java types in Rust. When a struct S implements JavaObject, it guarantees that every &S reference corresponds to a valid JNI local or global reference.
Construction Pattern: To prevent users from creating invalid Java object references, Duchess uses a pattern where:
duchess::java::lang::Object) have private fields that make them impossible to construct via safe Rust code.Object::new, which returns an implementation of the JavaConstructor trait.Local wrapper, which is the only safe way to obtain a reference to a JNI-managed object.Duchess uses Jvm::with to provide access to the JVM. This method guarantees that:
Thread Attachment Lifecycle:
AttachCurrentThread method.Jvm::with closure returns, the thread is automatically detached.Optimization:
If you want to avoid the overhead of attaching and detaching for every call, you can use Jvm::attach_thread_permanently to set the thread-local variable to a permanent state, which prevents automatic detaching.
// Example concept: Jvm::with manages attachment automatically
Jvm::with(|jvm| {
// The thread is guaranteed to be attached here
});
// The thread is detached here (unless attached permanently)Transitive upcasts are computed by iteratively growing a map of types and their supertypes.
C is mapped to its direct supertypes.C, it fetches the supertypes of its direct supertypes D and performs a union of those supertypes into the set for C.Substitution: When dealing with generics, the system accounts for substitution. If a class Foo extends a generic class Baz<X>, the generic parameter X is substituted into the type definition of Baz during the upcast process.
Duchess does not support nested JNI local frames. This is a deliberate design choice to simplify the API and avoid requiring users to pass a 'context' or 'environment' object into every single method call.
Implications:
MyObject returns a Local<'jvm, ReturnType>, the lifetime 'jvm is derived directly from the lifetime of &'jvm self.In Duchess, Java objects are represented by a dummy Rust struct that implements the JavaObject trait.
To maintain memory safety and the JNI invariant, users are never allowed to own these dummy structs directly. Instead, they interact with Java objects through specific pointer types (Local or Global) that ensure every &MyObject reference is actually a valid sys::jobject pointer. The lifetime of these references is tied to the JVM's local frame length.
// Example of the internal representation pattern
pub struct MyObject {
_dummy: ()
}
unsafe impl JavaObject for MyObject { }JVM operations in Duchess are lazy. Instead of executing immediately, you compose them using a series of method calls to build up a sequence of actions. This lazy composition allows Duchess to optimize the execution by reducing the number of JNI (Java Native Interface) invocations, which improves performance.
To run the composed operations, you must call the execute method and provide a mutable reference to a Jvm instance.
Duchess handles the linking of libjvm in two ways:
By default, the dylibjvm feature is enabled. Duchess will dynamically load and link libjvm at runtime. It searches for libjvm in the following order:
JAVA_HOME.java executable on your PATH.If you disable the dylibjvm feature, libjvm must be statically linked.
For non-standard installations, you can use JvmBuilder to configure the JVM location.
The Upcast trait is used to encode extends and implements relationships between Java classes and interfaces within Rust. It supports both direct supertypes and indirect (transitive) supertypes.
For example, if a Java hierarchy is defined as:
class Foo extends Bar { }
class Bar implements Serializable { }Then the Rust representation of Foo will implement Upcast for:
Bar (direct superclass)java::io::Serializable (transitive interface via Bar)java::lang::Object (transitive superclass via Bar)Limitation: Transitive upcasts are only computed up to the "water's edge". This means upcasting stops once the traversal encounters classes that are outside the current package being reflected into Rust.
To mimic Java's inheritance and method lookup, Duchess uses ViewAs structs that form a Deref chain based on the C3 linearization algorithm.
For a class X, a ViewAsXObj<J, N> struct is created where:
J is the original subtype.N is the next type in the MRO (the remainder of the chain).The Deref Chain:
If Foo extends Bar, Baz, the type Foo derefs through a chain:
ViewAsFooObj<Foo, ViewAsBarObj<Foo, ViewAsBazObj<Foo, ()>>> $\rightarrow$ ViewAsBarObj<Foo, ...> $\rightarrow$ ViewAsBazObj<Foo, ()> $\rightarrow$ ().
This allows Rust's method dispatch to walk the hierarchy to find the most specific implementation of a method.
#[repr(transparent)]
struct ViewAsXObj<J, N> {
this: J,
phantom: PhantomData<N>,
}
impl<J, N> Deref for ViewAsXObj<J, N> {
type Target = N;
fn deref(&self) -> &Self::Target {
// ...
}
}