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.
Added
JavaStr::into_raw()
which drops theJavaStr
and releases ownership of the raw string pointer (#374)JavaStr::from_raw()
which takes ownership of a raw string pointer to create aJavaStr
(#374)JNIEnv::get_string_unchecked
is a cheaper,unsafe
alternative toget_string
that doesn't check the given object is ajava.lang.String
instance. (#328)WeakRef
andJNIEnv#new_weak_ref
. (#304)define_class_bytearray
method that takes anAutoElements<jbyte>
rather than a&[u8]
(#244)JObject
now has anas_raw
method that borrows theJObject
instead of taking ownership likeinto_raw
. Needed becauseJObject
no longer has theCopy
trait. (#392)JavaVM::destroy()
(unsafe) as a way to try and unload aJavaVM
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 usingJavaVM::destroy()
(#391)JPrimitiveArray<T: TypeArray>
and type-specific aliases likeJByteArray
,JIntArray
etc now provide safe, reference wrappers for thesys
typesjarray
andjbyteArray
etc with a lifetime likeJObject
(#400)JObjectArray
provides a reference wrapper for ajobjectArray
with a lifetime likeJObject
. (#400)AutoElements
andAutoElementsCritical
(previouslyAutoArray
/AutoPrimitiveArray
) implementDeref<Target=[T]>
andDerefMut
so array elements can be accessed via slices without needing additionalunsafe
code. (#400)AsJArrayRaw
trait which enablesJNIEnv::get_array_length()
to work withJPrimitiveArray
orJObjectArray
types (#400)InitArgsBuilder
now hastry_option
andoption_encoded
methods. (#414)
Changed
JNIEnv::get_string
checks that the given object is ajava.lang.String
instance to avoid undefined behaviour from the JNI implementation potentially aborting the program. (#328)JNIEnv::call_*method_unchecked
was markedunsafe
, as passing improper argument types, or a bad number of arguments, can cause a JVM crash. (#385)- The
JNIEnv::new_object_unchecked
function now takes arguments as&[jni::sys::jvalue]
to avoid allocating, putting it inline with changes toJniEnv::call_*_unchecked
from 0.20.0 (#382) - The
get_superclass
function now returns an Option instead of a null pointer if the class has no superclass (#151) - The
invocation
feature now locates the JVM implementation dynamically at runtime (via thejava-locator
crate by default) instead of linking with the JVM at build time (#293) - Most
JNIEnv
methods now require&mut self
. This improves safety by preventingJObject
s from getting an invalid lifetime. Most native method implementations (that is,#[no_mangle] extern "system" fn
s) must now make theJNIEnv
parametermut
. See the example on the crate documentation. (#392) JByteBuffer
,JClass
,JNIEnv
,JObject
,JString
, andJThrowable
no longer have theClone
orCopy
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 (exceptextern fn
s that are directly called by the JVM) should now borrow it instead, e.g.&JObject
instead ofJObject
. (#392)AutoLocal
is now generic in the type of object reference (JString
, etc). (#392)- The closure passed to
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
andExecutor::with_attached_capacity
have been similarly changed. (#392) - The closure passed to
JNIEnv::with_local_frame
can now return a genericResult<T, E>
so long as the error implementsFrom<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 (seewith_local_frame_returning_local
) (#399)Executor::with_attached
andExecutor::with_attached_capacity
have been changed in the same way asJNIEnv::with_local_frame
(they are thin wrappers) (#399)Desc
,JNIEnv::pop_local_frame
, andTypeArray
are nowunsafe
. (#392)- The
Desc
trait now has an associated typeOutput
. Many implementations now returnAutoLocal
, so if you callDesc::lookup
yourself and then callas_raw
on the returned object, make sure theAutoLocal
isn't dropped too soon (see theDesc::lookup
documentation for examples). (#392) - The
Desc<JClass>
trait is no longer implemented forJObject
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) - Named lifetimes in the documentation have more descriptive names (like
'local
instead of'a
). The new naming convention is explained in theJNIEnv
documentation. (#392) - Object reference types (
JObject
,JClass
,AutoLocal
,GlobalRef
, etc) now implementAsRef<JObject>
andDeref<Target = JObject>
. Typed wrappers likeJClass
also implementInto<JObject>
, butGlobalRef
does not. (#392) - Most
JList
andJMap
methods now require a&mut JNIEnv
parameter.JListIter
andJMapIter
no longer implementIterator
, and instead have anext
method that requires a&mut JNIEnv
parameter (usewhile let
loops instead offor
). (#392) JValue
has been changed in several ways: (#392)- It is now a generic type named
JValueGen
.JValue
is now a type alias forJValueGen<&JObject>
, that is, it borrows an object reference.JValueOwned
is a type alias forJValueGen<JObject>
, that is, it owns an object reference. JValueOwned
does not have theCopy
trait.- The
to_jni
method is now namedas_jni
, and it borrows theJValueGen
instead of taking ownership. JObject
can no longer be converted directly toJValue
, which was commonly done when calling Java methods or constructors. Instead ofobj.into()
, use(&obj).into()
.
- It is now a generic type named
- All
JNIEnv
array APIs now work in terms ofJPrimitiveArray
andJObjectArray
(reference wrappers with a lifetime) instead ofsys
types likejarray
andjbyteArray
(#400) AutoArray
andAutoPrimitiveArray
have been renamedAutoElements
andAutoElementsCritical
to show their connection and differentiate from newJPrimitiveArray
API (#400)get_primitive_array_critical
is nowunsafe
and has been renamed toget_array_elements_critical
(consistent with the rename ofAutoPrimitiveArray
) with more detailed safety documentation (#400)get_array_elements
is now alsounsafe
(for many of the same reasons asget_array_elements_critical
) and has detailed safety documentation (#400)AutoArray/AutoArrayCritical::size()
has been replaced with.len()
which can't fail and returns ausize
(#400)- The
TypeArray
trait is now a private / sealed trait, that is considered to be an implementation detail for theAutoArray
API. JvmError
has several more variants and is nownon_exhaustive
. (#414)InitArgsBuilder::option
raises an error on Windows if the string is too long. The limit is currently 1048576 bytes. (#414)
Fixed
- Trying to use an object reference after it has been deleted now causes a compile error instead of undefined behavior. As a result, it is now safe to use
AutoLocal
,JNIEnv::delete_local_ref
, andJNIEnv::with_local_frame
. (Most of the limitations added in #392, listed above, were needed to make this work.) (#381, #392) - Class lookups via the
Desc
trait now returnAutoLocal
s, which prevents them from leaking. (#109, #392) InitArgsBuilder::option
properly encodes non-ASCII characters on Windows. (#414)
Removed
get_string_utf_chars
andrelease_string_utf_chars
fromJNIEnv
(SeeJavaStr::into_raw()
andJavaStr::from_raw()
instead) (#372)- All
JNIEnv::get_<type>_array_elements()
methods have been removed as redundant since they would all be equivalent toget_array_elements()
with the introduction ofJPrimitiveArray
(#400)
New Contributors
- @progmanos made their first contribution in #378
- @homelessnessbo made their first contribution in #388
- @x4e made their first contribution in #244
- @fee1-dead made their first contribution in #395
- @kb-1000 made their first contribution in #409
Full Changelog: v0.20.0...v0.21.0