Struct j4rs::Jvm

pub struct Jvm { /* private fields */ }

Holds the assets for the JVM

Implementations

impl Jvm

pub fn new( jvm_options: &[String], lib_name_to_load: Option<String> ) -> Result<Jvm>

Creates a new Jvm.

pub fn attach_thread() -> Result<Jvm>

Attaches the current thread to an active JavaVM

pub fn attach_thread_with_no_detach_on_drop() -> Result<Jvm>

Attaches the current thread to an active JavaVM and instructs that the Jvm will detach the Java JVM from the thread when the rust Jvm is dropped.

This is useful when creating a Jvm while on a Thread that is created in the Java world. When this Jvm is dropped, we don’t want to detach the thread from the Java VM.

pub fn detach_thread_on_drop(&mut self, detach: bool)

If false, the thread will not be detached when the Jvm is being dropped. This is useful when creating a Jvm while on a Thread that is created in the Java world. When this Jvm is dropped, we don’t want to detach the thread from the Java VM.

It prevents errors like: attempting to detach while still running code

pub unsafe fn try_from(jni_environment: *mut JNIEnv) -> Result<Jvm>

pub fn create_instance( &self, class_name: &str, inv_args: &[impl Borrow<InvocationArg>] ) -> Result<Instance>

Creates an Instance of the class class_name, passing an array of InvocationArgs to construct the instance.

pub fn static_class(&self, class_name: &str) -> Result<Instance>

Retrieves the static class class_name.

pub fn create_java_array( &self, class_name: &str, inv_args: &[impl Borrow<InvocationArg>] ) -> Result<Instance>

Creates a new Java Array with elements of the class class_name. The array will have the InvocationArgs populated. The InvocationArgs must be of type class_name.

pub fn create_java_list( &self, class_name: &str, inv_args: &[InvocationArg] ) -> Result<Instance>

👎Deprecated since 0.15.0: Please use java_list instead

Creates a new Java List with elements of the class class_name. The array will have the InvocationArgs populated. The InvocationArgs must be of type class_name.

pub fn java_list<'a>( &self, inner_class_name: impl Into<&'a str>, inv_args: Vec<impl TryInto<InvocationArg, Error = J4RsError>> ) -> Result<Instance>

Creates a new Java List with elements of the class inner_class_name.

pub fn java_map<'a>( &self, key_class_name: impl Into<&'a str>, value_class_name: impl Into<&'a str>, inv_args: HashMap<impl TryInto<InvocationArg, Error = J4RsError>, impl TryInto<InvocationArg, Error = J4RsError>> ) -> Result<Instance>

Creates a new Java Map with keys of class key_class_name and values of class value_class_name.

pub fn invoke( &self, instance: &Instance, method_name: &str, inv_args: &[impl Borrow<InvocationArg>] ) -> Result<Instance>

Invokes the method method_name of a created Instance, passing an array of InvocationArgs. It returns an Instance as the result of the invocation.

pub fn field(&self, instance: &Instance, field_name: &str) -> Result<Instance>

Retrieves the field field_name of a created Instance.

pub fn static_class_field( &self, class_name: &str, field_name: &str ) -> Result<Instance>

Retrieves the field field_name of a static class.

pub fn invoke_to_channel( &self, instance: &Instance, method_name: &str, inv_args: &[impl Borrow<InvocationArg>] ) -> Result<InstanceReceiver>

Invokes the method method_name of a created Instance, passing an array of InvocationArgs. It returns a Result of InstanceReceiver that may be used to get an underlying Receiver<Instance>. The result of the invocation will come via this Receiver.

pub fn init_callback_channel( &self, instance: &Instance ) -> Result<InstanceReceiver>

Initializes a callback channel via a Java Instance that is a NativeCallbackToRustChannelSupport. It returns a Result of InstanceReceiver that may be used to get an underlying Receiver<Instance>. The NativeCallbackToRustChannelSupport Instance which is passed as argument, will be sending Instances via this Receiver.

pub fn invoke_static( &self, class_name: &str, method_name: &str, inv_args: &[impl Borrow<InvocationArg>] ) -> Result<Instance>

Invokes the static method method_name of the class class_name, passing an array of InvocationArgs. It returns an Instance as the result of the invocation.

pub fn clone_instance(&self, instance: &Instance) -> Result<Instance>

Creates a clone of the provided Instance

pub fn cast(&self, from_instance: &Instance, to_class: &str) -> Result<Instance>

Invokes the static method method_name of the class class_name, passing an array of InvocationArgs. It returns an Instance as the result of the invocation.

pub fn to_rust_boxed<T>(&self, instance: Instance) -> Result<Box<T>>

where T: DeserializeOwned + Any,

Returns the Rust representation of the provided instance, boxed

pub fn to_rust<T>(&self, instance: Instance) -> Result<T>

where T: DeserializeOwned + Any,

Returns the Rust representation of the provided instance

pub fn to_rust_deserialized<T>(&self, instance: Instance) -> Result<T>

where T: DeserializeOwned + Any,

pub fn deploy_artifact<T: Any + JavaArtifact>(&self, artifact: &T) -> Result<()>

Deploys an artifact in the default j4rs jars location.

This is useful for build scripts that need jars for the runtime that can be downloaded from e.g. Maven.

The function deploys only the specified artifact, not its transitive dependencies.

pub fn copy_j4rs_libs_under(path: &str) -> Result<()>

Copies the jassets default directory and the j4rs dynamic library under the specified location. This is useful for cases when with_base_path method is used when building a Jvm with the JvmBuilder. Build scripts should use this method.

pub fn chain(&self, instance: &Instance) -> Result<ChainableInstance<'_>>

Initiates a chain of operations on Instances.

pub fn into_chain(&self, instance: Instance) -> ChainableInstance<'_>

Initiates a chain of operations on Instances.

pub fn throw_invocation_exception(&self, message: &str) -> Result<()>

Throws an exception in the Java World

pub fn select( instance_receivers: &[&InstanceReceiver] ) -> Result<(usize, Instance)>

Returns the first Instance that is available from the passed InstanceReceivers, along with the index of the receiver that was selected and actually returned the instance.

This is a mostly naive implementation of select, because of absence for selecting among mpsc channels.

pub fn select_timeout( instance_receivers: &[&InstanceReceiver], timeout: &Duration ) -> Result<(usize, Instance)>

Returns the first Instance that is available from the passed InstanceReceivers, along with the index of the receiver that was selected and actually returned the instance.

If there are no instances returned for the duration defined in timeout argument, an error is returned.

This is a mostly naive implementation of select, because of absence for selecting among mpsc channels.

impl Jvm

pub async fn invoke_async( &self, instance: &Instance, method_name: &str, inv_args: &[InvocationArg] ) -> Result<Instance>

Invokes the method method_name of a created Instance asynchronously, passing an array of InvocationArgs. It returns an Instance as the result of the invocation.

pub async fn invoke_into_sendable_async( instance: Instance, method_name: String, inv_args: Vec<InvocationArg> ) -> Result<Instance>

Invokes the method method_name of a created Instance asynchronously, passing an array of InvocationArgs. It returns an Instance as the result of the invocation.

Instances are Send and can be safely sent to other threads. However, because of Send Approximation, the Future returned by invoke_async is not Send, even if it just contains an Instance. This is because the Jvm is being captured by the async call as well and the Jvm is not Send.

In order to have a Future<Instance> that is Send, the Jvm::invoke_into_sendable_async can be used. This function does not get a Jvm as argument; it creates one internally when needed and applies some scoping workarounds in order to achieve returning a Future<Instance> which is also Send.

Trait Implementations

impl Clone for Jvm

fn clone(&self) -> Jvm

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Jvm

fn drop(&mut self)

Executes the destructor for this type.

impl JavaFxSupport for Jvm

fn start_javafx_app(&self) -> Result<InstanceReceiver>

Triggers the start of a JavaFX application. When the JavaFX application starts, the InstanceReceiver channel will receive an Instance of javafx.stage.Stage.

The UI may start being built using the provided Stage

fn get_javafx_event_receiver( &self, instance: &Instance, fx_event_type: FxEventType ) -> Result<InstanceReceiver>

Creates an instance receiver that will be receiving Instances of events. The fx_event_type argument is the type of the event that we want to handle and receive Instances for.

For example, to create an InstanceReceiver for a ‘javafx.scene.control.Button’, you need to call the method by using the button as the instance argument FxEventType::ActionEvent_Action as the fx_event_type argument

fn on_close_event_receiver(&self, stage: &Instance) -> Result<InstanceReceiver>

Creates an instance receiver that will be receiving Instances of events for onclose requests of a Stage.

The instance passed as argument needs to be of class javafx.stage.Stage.

fn deploy_javafx_dependencies(&self) -> Result<()>

Deploys the required dependencies to run a JavaFX application in order to be able to be used by j4rs.

fn load_fxml(&self, path: &PathBuf, stage: &Instance) -> Result<FxController>

Loads a FXML and returns a Result of a FxController for it.