Releases: jni-rs/jni-rs
Releases · jni-rs/jni-rs
Rust JNI 0.21.1
Rust JNI 0.21.0
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
, and `JNIEnv::with_local_fr...
Rust JNI 0.20.0
Added
Default
trait implemented forJObject
,JString
,JClass
, andJByteBuffer
(#199)Debug
trait implemented forJavaVM
,GlobalRef
,GlobalRefGuard
,JStaticMethodID
andReleaseMode
(#345)ReturnType
for specifying object return types without a String allocation. (#329)
Changed
- The
release_string_utf_chars
function has been marked as unsafe. (#334) - Mark
JNIEnv::new_direct_byte_buffer
asunsafe
(#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)- The lifetime of
AutoArray
is no longer tied to the lifetime of a particularJNIEnv
reference. (#302) - Relaxed lifetime restrictions on
JNIEnv::new_local_ref
. Now it can be used to create a local
reference from a global reference. (#301 / #319) JMethodID
andJStaticMethodID
implementSend
+Sync
and no longer has a lifetime parameter, making method
IDs cacheable (with a documented 'Safety' note about ensuring they remain valid). (#346)JFieldID
andJStaticFieldID
implementSend
+Sync
and no longer has a lifetime parameter, making field
IDs cacheable (with a documented 'Safety' note about ensuring they remain valid). (#346)- The
call_*_method_unchecked
functions now takejni:sys::jvalue
arguments to avoid allocating
aVec
on each call to map + collectJValue
s assys:jvalue
s (#329) - The
From
trait implementations convertingjni_sys
types likejobject
toJObject
have been replaced
withunsafe
::from_raw
functions and corresponding::into_raw
methods. Existing::into_inner
APIs were
renamed::into_raw
for symmetry. (#197) - The APIs
JNIEnv::set_rust_field
,JNIEnv::get_rust_field
andJNIEnv::take_rust_field
have been marked asunsafe
(#219)
New Contributors
- @TobiasDeBruijn made their first contribution in #332
- @chrismooredev made their first contribution in #324
- @xianminx made their first contribution in #350
- @rib made their first contribution in #359
- @kgrech made their first contribution in #355
- @sdeleuze made their first contribution in #337
- @Rodrigodd made their first contribution in #339
- @tomcumming made their first contribution in #308
- @kjvalencik made their first contribution in #320
- @TimeToogo made their first contribution in #351
- @jrose-signal made their first contribution in #318
- @argv-minus-one made their first contribution in #319
Full Changelog: v0.19.0...v0.20.0
Rust JNI 0.19.0
Added
AutoArray
and genericget_array_elements()
, along withget_<type>_array_elements
helpers. (#287)size()
method toAutoArray
andAutoPrimitiveArray
. (#278 / #287)discard()
method toAutoArray
andAutoPrimitiveArray
. (#275 / #287)
Changed
- Removed AutoPrimitiveArray::commit(). (#290)
AutoByte/PrimitiveArray.commit()
now returnsResult
. (#275)- Removed methods get/release/commit_byte/primitive_array_{elements|critical}. (#281)
- Renamed methods get_auto_byte/long/primitive_array_{elements|critical} to
get_byte/long/primitive_array_{elements|critical}. (#281)
Rust JNI 0.18.0
Added
JNIEnv#define_unnamed_class
function that allows loading a class without
specifying its name. The name is inferred from the class data. (#246)SetStatic<type>Field
. (#248)TryFrom<JValue>
for types inside JValue variants (#264).- Implemented Copy for JNIEnv (#255).
repr(transparent)
attribute to JavaVM struct (#259)
Changed
⚠️ Switch fromerror-chain
tothiserror
, making all errorsSend
. Also, support all JNI errors
in thejni_error_code_to_result
function and add more information to theInvalidArgList
error. (#242)
Rust JNI 0.17.0
Added
- Get/ReleaseByteArrayElements, and Get/ReleasePrimitiveArrayCritical. (#237)
Rust JNI 0.16.0
Rust JNI 0.15.0
Added
- Ability to pass object wrappers that are convertible to
JObject
as arguments to the majority of JNIEnv methods without explicit conversion (#213) JNIEnv#is_same_object
implementation (#213)JNIEnv#register_native_methods
(#214)- Conversion from
Into<JObject>
toJValue::Object
Fixed
- Passing
null
as class loader todefine_class
method now allowed according to the JNI specification. (#225)
Rust JNI 0.14.0
Changed
- Relaxed some lifetime restrictions in JNIEnv to support the case when method, field ids; and global references to classes have a different (larger) lifetime than JNIEnv. (#209)
Rust JNI 0.13.1
Changed
- Various documentation improvements.