xmog_jvm Class Reference

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

#include <xmog_jvm.h>

Collaboration diagram for xmog_jvm:

[legend]List of all members.

Public Member Functions
xmog_localenv *	attach (JNIEnv *env)
	Create or returns the required framework housekeeping information for an already attached thread (it has a JNIEnv*).
xmog_localenv *	attach (jobject group=NULL, const char *name=NULL, bool bAsDaemon=false)
	Attempts to attach a thread to a running JVM.
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, ...).
void	detach (xmog_localenv *env=NULL)
	Detach a thread and destroy the JunC++ion housekeeping information.
xmog_error_handler *	get_error_handler ()
	Returns the error handler that will be used for newly attached threads.
xmog_base *	getDefaultEncoding ()
	Returns the default string encoding that is used when native strings are converted to Java strings.
bool	getInDestroy ()
	Returns true if this instance has started destroy processing.
bool	getInProcess ()
	Returns true if this instance represents an in-process JVM.
jint	getJavaVersion ()
	Returns the in-process JVM Java version in JNI version format.
JavaVM *	getJavaVM ()
	Returns the JavaVM represented by this JVM instance.
jint	getJNIVersion ()
	Returns the JNI version. In remote JVM scenarios, the value returned here is always > 1.2.
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.
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.
void	operator delete (void *)
	Overloaded operator delete that is safe to use for non heap-allocated instances.
void *	operator new (size_t)
	Overloaded operator new that allows us to detect whether the instance is heap-allocated or not.
void	set_error_handler (xmog_error_handler *_eh)
	Sets the error handler that will be used for newly attached threads.
void	setDefaultEncoding (xmog_base *_enc)
	Sets the default string encoding that is used when native strings are converted to Java strings.
void	setDefaultEncoding (const char *_enc)
	Sets the default string encoding that is used when native strings are converted to Java strings.
	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.
	~xmog_jvm ()
	The destructor.
Static Public Member Functions
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.
static void	static_detach (xmog_localenv *env=NULL)
	Detach a thread and destroy the framework housekeeping information.
Protected Attributes
xmog_base *	default_enc_
	The default string encoding that is used for newly attached threads to translate between native and Java strings.
xmog_error_handler *	eh_
	The error handler that is used for newly attached threads.
bool	inDestroy_
	true if we have already invoked the detroy() method, false otherwise.
bool	inProcess_
	true if we have an in-process JVM, false otherwise.
jint	javaVersion_
	The Java version of the JVM.
jint	jniVersion_
	The JNI version of the JVM.
JavaVM *	jvm_
	A pointer to the JNI-type JavaVM instance that is represented by this object.

---

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 (  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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

---