Lesson 1: Introduction

Runtime configuration can be grouped into three distinct categories:

1. Settings that govern the JVM's launch.
2. Settings that apply post-launch, to new threads created by or attaching to the JVM.
3. Settings that apply to the current thread.

For the most part you will be able to ignore the second and third categories and focus exclusively on the first category. It is still useful to be aware of how you can change some settings after the JVM has been launched.

Pre-Launch Settings

All options that govern the JVM's launch, including which JVM to launch, are bundled in the xmog_jvm_loader class. You acquire an xmog_jvm_loader instance—or better, a reference to one—through one of its get_jvm_loader() methods. Multiple overloads of this factory method are available, all of which support different styles of initialization with a variety of default arguments.

Please note that there is only ever one singleton instance of an xmog_jvm_loader. Once it has been created all further calls to a get_jvm_loader() method will return the already created instance.

If it is necessary for you to check whether some other code has already instantiated the loader singleton you can use the xmog_jvm_loader::get_jvm_loader_no_create() function that returns a pointer to the loader singleton or NULL if it has not been created yet.

The xmog_jvm_loader type combines two base types that provide two different categories of configuration settings. The xmog_jvm_options class provides all options that deal with the configuration of a JVM. Think of it as the type that allows you to set all the options that you normally provide to the java launcher on the command line.

The xmog_options class provides all the framework configuration options, including the important setJvmPath() method that allows you to specify the JVM that you wish to embed in your C++ application.

In general, it is a best practice to acquire an xmog_jvm_loader instance in your application's main(), configure all the options there, and then attempt to load the JVM. This gives you an early and easy to diagnose point of failure in case something goes wrong.

Post-Launch Settings

Once you have successfully loaded a JVM into your process most of the pre-launch JVM options effectively become no-ops. The pre-launch settings get taken into account in the creation of the JVM and then they are "frozen." Further modifications are allowed but they will not have any impact. For example, appending a jar file to the classpath after the JVM has been loaded does not have the desired effect because the classpath is only used to initialize the JVM and cannot be modified in an already running JVM.

Yet there are some JMS Courier framework settings that can be modified after the JVM has been loaded because they govern the interaction between C++ and Java and not the JVM itself. These settings are available through the xmog_jvm class. Please note that modifying these settings on the xmog_jvm instance only affects threads that will be created or attached to the JVM in the future. Already attached threads continue to use the global settings that were in effect when the JVM was created.

To gain access to a xmog_jvm instance you can call xmog_jvm_loader's load() or get_jvm() methods. Both return a pointer to the xmog_jvm singleton or NULL if the xmog_jvm instance has not yet been created.

Per-Thread Settings

Some settings can be overridden for the current thread. Your gateway to the current thread is the xmog_localenv type. If you look at the generated proxy types you will see that a pointer to this type is an optional argument to just about every method. The JMS Courier runtime maintains all types of glue in these instainces.