Struct InitArgsBuilder

pub struct InitArgsBuilder<'a> { /* private fields */ }

Builder for JavaVM InitArgs.

This API requires “invocation” feature to be enabled, see “Launching JVM from Rust”.

Implementations

impl<'a> InitArgsBuilder<'a>

pub fn new() -> Self

Create a new default InitArgsBuilder

pub fn option(self, opt_string: impl AsRef<str> + Into<Cow<'a, str>>) -> Self

Adds a JVM option, such as -Djavax.net.debug=all.

See the JNI specification for details on which options are accepted.

The vfprintf, abort, and exit options are unsupported at this time. Setting one of these options has no effect.

The option must not contain any U+0000 code points except one at the end. A U+0000 code point at the end is not required, but on platforms where UTF-8 is the default character encoding, including one U+0000 code point at the end will make this method run slightly faster.

Errors

This method can fail if:

• opt_string contains a U+0000 code point before the end.
• opt_string cannot be represented in the platform default character encoding.
• the platform’s character encoding conversion API reports some other error.
• opt_string is too long. (In the current implementation, the maximum allowed length is 1048576 bytes on Windows. There is currently no limit on other platforms.)

Errors raised by this method are deferred. If an error occurs, it is returned from InitArgsBuilder::build instead.

pub fn try_option( &mut self, opt_string: impl Into<Cow<'a, str>>, ) -> Result<(), JvmError>

Adds a JVM option, such as -Djavax.net.debug=all. Returns an error immediately upon failure.

This is an alternative to InitArgsBuilder::option that does not defer errors. See below for details.

See the JNI specification for details on which options are accepted.

The vfprintf, abort, and exit options are unsupported at this time. Setting one of these options has no effect.

The option must not contain any U+0000 code points except one at the end. A U+0000 code point at the end is not required, but on platforms where UTF-8 is the default character encoding, including one U+0000 code point at the end will make this method run slightly faster.

Errors

This method can fail if:

• opt_string contains a U+0000 code point before the end.
• opt_string cannot be represented in the platform default character encoding.
• the platform’s character encoding conversion API reports some other error.
• opt_string is too long. (In the current implementation, the maximum allowed length is 1048576 bytes on Windows. There is currently no limit on other platforms.)

Unlike the option method, this one does not defer errors. If the opt_string cannot be used, then this method returns Err and self is not changed. If there is already a deferred error, however, then this method does nothing.

pub fn option_encoded(self, opt_string: impl Into<Cow<'a, CStr>>) -> Self

Adds a JVM option, such as -Djavax.net.debug=all. The option must be a CStr encoded in the platform default character encoding.

This is an alternative to InitArgsBuilder::option that does not do any encoding. This method is not unsafe as it cannot cause undefined behavior, but the option will be garbled (that is, become mojibake) if not encoded correctly.

See the JNI specification for details on which options are accepted.

The vfprintf, abort, and exit options are unsupported at this time. Setting one of these options has no effect.

This method does not fail, and will neither return nor defer an error.

pub fn version(self, version: JNIVersion) -> Self

Set JNI version for the init args

Default: V8

pub fn ignore_unrecognized(self, ignore: bool) -> Self

Set the ignoreUnrecognized init arg flag

If ignoreUnrecognized is true, JavaVM::new ignores all unrecognized option strings that begin with “-X” or “_”. If ignoreUnrecognized is false, JavaVM::new returns Err as soon as it encounters any unrecognized option strings.

Default: false

pub fn build(self) -> Result<InitArgs<'a>, JvmError>

Build the InitArgs

Errors

If a call to InitArgsBuilder::option caused a deferred error, it is returned from this method.

pub fn options(&self) -> Result<&[Cow<'a, CStr>], &JvmError>

Returns collected options.

If a call to InitArgsBuilder::option caused a deferred error, then this method returns a reference to that error.

Trait Implementations

impl<'a> Debug for InitArgsBuilder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for InitArgsBuilder<'a>

fn default() -> Self

Returns the “default value” for a type.