The class that represents a Java Virtual Machine in the framework. More...

#include <xmog_jvm.h>

Collaboration diagram for xmog_jvm:

[legend]

Public Member Functions
	xmog_jvm (JavaVM *theJvm, jint jniVersion=JNI_VERSION_1_2, jint javaVersion=0, bool inProcess=true)
	The constructor that is only used by the framework. More...

	~xmog_jvm ()
	The destructor.

void *	operator new (size_t)
	Overloaded operator `new` that allows us to detect whether the instance is heap-allocated or not.

void	operator delete (void *)
	Overloaded operator `delete` that is safe to use for non heap-allocated instances.

xmog_localenv *	attach (jobject group=NULL, const char *name=NULL, bool bAsDaemon=false)
	Attempts to attach a thread to a running JVM. More...

xmog_localenv *	attach (JNIEnv *env)
	Create or returns the required framework housekeeping information for an already attached thread (it has a JNIEnv*). More...

void	detach (xmog_localenv *env=NULL)
	Detach a thread and destroy the JunC++ion housekeeping information. More...

void	destroy ()
	Destroys this instance of the JVM, thereby performing whatever cleanup code is appropriate for the JVM instance (JVM unloading, socket termination, shared memory cleanup, ...). More...

virtual int	initializeFieldID (xmog_java_class clazz, xmog_java_field field, xmog_localenv *env=NULL)
	Initializes the identifying information for at least the specified field. More...

virtual int	initializeMethodID (xmog_java_class clazz, xmog_java_method method, xmog_localenv *env=NULL)
	Initializes the identifying information for at least the specified method. More...

jint	getJNIVersion ()
	Returns the JNI version. In remote JVM scenarios, the value returned here is always > 1.2.

bool	getInProcess ()
	Returns true if this instance represents an in-process JVM.

bool	getInDestroy ()
	Returns true if this instance has started destroy processing.

JavaVM *	getJavaVM ()
	Returns the JavaVM represented by this JVM instance.

jint	getJavaVersion ()
	Returns the in-process JVM Java version in JNI version format.

void	setDefaultEncoding (const char *_enc)
	Sets the default string encoding that is used when native strings are converted to Java strings. More...

void	setDefaultEncoding (xmog_base *_enc)
	Sets the default string encoding that is used when native strings are converted to Java strings. More...

xmog_base *	getDefaultEncoding ()
	Returns the default string encoding that is used when native strings are converted to Java strings. More...

void	set_error_handler (xmog_error_handler *_eh)
	Sets the error handler that will be used for newly attached threads. More...

xmog_error_handler *	get_error_handler ()
	Returns the error handler that will be used for newly attached threads. More...

Static Public Member Functions
static void	static_detach (xmog_localenv *env=NULL)
	Detach a thread and destroy the framework housekeeping information. More...

static xmog_localenv *	getEnv ()
	Returns the local environment pointer if the thread has already been attached to the JVM or NULL if it has not yet been attached.

Protected Attributes
JavaVM *	jvm_
	A pointer to the JNI-type `JavaVM` instance that is represented by this object.

xmog_error_handler *	eh_
	The error handler that is used for newly attached threads.

xmog_base *	default_enc_
	The default string encoding that is used for newly attached threads to translate between native and Java strings.

jint	jniVersion_
	The JNI version of the JVM.

jint	javaVersion_
	The Java version of the JVM.

bool	inProcess_
	`true` if we have an in-process JVM, `false` otherwise.

bool	inDestroy_
	`true` if we have already invoked the detroy() method, `false` otherwise.

bool	native_
	`true` if we are running in native mode, `false` otherwise.

Detailed Description

The class that represents a Java Virtual Machine in the framework.

The developer never directly instantiates objects of this type but rather uses the xmog_jvm_loader class as a factory. Please see the examples in xmog_jvm_loader documentation for more insight into the configuration of the framework.

Unless you need direct access to the framework for some reason, you or want to shut down the JVM manually, you will in all likelihood never have to deal with this type directly. The few reasons to use xmog_jvm directly are:

manually attaching a natively created thread to the JVM, for example to provide a thread name or to create a deamon thread rather than a normal thread.
manually detaching a thread from the JVM.
destroying the JVM (unloading it). Don't expect this to work with all JVMs and particularly don't expect to be able to start a new JVM afterwards.

Constructor & Destructor Documentation

◆ xmog_jvm()

xmog_jvm::xmog_jvm	(	JavaVM *	theJvm,
		jint	jniVersion = `JNI_VERSION_1_2`,
		jint	javaVersion = `0`,
		bool	inProcess = `true`
	)

The constructor that is only used by the framework.

Parameters

theJvm	a pointer to a `JavaVM` instance representing a Java Virtual Machine.
jniVersion	the JNI version number. Defaults to `JNI_VERSION_1_2` (0x00010002).
javaVersion	the Java version number in JNI version number format. Defaults to `0`.
inProcess	`true` if we are using JNI, `false` otherwise.

Member Function Documentation

◆ attach() [1/2]

xmog_localenv* xmog_jvm::attach ( JNIEnv * env )

Create or returns the required framework housekeeping information for an already attached thread (it has a JNIEnv*).

This is a useful method in the context of native method implementations. This method is used by the framework to associate the framework housekeeping information with an already attached thread.

Parameters

env	pointer to an already existing JNIEnv.

Returns: a local environment that wraps around the passed JNIEnv and is fully initialized.

◆ attach() [2/2]

xmog_localenv* xmog_jvm::attach	(	jobject	group = `NULL`,
		const char *	name = `NULL`,
		bool	bAsDaemon = `false`
	)

Attempts to attach a thread to a running JVM.

This method also creates or returns the required framework housekeeping information. Simply using the plain JNI function AttachCurrentThread() will perform the JNI action but it will not initialize the associated framework data (for error handling etc.). The users will almost never have to call this method directly. Usually, the framework and the generated code will do the right thing for the user. The only foreseen reason to call this method directly is to attach a user-created thread to a specific thread group or with a specific name or as a daemon thread.

Parameters

group	the (optional) `jobject` handle of a thread group. The default value is `NULL`.
name	the (optional) thread name. The default value is `NULL`.
bAsDaemon	the (optional) daemon flag. The default value is `false`.

Returns: a local environment pointer representing this thread, attached to the JVM.

◆ destroy()

void xmog_jvm::destroy ( )

Destroys this instance of the JVM, thereby performing whatever cleanup code is appropriate for the JVM instance (JVM unloading, socket termination, shared memory cleanup, ...).

Don't expect this call to work with all JVMs and from all threads. Many JVMs have limitations in this area and may only be shut down from the main application thread and only when all object references have been cleaned up.

◆ detach()

void xmog_jvm::detach ( xmog_localenv * env = NULL )

Detach a thread and destroy the JunC++ion housekeeping information.

This method takes an optional argument that should never explicitly be used by a developer. It is solely present as an internal performance improvement.

Parameters

env	the per-thread housekeeping information. The default value is NULL and users should not usually pass a value here.

◆ get_error_handler()

xmog_error_handler* xmog_jvm::get_error_handler ( )

Returns the error handler that will be used for newly attached threads.

Error handlers are thread specific because a programmer must be able to adjust the errorhandling policy in one thread without affecting the entire application. This function allows the querying of the error handler that will be used for newly attached threads.

◆ getDefaultEncoding()

xmog_base* xmog_jvm::getDefaultEncoding ( )

Returns the default string encoding that is used when native strings are converted to Java strings.

The default value will be based on the platform and the version of Java. A value of NULL is interpreted as meaning that we use the platform's default encoding.

This function allows the querying of the encoding that will be the default encoding for newly attached threads. Once a new thread is created, it maintains its own copy of the encoding and its default encoding will not be affected anymore by calling this method. You can query the default encoding for an already attached thread by calling xmog_localenv::get_default_encoding().

Returns: the current value of this setting on this thread.

◆ initializeFieldID()

virtual int xmog_jvm::initializeFieldID	(	xmog_java_class *	clazz,
		xmog_java_field *	field,
		xmog_localenv *	env = `NULL`
	)

virtual

Initializes the identifying information for at least the specified field.

This method is usually overridden in remoting JVMs to improve the efficiency of lookup operations by bundling all proxy members together in one request.

Parameters

clazz	the proxy type for which we want identifying information.
field	the proxy field descriptor for which we want identifying information.
env	the optional environment pointer.

Returns: 0 if everything went alright, an errorcode otherwise.

◆ initializeMethodID()

virtual int xmog_jvm::initializeMethodID	(	xmog_java_class *	clazz,
		xmog_java_method *	method,
		xmog_localenv *	env = `NULL`
	)

virtual

Initializes the identifying information for at least the specified method.

This method is usually overridden in remoting JVMs to improve the efficiency of lookup operations by bundling all proxy members together in one request.

Parameters

clazz	the proxy type for which we want identifying information.
method	the proxy method descriptor for which we want identifying information.
env	the optional environment pointer.

Returns: 0 if everything went alright, an errorcode otherwise.

◆ set_error_handler()

void xmog_jvm::set_error_handler ( xmog_error_handler * _eh )

Sets the error handler that will be used for newly attached threads.

Error handlers are thread specific because a programmer must be able to adjust the errorhandling policy in one thread without affecting the entire application. This function allows the specification of the error handler that will be used for newly attached threads but it does not affect already attached threads.

Parameters

_eh	the error handler instance to be used.

◆ setDefaultEncoding() [1/2]

void xmog_jvm::setDefaultEncoding ( const char * _enc )

Sets the default string encoding that is used when native strings are converted to Java strings.

This function allows the specification of the encoding that will be the default encoding for newly attached threads. Once a new thread is created, it maintains its own copy of the encoding and its default encoding will not be affected anymore by calling this method. You can change the default encoding for an already attached thread by calling xmog_localenv::set_default_encoding(xmog_base*).

The default value will be based on the platform and the version of Java. A value of NULL is interpreted as meaning that we use the JREs default encoding. For highest performance when dealing with UTF-8 strings, use the xmog_java_string::UTF_8 encoding.

◆ setDefaultEncoding() [2/2]

void xmog_jvm::setDefaultEncoding ( xmog_base * _enc )

Sets the default string encoding that is used when native strings are converted to Java strings.

This function allows the specification of the encoding that will be the default encoding for newly attached threads. Once a new thread is created, it maintains its own copy of the encoding and its default encoding will not be affected anymore by calling this method. You can change the default encoding for an already attached thread by calling xmog_localenv::set_default_encoding(xmog_base*).

The default value will be based on the platform and the version of Java. A value of NULL is interpreted as meaning that we use the JREs default encoding. For highest performance when dealing with UTF-8 strings, use the xmog_java_string::UTF_8 encoding.

◆ static_detach()

static void xmog_jvm::static_detach ( xmog_localenv * env = NULL )

static

Detach a thread and destroy the framework housekeeping information.

This method takes an optional argument that should never explicitly be used by a developer. It is solely present as an internal performance improvement.

Parameters

env	the per-thread housekeeping information. The default value is NULL and users should not usually pass a value here.

The documentation for this class was generated from the following file:

xmog_jvm.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ xmog_jvm()

Member Function Documentation

◆ attach() [1/2]

◆ attach() [2/2]

◆ destroy()

◆ detach()

◆ get_error_handler()

◆ getDefaultEncoding()

◆ initializeFieldID()

◆ initializeMethodID()

◆ set_error_handler()

◆ setDefaultEncoding() [1/2]

◆ setDefaultEncoding() [2/2]

◆ static_detach()