Rust bindings to the Java Native Interface — JNI
APACHE-2.0 License
Bot releases are hidden (Show)
Published by rib over 1 year ago
While the last (0.20) release was rather conservative (just focusing on reviving the project), this release tackles some more substantial issues (including several safety issues and some bugs dating back to 2018) and as a result it was also necessary to make some breaking changes that will involve some work when updating existing jni
code.
Please see the migration guide for some guidance on how to update to this release.
JavaStr::into_raw()
which drops the JavaStr
and releases ownership of the raw string pointer (#374)JavaStr::from_raw()
which takes ownership of a raw string pointer to create a JavaStr
(#374)JNIEnv::get_string_unchecked
is a cheaper, unsafe
alternative to get_string
that doesn't check the given object is a java.lang.String
instance. (#328)WeakRef
and JNIEnv#new_weak_ref
. (#304)define_class_bytearray
method that takes an AutoElements<jbyte>
rather than a &[u8]
(#244)JObject
now has an as_raw
method that borrows the JObject
instead of taking ownership like into_raw
. Needed because JObject
no longer has the Copy
trait. (#392)JavaVM::destroy()
(unsafe) as a way to try and unload a JavaVM
on supported platforms (#391)JavaVM::detach_current_thread()
(unsafe) as a way to explicitly detach a thread (normally this is automatic on thread exit). Needed to detach daemon threads manually if using JavaVM::destroy()
(#391)JPrimitiveArray<T: TypeArray>
and type-specific aliases like JByteArray
, JIntArray
etc now provide safe, reference wrappers for the sys
types jarray
and jbyteArray
etc with a lifetime like JObject
(#400)JObjectArray
provides a reference wrapper for a jobjectArray
with a lifetime like JObject
. (#400)AutoElements
and AutoElementsCritical
(previously AutoArray
/AutoPrimitiveArray
) implement Deref<Target=[T]>
and DerefMut
so array elements can be accessed via slices without needing additional unsafe
code. (#400)AsJArrayRaw
trait which enables JNIEnv::get_array_length()
to work with JPrimitiveArray
or JObjectArray
types (#400)InitArgsBuilder
now has try_option
and option_encoded
methods. (#414)JNIEnv::get_string
checks that the given object is a java.lang.String
instance to avoid undefined behaviour from the JNI implementation potentially aborting the program. (#328)JNIEnv::call_*method_unchecked
was marked unsafe
, as passing improper argument types, or a bad number of arguments, can cause a JVM crash. (#385)JNIEnv::new_object_unchecked
function now takes arguments as &[jni::sys::jvalue]
to avoid allocating, putting it inline with changes to JniEnv::call_*_unchecked
from 0.20.0 (#382)get_superclass
function now returns an Option instead of a null pointer if the class has no superclass (#151)invocation
feature now locates the JVM implementation dynamically at runtime (via the java-locator
crate by default) instead of linking with the JVM at build time (#293)JNIEnv
methods now require &mut self
. This improves safety by preventing JObject
s from getting an invalid lifetime. Most native method implementations (that is, #[no_mangle] extern "system" fn
s) must now make the JNIEnv
parameter mut
. See the example on the crate documentation. (#392)JByteBuffer
, JClass
, JNIEnv
, JObject
, JString
, and JThrowable
no longer have the Clone
or Copy
traits. This improves safety by preventing object references from being used after the JVM deletes them. Most functions that take one of these types as a parameter (except extern fn
s that are directly called by the JVM) should now borrow it instead, e.g. &JObject
instead of JObject
. (#392)AutoLocal
is now generic in the type of object reference (JString
, etc). (#392)JNIEnv::with_local_frame
must now take a &mut JNIEnv
parameter, which has a different lifetime. This improves safety by preventing local references from escaping the closure, which would cause a use-after-free bug. Executor::with_attached
and Executor::with_attached_capacity
have been similarly changed. (#392)JNIEnv::with_local_frame
can now return a generic Result<T, E>
so long as the error implements From<jni::errors::Error>
(#399)JNIEnv::with_local_frame
now returns the same type that the given closure returns (#399)JNIEnv::with_local_frame
no longer supports returning a local reference directly to the calling scope (see with_local_frame_returning_local
) (#399)Executor::with_attached
and Executor::with_attached_capacity
have been changed in the same way as JNIEnv::with_local_frame
(they are thin wrappers) (#399)Desc
, JNIEnv::pop_local_frame
, and TypeArray
are now unsafe
. (#392)Desc
trait now has an associated type Output
. Many implementations now return AutoLocal
, so if you call Desc::lookup
yourself and then call as_raw
on the returned object, make sure the AutoLocal
isn't dropped too soon (see the Desc::lookup
documentation for examples). (#392)Desc<JClass>
trait is no longer implemented for JObject
or &JObject
. The previous implementation that called .get_object_class()
was surprising and a simpler cast would make it easy to mistakenly pass instances where a class is required. (#118)'local
instead of 'a
). The new naming convention is explained in the JNIEnv
documentation. (#392)JObject
, JClass
, AutoLocal
, GlobalRef
, etc) now implement AsRef<JObject>
and Deref<Target = JObject>
. Typed wrappers like JClass
also implement Into<JObject>
, but GlobalRef
does not. (#392)JList
and JMap
methods now require a &mut JNIEnv
parameter. JListIter
and JMapIter
no longer implement Iterator
, and instead have a next
method that requires a &mut JNIEnv
parameter (use while let
loops instead of for
). (#392)JValue
has been changed in several ways: (#392)
JValueGen
. JValue
is now a type alias for JValueGen<&JObject>
, that is, it borrows an object reference. JValueOwned
is a type alias for JValueGen<JObject>
, that is, it owns an object reference.JValueOwned
does not have the Copy
trait.to_jni
method is now named as_jni
, and it borrows the JValueGen
instead of taking ownership.JObject
can no longer be converted directly to JValue
, which was commonly done when calling Java methods or constructors. Instead of obj.into()
, use (&obj).into()
.JNIEnv
array APIs now work in terms of JPrimitiveArray
and JObjectArray
(reference wrappers with a lifetime) instead of sys
types like jarray
and jbyteArray
(#400)AutoArray
and AutoPrimitiveArray
have been renamed AutoElements
and AutoElementsCritical
to show their connection and differentiate from new JPrimitiveArray
API (#400)get_primitive_array_critical
is now unsafe
and has been renamed to get_array_elements_critical
(consistent with the rename of AutoPrimitiveArray
) with more detailed safety documentation (#400)get_array_elements
is now also unsafe
(for many of the same reasons as get_array_elements_critical
) and has detailed safety documentation (#400)AutoArray/AutoArrayCritical::size()
has been replaced with .len()
which can't fail and returns a usize
(#400)TypeArray
trait is now a private / sealed trait, that is considered to be an implementation detail for the AutoArray
API.JvmError
has several more variants and is now non_exhaustive
. (#414)InitArgsBuilder::option
raises an error on Windows if the string is too long. The limit is currently 1048576 bytes. (#414)AutoLocal
, JNIEnv::delete_local_ref
, and JNIEnv::with_local_frame
. (Most of the limitations added in #392, listed above, were needed to make this work.) (#381, #392)Desc
trait now return AutoLocal
s, which prevents them from leaking. (#109, #392)InitArgsBuilder::option
properly encodes non-ASCII characters on Windows. (#414)get_string_utf_chars
and release_string_utf_chars
from JNIEnv
(See JavaStr::into_raw()
and JavaStr::from_raw()
instead) (#372)JNIEnv::get_<type>_array_elements()
methods have been removed as redundant since they would all be equivalent to get_array_elements()
with the introduction of JPrimitiveArray
(#400)Full Changelog: https://github.com/jni-rs/jni-rs/compare/v0.20.0...v0.21.0
Published by rib about 2 years ago
Default
trait implemented for JObject
, JString
, JClass
, and JByteBuffer
(#199)Debug
trait implemented for JavaVM
, GlobalRef
, GlobalRefGuard
, JStaticMethodID
and ReleaseMode
(#345)ReturnType
for specifying object return types without a String allocation. (#329)release_string_utf_chars
function has been marked as unsafe. (#334)JNIEnv::new_direct_byte_buffer
as unsafe
(#320)JNIEnv::new_direct_byte_buffer
now takes a raw pointer and size instead of a slice (#351 and #364)JNIEnv::direct_buffer_address
returns a raw pointer instead of a slice (#364)AutoArray
is no longer tied to the lifetime of a particular JNIEnv
reference. (#302)JNIEnv::new_local_ref
. Now it can be used to create a localJMethodID
and JStaticMethodID
implement Send
+ Sync
and no longer has a lifetime parameter, making methodJFieldID
and JStaticFieldID
implement Send
+ Sync
and no longer has a lifetime parameter, making fieldcall_*_method_unchecked
functions now take jni:sys::jvalue
arguments to avoid allocatingVec
on each call to map + collect JValue
s as sys:jvalue
s (#329)From
trait implementations converting jni_sys
types like jobject
to JObject
have been replacedunsafe
::from_raw
functions and corresponding ::into_raw
methods. Existing ::into_inner
APIs were::into_raw
for symmetry. (#197)JNIEnv::set_rust_field
, JNIEnv::get_rust_field
and JNIEnv::take_rust_field
have been marked as unsafe
(#219)Full Changelog: https://github.com/jni-rs/jni-rs/compare/v0.19.0...v0.20.0
Published by dmitry-timofeev over 3 years ago
AutoArray
and generic get_array_elements()
, along with get_<type>_array_elements
helpers. (#287)size()
method to AutoArray
and AutoPrimitiveArray
. (#278 / #287)discard()
method to AutoArray
and AutoPrimitiveArray
. (#275 / #287)AutoByte/PrimitiveArray.commit()
now returns Result
. (#275)Published by dmitry-timofeev almost 4 years ago
JNIEnv#define_unnamed_class
function that allows loading a class withoutSetStatic<type>Field
. (#248)TryFrom<JValue>
for types inside JValue variants (#264).repr(transparent)
attribute to JavaVM struct (#259)error-chain
to thiserror
, making all errors Send
. Also, support all JNI errorsjni_error_code_to_result
function and add more information to the InvalidArgList
Published by stanislav-tkach about 4 years ago
Published by stanislav-tkach about 4 years ago
Published by stanislav-tkach about 4 years ago
JObject
as arguments to the majority of JNIEnv methods without explicit conversion (#213)JNIEnv#is_same_object
implementation (#213)JNIEnv#register_native_methods
(#214)Into<JObject>
to JValue::Object
null
as class loader to define_class
method now allowed according to the JNI specification. (#225)Published by stanislav-tkach about 4 years ago
Published by stanislav-tkach about 4 years ago
Published by dmitry-timofeev over 5 years ago
0.13 brings major improvements in thread management, allowing to attach the native threads
permanently and safely; Executor
for extra convenience and safety; and other
improvements and fixes.
⚠️ If your code attaches native threads — make sure to check the updated documentation
of JavaVM to learn about the new features!
JavaVM::attach_current_thread_permanently
method, which attaches the currentJavaVM::attach_current_thread_as_daemon
also automatically detach themselvesJavaVM::threads_attached
method. (#179, #180)Executor
— a simple thread attachment manager which helps to safelyInitArgsBuilder
from V1 to V8. (#178)AutoLocal
to make it more flexible. (#190)java.lang.Exception
to unchecked java.lang.RuntimeException
.JNIEnv#throw
is invoked with exception message:env.throw("Exception message")
; however, for efficiency reasons, it is recommendedthrow_new
:env.throw_new(exception_type, "Exception message")
. (#194)JavaVM::attach_current_thread_as_daemon
now automatically detachJList
, JMap
and JMapIter
. (#190, #191)Published by dmitry-timofeev over 5 years ago
From<jboolean>
implementation for JValue
(#173)Debug
trait for InitArgsBuilder. (#175)InitArgsBuilder#options
returning the collected JVM options. (#177)Published by dmitry-timofeev over 5 years ago
Published by dmitry-timofeev over 5 years ago
This release does not bring code changes.
Published by dmitry-timofeev over 5 years ago
JString
, JMap
and JavaStr
and their respective iterators now require an extra lifetime so that they can now work with &'b JNIEnv<'a>
, where 'a: 'b
.Published by dmitry-timofeev over 5 years ago
This release brings various improvements and fixes, outlined below. The most notable changes are:
null
is no longer represented as an Err
with error kind NullPtr
if it is a value of someunsafe
methods, providing a low-level API similar to JNI, has been marked safe and renamed_unchecked
suffix. Such methods can be used to implement caching of class referencespush_local_frame
, delete_global_ref
and release_string_utf_chars
no longer check for exceptions as they are safe
to call if there is a pending exception (#124):
push_local_frame
will now work in case of pending exceptions — asdelete_global_ref
and release_string_utf_chars
won't print incorrectRename some macros to better express their intent (see #123):
jni_call
to jni_non_null_call
as it checks the return valuejni_non_null_call
(which may return nulls) to jni_non_void_call
.A lot of public methods of JNIEnv
have been marked as safe, all unsafe code
has been isolated inside internal macros. Methods with _unsafe
suffixes have
been renamed and now have _unchecked
suffixes (#140)
from_str
method of the JavaType
has been replaced by the FromStr
implementation
Implemented Sync for GlobalRef (#102).
Improvements in macro usage for JNI methods calls (#136):
call_static_method_unchecked
and get_static_field_unchecked
methods arecall_static_method_unchecked
Further improvements in macro usage for JNI method calls (#150):
Implemented Clone for JNIEnv (#147).
The get_superclass(), get_field_unchecked() and get_object_array_element() are allowed to return NULL object according
to the specification (#163).
Published by dmitry-timofeev about 6 years ago
JavaVM#get_java_vm_pointer
to retrieve a JavaVM pointer (#98)cdylib
(#100)