Lesson 2: Explicit Configuration

Introduction

Explicit configuration is the programmatic configuration of your combined Java and .NET application through API calls. It lies at the heart of all other configuration mechanisms because the other mechanisms can be implemented in terms of the epxlicit configuration API.

The IOptions and IJvmOptions types declare the public configuration APIs that are implemented by the JvmLoader type, through which you usually access them.

You typically acquire a reference to the singleton JvmLoader instance in your program's Main() or in a custom initialization method that you invoke from your program's Main(). The simplest way to do it is by calling the static GetJvmLoader() method without any arguments and then start setting the configuration properties or calling configuration functions declared by these two types:

IJvmLoader loader = JvmLoader.GetJvmLoader();

// start making configuration API calls
loader.JvmPath = ...;
loader.DashDOption[ "key" ] = "value";
loader.DashXOption[ "mx" ] = "512m";
loader.AppendToClassPath( ... );
    
...

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

When to Configure

As you can see in the above code snippet, we explicitly try to load the JVM after the configuration is complete. While this is not strictly necessary (the JDBC Courier runtime supports on-demand loading when Java is required) it is highly recommended. Doing it this way gives you one and only one point at which the JVM initialization could fail, making the debugging of configuration issues much easier.

You want to make sure that the configuration is complete before you make your first Java call or the JDBC Courier runtime will simply use its default settings to load a JVM when asked to do something in Java. Most JVM settings are "frozen" in place once the JVM has been loaded and cannot be modified after the fact. Therefore, particularly if you have a large codebase, it is important to perform the configuration as early as possible. We recommend that you do it right at the beginning of your program's Main(). If your application has multiple entry points you should factor the JVM configuration and loading code into a separate method that you invoke from all possible entry points.

Example

You can find an example in the code generator distribution at examples/dotnet/v3/configuration/explicit. The readme.html file in that directory contains a description and the instructions on how to build and run the example.

If you take away nothing else from that example, you should still pay attention to the error handling around the JVM loading. When you're not familiar with the product yet it can be quite common to misconfigure the JVM path or another crucial JMV setting with the consequence that the JVM will not load. Getting some form of error feedback as well as avoiding the continued execution of the application without a JVM will save you many hours of debugging.

Other Techniques

For a more advanced, yet more complex technique you can see the the lesson on Configuration Hooks.