Lesson 1: Introduction

Runtime configuration can be grouped into a few rough functional categories:

1. Settings that govern the JVM's internals like classpath, etc.
2. Settings that govern runtime internals like logging.
3. Settings that govern .NET features like COM support.

Most of our customers can focus on the first category.

Overview

All configuration APIs are in the Codemesh.JuggerNET namespace. The IOptions and IJvmOptions interfaces declare all the settings that are configurable. They are aggregated into the IJvmLoader interface through which you usually access them. You can acquire an instance of an IJvmLoader with a call to one of the JvmLoader.GetJvmLoader() variants.

Once you have configured all options, you can explicitly load the JVM via IJvmLoader.Load() or rely on the on-demand JVM loading that occurs when your application executes the first call that requires a JVM.

What do you need to configure? If you start out with a Java application that you are trying to reproduce from .NET or you have a Java snippet you need to call from .NET, you pretty much have the answer to your question. You need to somehow provide all the options that you would pass to the java launcher to run your code. Additionally, you usually need to configure which JVM to use. In Java, that's something you do implicitly by choosing a particular java launcher. In .NET you will have to point the JDBC Courierruntime at a particular jvm.dll that is compatible with your process.

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

Post-Load Modifications

Once you have successfully loaded a JVM into your process most of the configurable JVM option setters become no-ops. The settings are taken into account in the creation of the JVM and then they are effectively "frozen." Further modifications are allowed but they will not have any impact. For example, changing the initial heapsize or appending a jar file to the classpath after the JVM has been loaded does not have the desired effect because those settings are only used to initialize the JVM and cannot be modified in an already running JVM. You can change the JDBC Courier setting but that won't make any difference to the already running JVM.

Also note that it is usually not possible to shut down a JVM in a process and then start another one. All the JVMs we have encountered assume that their lifecycle is essentially the process' lifecycle and cannot reinitialize themselves after having exited.

Sample Snippet

A minimal snippet that performs some minimal configuration tasks is shown below.

using Codemesh.JuggerNET;

...

IJvmLoader loader = JvmLoader.GetJvmLoader();

loader.JvmPath = ...;
loader.MaximumHeapSize = 512;

try {
    IJvm jvm = loader.Load();
}
catch( System.Exception e ) {
    ...
}

Three Basic Configuration Mechanisms

There are three basic configuration mechanisms. The snippet above shows explicit, programmatic configuration, the mechanism that is at the heart of all three.

You can also use a configuration file from which the runtime will read the configuration settings.

And last but not least, there are configuration hooks. Configuration hooks provide a callback-based self-configuration facility for assemblies.

The following three lessons demonstrate each approach.