Java VM Utilities

Java virtual machine support, helping accessing the JVM and converting data types. More...

Classes
class	jau::jni::JavaAnon
	Pure virtual JavaAnon, hiding Java JNI details from API, to be implemented by JNI module. More...
class	jau::jni::JavaGlobalObj
	Implementation for JavaAnon, by simply wrapping a JNIGlobalRef instance. More...
class	jau::jni::JavaUplink
	Sharing the anonymous Java object (JavaAnon), i.e. More...
class	jau::jni::JNICriticalArray< T, U >
class	jau::jni::JNIEnvContainer
class	jau::jni::JNIGlobalRef
class	jau::jni::shared_ptr_ref< T >
	A std::shared_ptr<T> storage instance to be copied from and released into a java object's long nativeInstance field. More...

Macros
#define	rethrow_and_raise_java_exception_jau(E)
	Re-throw current exception and raise respective java exception using any matching function above.

Typedefs
typedef std::shared_ptr< JavaAnon >	jau::jni::JavaAnonRef
typedef std::shared_ptr< JavaGlobalObj >	jau::jni::JavaGlobalObjRef
typedef std::shared_ptr< JavaUplink >	jau::jni::JavaUplinkRef

Functions
template<typename T>
std::shared_ptr< T > *	jau::jni::castInstance (jlong instance, const bool throw_on_nullptr=true)
	Returns the cast shared_ptr<T> pointer from the java object's long nativeInstance field.
template<typename T>
void	jau::jni::clearInstance (JNIEnv *env, jobject obj)
	Deletes the std::shared_ptr<T> storage of the java object if exists and write nullptr into its long nativeInstance field.
template<class byte_container_type, std::enable_if_t< std::is_integral_v< typename byte_container_type::value_type > &&std::is_convertible_v< typename byte_container_type::value_type, jbyte >, bool > = true>
jbyteArray	jau::jni::convert_bytes_to_jbytearray (JNIEnv *env, const byte_container_type &data)
template<typename T>
jobject	jau::jni::convert_instance_to_jobject (JNIEnv *env, const std::shared_ptr< T > &elem, const char *ctor_prototype, jau::function< jobject(JNIEnv *, jclass, jmethodID, const std::shared_ptr< T > &)> ctor)
template<typename T>
jobject	jau::jni::convert_instance_to_jobject (JNIEnv *env, jclass clazz, const char *ctor_prototype, jau::function< jobject(JNIEnv *, jclass, jmethodID, const std::shared_ptr< T > &)> ctor, const std::shared_ptr< T > &elem)
std::vector< std::string >	jau::jni::convert_jlist_string_to_vector (JNIEnv *env, jobject jlist)
jobject	jau::jni::convert_vector_bytes_to_jarraylist (JNIEnv *env, const std::vector< std::vector< uint8_t > > &array)
template<typename T>
jobject	jau::jni::convert_vector_sharedptr_to_jarraylist (JNIEnv *env, T &array)
template<typename T, typename U>
jobject	jau::jni::convert_vector_sharedptr_to_jarraylist (JNIEnv *env, T &array, const char *ctor_prototype, jau::function< jobject(JNIEnv *, jclass, jmethodID, const std::shared_ptr< U > &)> ctor)
template<typename T, typename U>
jobject	jau::jni::convert_vector_sharedptr_to_jarraylist (JNIEnv *env, T &array, jau::function< jobject(JNIEnv *, const std::shared_ptr< U > &)> ctor)
jobject	jau::jni::convert_vector_string_to_jarraylist (JNIEnv *env, const std::vector< std::string > &array)
jobject	jau::jni::convert_vector_stringview_to_jarraylist (JNIEnv *env, const std::vector< std::string_view > &array)
template<typename T, typename U>
jobject	jau::jni::convert_vector_to_jarraylist (JNIEnv *env, T &array, jau::function< jobject(JNIEnv *, const U &)> ctor)
bool	jau::jni::from_jboolean_to_bool (const jboolean val)
jau::io::secure_string	jau::jni::from_jbytebuffer_to_sstring (JNIEnv *env, jobject jbytebuffer)
std::string	jau::jni::from_jstring_to_string (JNIEnv *env, jstring str)
jstring	jau::jni::from_string_to_jstring (JNIEnv *env, const std::string &str)
jobject	jau::jni::get_new_arraylist (JNIEnv *env, jsize size, jmethodID *add)
jfieldID	jau::jni::getField (JNIEnv *env, jobject obj, const char *field_name, const char *field_signature)
template<typename T>
std::shared_ptr< T > *	jau::jni::getInstance (JNIEnv *env, jobject obj, const bool throw_on_nullptr=true)
	Returns the cast shared_ptr<T> pointer from the java object's long nativeInstance field.
jfieldID	jau::jni::getInstanceField (JNIEnv *env, jobject obj)
jint	jau::jni::getIntFieldValue (JNIEnv *env, jobject obj, const char *field_name)
jlong	jau::jni::getLongFieldValue (JNIEnv *env, jobject obj, const char *field_name)
jobject	jau::jni::getObjectFieldValue (JNIEnv *env, jobject obj, const char *field_name, const char *field_signature)
template<typename T>
T *	jau::jni::getObjectRef (JNIEnv *env, jobject obj, const char *field_name)
std::string	jau::jni::getStringFieldValue (JNIEnv *env, jobject obj, const char *field_name)
bool	jau::jni::java_exception_check (JNIEnv *env, const char *file, int line)
	Return true if a java exception occurred, otherwise false.
void	jau::jni::java_exception_check_and_throw (JNIEnv *env, const char *file, int line)
	Throws a C++ exception if a java exception occurred, otherwise do nothing.
void	jau::jni::print_native_caught_exception_fwd2java (const char *cmsg, const char *file, int line)
void	jau::jni::print_native_caught_exception_fwd2java (const jau::ExceptionBase &e, const char *file, int line)
void	jau::jni::print_native_caught_exception_fwd2java (const std::exception &e, const char *file, int line)
void	jau::jni::print_native_caught_exception_fwd2java (const std::string &msg, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::ExceptionBase &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::IllegalArgumentError &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::IllegalStateError &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::IndexOutOfBoundsError &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::InternalError &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::NullPointerException &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::OutOfMemoryError &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::RuntimeExceptionBase &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::UnsupportedOperationException &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const std::bad_alloc &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const std::exception &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const std::invalid_argument &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const std::runtime_error &e, const char *file, int line)
void	jau::jni::rethrow_and_raise_java_exception_jauimpl (JNIEnv *env, const char *file, int line)
	Re-throw current exception and raise respective java exception using any matching function above.
jclass	jau::jni::search_class (JNIEnv *env, const char *clazz_name)
jclass	jau::jni::search_class (JNIEnv *env, JavaUplink &object)
jclass	jau::jni::search_class (JNIEnv *env, jobject obj)
jfieldID	jau::jni::search_field (JNIEnv *env, jclass clazz, const char *field_name, const char *type, bool is_static)
jmethodID	jau::jni::search_method (JNIEnv *env, jclass clazz, const char *method_name, const char *prototype, bool is_static)
template<typename T>
void	jau::jni::setInstance (JNIEnv *env, jobject obj, const std::shared_ptr< T > &t)
	Deletes the std::shared_ptr<T> storage of the java object if exists first and writes the given std::shared_ptr<T> storage pointer into its long nativeInstance field.
template<typename T>
void	jau::jni::setObjectRef (JNIEnv *env, jobject obj, T *t, const char *field_name)

Variables
thread_local JNIEnvContainer	jau::jni::jni_env
JavaVM *	jau::jni::vm

Detailed Description

Java virtual machine support, helping accessing the JVM and converting data types.

Macro Definition Documentation

rethrow_and_raise_java_exception_jau

#define rethrow_and_raise_java_exception_jau

(

E

)

Value:

jau::jni::rethrow_and_raise_java_exception_jauimpl((E), __FILE__, __LINE__)

Re-throw current exception and raise respective java exception using any matching function above.

Definition at line 107 of file helper_jni.hpp.

Typedef Documentation

JavaAnonRef

typedef std::shared_ptr<JavaAnon> jau::jni::JavaAnonRef

Definition at line 55 of file java_uplink.hpp.

JavaUplinkRef

typedef std::shared_ptr<JavaUplink> jau::jni::JavaUplinkRef

Definition at line 104 of file java_uplink.hpp.

JavaGlobalObjRef

typedef std::shared_ptr<JavaGlobalObj> jau::jni::JavaGlobalObjRef

Definition at line 249 of file helper_jni.hpp.

Function Documentation

java_exception_check()

bool jau::jni::java_exception_check	(	JNIEnv *	env,
		const char *	file,
		int	line )

Return true if a java exception occurred, otherwise false.

In case of an exception, the information might be logged to stderr.

In case of an exception, user shall release resourced in their JNI code and leave immediately.

java_exception_check_and_throw()

void jau::jni::java_exception_check_and_throw	(	JNIEnv *	env,
		const char *	file,
		int	line )

Throws a C++ exception if a java exception occurred, otherwise do nothing.

In case of an exception, the information might be logged to stderr.

In case of an exception and hence thrown C++ exception, might want to catch all and handle it via rethrow_and_raise_java_exception(JNIEnv*).

Here is the caller graph for this function:

print_native_caught_exception_fwd2java() [1/4]

void jau::jni::print_native_caught_exception_fwd2java	(	const jau::ExceptionBase &	e,
		const char *	file,
		int	line )

print_native_caught_exception_fwd2java() [2/4]

void jau::jni::print_native_caught_exception_fwd2java	(	const std::exception &	e,
		const char *	file,
		int	line )

print_native_caught_exception_fwd2java() [3/4]

void jau::jni::print_native_caught_exception_fwd2java	(	const std::string &	msg,
		const char *	file,
		int	line )

print_native_caught_exception_fwd2java() [4/4]

void jau::jni::print_native_caught_exception_fwd2java	(	const char *	cmsg,
		const char *	file,
		int	line )

raise_java_exception() [1/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::ExceptionBase &	e,
		const char *	file,
		int	line )

raise_java_exception() [2/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::RuntimeExceptionBase &	e,
		const char *	file,
		int	line )

raise_java_exception() [3/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::InternalError &	e,
		const char *	file,
		int	line )

raise_java_exception() [4/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::NullPointerException &	e,
		const char *	file,
		int	line )

raise_java_exception() [5/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::IllegalArgumentError &	e,
		const char *	file,
		int	line )

raise_java_exception() [6/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::IllegalStateError &	e,
		const char *	file,
		int	line )

raise_java_exception() [7/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::UnsupportedOperationException &	e,
		const char *	file,
		int	line )

raise_java_exception() [8/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::IndexOutOfBoundsError &	e,
		const char *	file,
		int	line )

raise_java_exception() [9/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::OutOfMemoryError &	e,
		const char *	file,
		int	line )

raise_java_exception() [10/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const std::exception &	e,
		const char *	file,
		int	line )

raise_java_exception() [11/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const std::runtime_error &	e,
		const char *	file,
		int	line )

raise_java_exception() [12/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const std::invalid_argument &	e,
		const char *	file,
		int	line )

raise_java_exception() [13/13]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const std::bad_alloc &	e,
		const char *	file,
		int	line )

rethrow_and_raise_java_exception_jauimpl()

void jau::jni::rethrow_and_raise_java_exception_jauimpl	(	JNIEnv *	env,
		const char *	file,
		int	line )

Re-throw current exception and raise respective java exception using any matching function above.

getField()

jfieldID jau::jni::getField	(	JNIEnv *	env,
		jobject	obj,
		const char *	field_name,
		const char *	field_signature )

Here is the caller graph for this function:

getInstanceField()

jfieldID jau::jni::getInstanceField ( JNIEnv * env, jobject obj )

inline

Definition at line 115 of file helper_jni.hpp.

Here is the caller graph for this function:

getObjectFieldValue()

jobject jau::jni::getObjectFieldValue	(	JNIEnv *	env,
		jobject	obj,
		const char *	field_name,
		const char *	field_signature )

getStringFieldValue()

std::string jau::jni::getStringFieldValue	(	JNIEnv *	env,
		jobject	obj,
		const char *	field_name )

getLongFieldValue()

jlong jau::jni::getLongFieldValue	(	JNIEnv *	env,
		jobject	obj,
		const char *	field_name )

getIntFieldValue()

jint jau::jni::getIntFieldValue	(	JNIEnv *	env,
		jobject	obj,
		const char *	field_name )

search_class() [1/3]

jclass jau::jni::search_class	(	JNIEnv *	env,
		const char *	clazz_name )

Here is the caller graph for this function:

search_class() [2/3]

jclass jau::jni::search_class	(	JNIEnv *	env,
		jobject	obj )

search_class() [3/3]

jclass jau::jni::search_class	(	JNIEnv *	env,
		JavaUplink &	object )

search_method()

jmethodID jau::jni::search_method	(	JNIEnv *	env,
		jclass	clazz,
		const char *	method_name,
		const char *	prototype,
		bool	is_static )

Here is the caller graph for this function:

search_field()

jfieldID jau::jni::search_field	(	JNIEnv *	env,
		jclass	clazz,
		const char *	field_name,
		const char *	type,
		bool	is_static )

from_jboolean_to_bool()

bool jau::jni::from_jboolean_to_bool

(

const jboolean

val

)

from_jstring_to_string()

std::string jau::jni::from_jstring_to_string	(	JNIEnv *	env,
		jstring	str )

from_string_to_jstring()

jstring jau::jni::from_string_to_jstring	(	JNIEnv *	env,
		const std::string &	str )

from_jbytebuffer_to_sstring()

jau::io::secure_string jau::jni::from_jbytebuffer_to_sstring	(	JNIEnv *	env,
		jobject	jbytebuffer )

get_new_arraylist()

jobject jau::jni::get_new_arraylist	(	JNIEnv *	env,
		jsize	size,
		jmethodID *	add )

Here is the caller graph for this function:

convert_vector_bytes_to_jarraylist()

jobject jau::jni::convert_vector_bytes_to_jarraylist	(	JNIEnv *	env,
		const std::vector< std::vector< uint8_t > > &	array )

convert_vector_string_to_jarraylist()

jobject jau::jni::convert_vector_string_to_jarraylist	(	JNIEnv *	env,
		const std::vector< std::string > &	array )

convert_vector_stringview_to_jarraylist()

jobject jau::jni::convert_vector_stringview_to_jarraylist	(	JNIEnv *	env,
		const std::vector< std::string_view > &	array )

convert_jlist_string_to_vector()

std::vector< std::string > jau::jni::convert_jlist_string_to_vector	(	JNIEnv *	env,
		jobject	jlist )

convert_bytes_to_jbytearray()

template<class byte_container_type, std::enable_if_t< std::is_integral_v< typename byte_container_type::value_type > &&std::is_convertible_v< typename byte_container_type::value_type, jbyte >, bool > = true>

jbyteArray jau::jni::convert_bytes_to_jbytearray	(	JNIEnv *	env,
		const byte_container_type &	data )

Definition at line 150 of file helper_jni.hpp.

getObjectRef()

template<typename T>

T * jau::jni::getObjectRef	(	JNIEnv *	env,
		jobject	obj,
		const char *	field_name )

Definition at line 259 of file helper_jni.hpp.

setObjectRef()

template<typename T>

void jau::jni::setObjectRef	(	JNIEnv *	env,
		jobject	obj,
		T *	t,
		const char *	field_name )

Definition at line 267 of file helper_jni.hpp.

castInstance()

template<typename T>

std::shared_ptr< T > * jau::jni::castInstance	(	jlong	instance,
		const bool	throw_on_nullptr = true )

Returns the cast shared_ptr<T> pointer from the java object's long nativeInstance field.

If throw_on_nullptr is true, throws an exception if the shared_ptr<T> pointer is nullptr.

Template Parameters

T

Parameters

instance
throw_on_nullptr

Returns

Definition at line 285 of file helper_jni.hpp.

getInstance()

template<typename T>

std::shared_ptr< T > * jau::jni::getInstance	(	JNIEnv *	env,
		jobject	obj,
		const bool	throw_on_nullptr = true )

Returns the cast shared_ptr<T> pointer from the java object's long nativeInstance field.

If throw_on_nullptr is true, throws an exception if either the shared_ptr<T> pointer or its managed object reference is nullptr.

Template Parameters

T

Parameters

env
obj
throw_on_nullptr	if true, throws exception if instance reference is nullptr (default). Otherwise not.

Definition at line 308 of file helper_jni.hpp.

setInstance()

template<typename T>

void jau::jni::setInstance	(	JNIEnv *	env,
		jobject	obj,
		const std::shared_ptr< T > &	t )

Deletes the std::shared_ptr<T> storage of the java object if exists first and writes the given std::shared_ptr<T> storage pointer into its long nativeInstance field.

Template Parameters

T

Parameters

env
obj
t

Definition at line 333 of file helper_jni.hpp.

clearInstance()

template<typename T>

void jau::jni::clearInstance	(	JNIEnv *	env,
		jobject	obj )

Deletes the std::shared_ptr<T> storage of the java object if exists and write nullptr into its long nativeInstance field.

Template Parameters

T

Parameters

env
obj

Definition at line 364 of file helper_jni.hpp.

convert_instance_to_jobject() [1/2]

template<typename T>

jobject jau::jni::convert_instance_to_jobject	(	JNIEnv *	env,
		const std::shared_ptr< T > &	elem,
		const char *	ctor_prototype,
		jau::function< jobject(JNIEnv *, jclass, jmethodID, const std::shared_ptr< T > &)>	ctor )

Definition at line 667 of file helper_jni.hpp.

convert_instance_to_jobject() [2/2]

template<typename T>

jobject jau::jni::convert_instance_to_jobject	(	JNIEnv *	env,
		jclass	clazz,
		const char *	ctor_prototype,
		jau::function< jobject(JNIEnv *, jclass, jmethodID, const std::shared_ptr< T > &)>	ctor,
		const std::shared_ptr< T > &	elem )

Definition at line 684 of file helper_jni.hpp.

convert_vector_sharedptr_to_jarraylist() [1/3]

template<typename T>

jobject jau::jni::convert_vector_sharedptr_to_jarraylist	(	JNIEnv *	env,
		T &	array )

Definition at line 701 of file helper_jni.hpp.

Here is the caller graph for this function:

convert_vector_sharedptr_to_jarraylist() [2/3]

template<typename T, typename U>

jobject jau::jni::convert_vector_sharedptr_to_jarraylist	(	JNIEnv *	env,
		T &	array,
		const char *	ctor_prototype,
		jau::function< jobject(JNIEnv *, jclass, jmethodID, const std::shared_ptr< U > &)>	ctor )

Definition at line 723 of file helper_jni.hpp.

convert_vector_sharedptr_to_jarraylist() [3/3]

template<typename T, typename U>

jobject jau::jni::convert_vector_sharedptr_to_jarraylist	(	JNIEnv *	env,
		T &	array,
		jau::function< jobject(JNIEnv *, const std::shared_ptr< U > &)>	ctor )

Definition at line 758 of file helper_jni.hpp.

convert_vector_to_jarraylist()

template<typename T, typename U>

jobject jau::jni::convert_vector_to_jarraylist	(	JNIEnv *	env,
		T &	array,
		jau::function< jobject(JNIEnv *, const U &)>	ctor )

Definition at line 789 of file helper_jni.hpp.

Here is the caller graph for this function:

Variable Documentation

vm

JavaVM* jau::jni::vm

extern

jni_env

thread_local JNIEnvContainer jau::jni::jni_env

extern