Overview

When using the crate, I couldn't find a way of accessing long array elements in a convenient away. I had a look at JNIEnv#get_byte_array_elements and figured that we can add a similar approach for accessing long arrays.

Definition of Done

• [x] There are no TODOs left in the code
• [x] Change is covered by automated tests
• [x] The coding guidelines are followed
• [x] Public API has documentation
• [x] This change is not breaking or mentioned in the Changelog
• [x] The continuous integration build passes

Overview

This PR adds the feature invocation-dyn. When this feature is enabled, JavaVM::new will discover the location of the JVM shared library using the java-locator crate and load it using the libloading crate, instead of relying on the system dynamic linker.

That way, there's no need to add the location of the JVM shared library to $LD_LIBRARY_PATH or %Path%, making it much easier to run a program that uses the Invocation API. With the invocation-dyn feature enabled, this crate's tests all run successfully (on my Linux and Windows machines, at least) without having to run the test_profile script. (I don't have a Mac to test on at the moment.)

This PR also adds JavaVM::with_libjvm, which takes the location of the JVM shared library from the caller instead of using java-locator.

Breaking Changes

Because the java-locator and libloading calls can both fail, JavaVM::new now returns Result<Self, StartJvmError>. StartJvmError wraps java_locator::errors::Error and libloading::Error in addition to jni::errors::Error. Code that expects it to return Result<Self, jni::errors::Error> will have to be updated.

Question

Do you want to keep the original linking scheme? I'm not sure if there are some situations where it's better to link with the JVM shared library at build time (the original invocation feature) instead of discovering and loading it at run time (the invocation-dyn feature), so I kept both. On the other hand, removing the original linking scheme would simplify both the code (build.rs, test_profile) and the documentation of this crate.

Because I don't know if we're keeping both, I haven't yet fully documented the new feature. Please let me know which way you want to proceed, and I'll finish the documentation.

Definition of Done

• [x] There are no TODOs left in the code
• [x] Change is covered by automated tests
• [x] The coding guidelines are followed
• [x] Public API has documentation
• [x] User-visible changes are mentioned in the Changelog
• [x] The continuous integration build passes

Get array elements test are failing:

The error is:

ReleasePrimitiveArrayCritical: release array failed bounds check, incorrect pointer returned ? array: 0x00007f4de007bc40 carray: 0x00007f4dd8001260
GuardedMemory(0x00007f4de445c420) base_addr=0x00007f4dd8001240 tag=0x00007f4dd8001720 user_size=24 user_data=0x00007f4dd8001260
  Header guard @0x00007f4dd8001240 is BROKEN
  Trailer guard @0x00007f4dd8001278 is OK
  User data appears to have been freed
FATAL ERROR in native method: ReleasePrimitiveArrayCritical: failed bounds check

Overview

This PR:

• Renames JNIEnv::get_string to JNIEnv::get_string_unchecked, and marks it unsafe
• Adds a new JNIEnv::get_string which checks whether the object passed in is actually a java.lang.String
• Adds a new error variant describing that the type of the parameter passed in is incorrect.

See also: #328

This PR is backwards compatible, though the code will become slightly slower due to the addition of the class check

Open questions:

• Can we optimize the find_class call for java/lang/String to be put in a once cell? Or must the lifetime of the JClass be tied to the JNIEnv's lifetime?

Definition of Done

• [x] There are no TODOs left in the code
• [x] Change is covered by automated tests
• [X] The coding guidelines are followed
• [X] Public API has documentation
• [x] User-visible changes are mentioned in the Changelog
• [ ] The continuous integration build passes

There's a number of types that could benefit from having the Default trait. I've noted at least:

JObject JString jobject jstring

... but I suspect that most of the raw/object types could safely implement this.

Overview

This is proof-of-concept code for implementing a "generic" get_array_elements() method. This is the result of a series of comments / talks, in #272 and #237.

If you think this has merit, it's interesting, or useful, I can follow up with implementing the rest of the methods, i.e. release/ commit_array_elements, and the auto versions.

I don't particularly like the approach used here, but pulling this anyway, because:

• There can be better ways to do it, and we can maybe realise them here.
• This can still be useful, in the sense that it can be converted into a macro, and used in other parts of the code base, to simplify not only these, but also similar methods.

Please let me know what you think.

Definition of Done

• [x] There are no TODOs left in the code
• [x] Change is covered by automated tests
• [x] The coding guidelines are followed
• [x] Public API has documentation
• [ ] User-visible changes are mentioned in the Changelog
• [x] The continuous integration build passes

Hi there, this is a followup draft from #222 . I'd like to work with you on the content here. A few others contributed to these materials as well. :)

Overview

Add a tutorial that introduces JNI programming with jni-rs. Build with mdbook to get a preview. One of the goals of the book is to have the reader do stuff and think about JNI/FFI in exercises. At the moment, it introduces JNI with division, debugging, and a native Counter implementation. You will see TODOs as you reach the end of the tutorial, especially on Cleaners.

Definition of Done

• [x] There are no TODOs left in the code
• [ ] Everyone is happy enough with writing style and content
• [x] The material is tested on Windows
• [x] The material is tested on Linux
• [x] The material is tested on OSX
• [ ] The authors tag is filled in
• [ ] Change is covered by automated tests
• [ ] The coding guidelines are followed
• [x] Public API has documentation
• [x] This change is not breaking or mentioned in the Changelog
• [ ] The continuous integration build passes

New functions:

• register_class_loader to register a global class loader
• unregister_class_loader to unregister a global class loader

The global class loader will be used by find_class, instead of JNIEnv::FindClass.

Overview

Please describe your changes here and list any open questions you might have.

Definition of Done

• [x] There are no TODOs left in the code
• [ ] Change is covered by automated tests
• [ ] The coding guidelines are followed
• [x] Public API has documentation
• [x] This change is not breaking or mentioned in the Changelog
• [ ] The continuous integration build passes

Overview

This PR updates the documentation for JNIEnv::get_string_utf_chars, providing more details on safety and adding error documentation. This PR also marks the function as unsafe

Open questions

• Do we want to rename this function to get_string_utf_chars_unchecked and add a checked variant, like done with get_string in #370?
• Do we want to add a newtype wrapper around the pointer with a Drop impl to avoid the potential memory leak?

See also: #371

Definition of Done

• [x] There are no TODOs left in the code
• [x] Change is covered by automated tests
• [X] The coding guidelines are followed
• [X] Public API has documentation
• [x] User-visible changes are mentioned in the Changelog
• [x] The continuous integration build passes

Overview

Fixed calculation of buffer length provided to Get*ArrayRegion() and Set*ArrayRegion() JNI functions.

Fixes #142.

Definition of Done

• [x] There are no TODOs left in the code
• [ ] Change is covered by automated tests
• [x] The coding guidelines are followed
• [x] Public API has documentation
• [x] This change is not breaking or mentioned in the Changelog
• [ ] The continuous integration build passes

This means that you cannot pass either a JObject::null() or a class id to call_static_method_unchecked, you need to pass an instance of the target class.

I believe that the call to lookup should be removed to make it possible to invoke static methods without an available instance.

Overview

This PR has the changes discussed in #392. I believe it's finally ready to merge.

This PR is the result of squashing a branch into a single commit. Here is the original, unsquashed branch.

Definition of Done

• [x] There are no TODOs left in the code
• [x] Change is covered by automated tests
• [x] The coding guidelines are followed
• [x] Public API has documentation
• [x] User-visible changes are mentioned in the Changelog
• [x] The continuous integration build passes

$ java --version openjdk 11.0.15 2022-04-19 LTS OpenJDK Runtime Environment Zulu11.56+19-CA (build 11.0.15+10-LTS) OpenJDK 64-Bit Server VM Zulu11.56+19-CA (build 11.0.15+10-LTS, mixed mode)

$ uname -a Darwin MacBook-Pro.local 20.5.0 Darwin Kernel Version 20.5.0: Sat May 8 05:10:31 PDT 2021; root:xnu-7195.121.3~9/RELEASE_ARM64_T8101 arm64

javac HelloWorld.java && java -Djava.library.path=mylib/target/debug/ HelloWorld
Exception in thread "main" java.lang.UnsatisfiedLinkError: no mylib in java.library.path: [mylib/target/debug/]
        at java.base/java.lang.ClassLoader.loadLibrary(ClassLoader.java:2673)
        at java.base/java.lang.Runtime.loadLibrary0(Runtime.java:830)
        at java.base/java.lang.System.loadLibrary(System.java:1873)
        at HelloWorld.<clinit>(HelloWorld.java:13)

Particulary to be able to call a methode with a byte array in parameter. It was possible in JNI 0.19 thanks to into but the new conversion methode doesn't work with jbyteArray.

e.g: jni-rs 0.19

    let buffer = env.new_byte_array(asset_size)?; 
    env.call_method(asset_stream, "read", "([B)I", &[buffer.into()])?;

.. This is a breaking change, though

Overview

see title

Definition of Done

• [ ] There are no TODOs left in the code
• [ ] Change is covered by automated tests
• [ ] The coding guidelines are followed
• [ ] Public API has documentation
• [ ] User-visible changes are mentioned in the Changelog
• [ ] The continuous integration build passes

Updates the requirements on libloading to permit the latest version.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

JNIEnv::{push,with}_local_frame can cause JObjects to be freed before their lifetime ends, potentially resulting in use-after-free bugs and undefined behavior.

Proof of concept:

use jni::{*, objects::*};

fn main() {
	// Initialize JVM.
	let jvm = JavaVM::new(
		InitArgsBuilder::new()
		.version(JNIVersion::V8)
		.option("-Xcheck:jni")
		.build()
		.unwrap()
	).unwrap();

	let env = jvm.attach_current_thread().unwrap();

	// Construct an object inside a local reference frame, but leak the reference out of that frame.
	let mut obj: Option<JObject<'_>> = None;

	env.with_local_frame(2, || {
		obj = Some(env.new_object(
			"java/lang/Integer",
			"(I)V",
			&[42.into()],
		).unwrap());

		Ok(JObject::null())
	}).unwrap();

	// Try to call a method on it. This will crash.
	let answer = env.call_method(
		obj.unwrap(),
		"intValue",
		"()I",
		&[],
	).unwrap().i().unwrap();

	println!("The answer is {answer}.");
}

The lifetimes of JObjects are not limited by local reference frames. They have the lifetime of the JNIEnv that created them, which is longer than the lifetime of a local reference frame created with that same JNIEnv.

This seems difficult to fix. My first thought was to make {push,with}_local_frame take a &mut self parameter (and make JNIEnv !Copy), but then it would be impossible to have any live JObjects outside of the local frame, because Rust considers the JNIEnv already borrowed.

We could make all local references (JObject, JClass, etc) behave like AutoLocal, that is, non-Copy and free-on-drop. Then we make {pop,push,with}_local_frame unsafe (or just remove them, since this would make local reference frames mostly unnecessary).

Additional benefits:

• This would solve the safety issues with AutoLocal described in #381, since there would be no (non-unsafe) way to have more than one JObject wrapping the same local reference.

• This would fix the memory leak described in #109, since JClass is now freed upon drop too.

• JNIEnv::delete_local_ref, which also can free JObjects before the end of their lifetime, would no longer be necessary and could be removed.

Drawbacks:

• This would be a pretty extensive change. Most parameters of type JObject would need to be changed to &JObject, in both this crate and user code, since it's no longer Copy. Similarly, trait bounds like T: Into<JObject> would have to be changed, perhaps to T: AsRef<JObject> (and add impl<'a> AsRef<JObject<'a>> for JObject<'a> and every type that wraps it).

• JObject and friends no longer implement Copy or Clone. From now on, the only way to duplicate a JObject is with JNIEnv::new_local_ref. I'm not sure whether that would be a nuisance or not, but if it is, then we could make it less of one by adding a new method pub fn clone<'b>(&self, env: JNIEnv<'b>) -> Result<_<'b>> to each of these types.

What do you think? Would you like me to do this?