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)   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. More...

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. More...
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. More...
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. More...
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. More...
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. More...
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::OutOfMemoryError &e, const char *file, int line)
void	jau::jni::print_native_caught_exception_fwd2java (const jau::RuntimeException &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::IllegalArgumentException &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::IllegalStateException &e, const char *file, int line)
void	jau::jni::raise_java_exception (JNIEnv *env, const jau::IndexOutOfBoundsException &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::RuntimeException &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. More...
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. More...
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

)

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 250 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/5]

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

print_native_caught_exception_fwd2java() [2/5]

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

print_native_caught_exception_fwd2java() [3/5]

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

print_native_caught_exception_fwd2java() [4/5]

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

print_native_caught_exception_fwd2java() [5/5]

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

raise_java_exception() [1/12]

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

raise_java_exception() [2/12]

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

raise_java_exception() [3/12]

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

raise_java_exception() [4/12]

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

raise_java_exception() [5/12]

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

raise_java_exception() [6/12]

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

raise_java_exception() [7/12]

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

raise_java_exception() [8/12]

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

raise_java_exception() [9/12]

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

raise_java_exception() [10/12]

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

raise_java_exception() [11/12]

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

raise_java_exception() [12/12]

void jau::jni::raise_java_exception	(	JNIEnv *	env,
		const jau::OutOfMemoryError &	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
	)

Here is the caller graph for this function:

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 260 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 268 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 286 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 309 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 334 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 365 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 668 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 685 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 702 of file helper_jni.hpp.

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 724 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 759 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 790 of file helper_jni.hpp.

Variable Documentation

vm

JavaVM* jau::jni::vm

extern

jni_env

thread_local JNIEnvContainer jau::jni::jni_env

extern