Runtime Configuration

Classes
class	xmog_jvm_loader
	The class that acts as a factory for xmog_jvm_loaders and thereby for our JVM abstraction. More...
class	xmog_jvm_options
	A class abstracting the maintenance and initialization of JVM configuration options. More...
class	xmog_options
	This class wraps around options that govern the overall behavior of the runtime library with respect to logging, tracing, errorhandling, etc. More...
class	xmog_remote_client_options
	A class that represents the settings that a remote client uses to connect to a shared JVM. More...
Typedefs
typedef void(XMOG_CALLING_CONVENTION *	xmog_jvm_loader::XMOG_CONFIG_HOOK )(void *pLoader, int when)
	A typedef for registration hooks.
Enumerations
enum	xmog_bytecode_verification { VerifyUndefined = -1, VerifyNone = 0, VerifyRemote = 1, VerifyAll = 2 }
	Bytecode verification levels for JDK 1.1. More...
enum	xmog_jvm_verbosity {   VerbosityUndefined = -1, VerbosityNone = 0, VerbosityClass = 1, VerbosityGC = 2,   VerbosityJNI = 4, VerbosityAll = 7 }
	Verbosity levels for the JVM. More...

---

Detailed Description

Overview

When you're using Java from a different programming language, you need to configure the Java runtime options as well as the framework options. Java options include such items as the classpath and are configured by class xmog_jvm_options; general framework options include such items as the error handling strategy and are configured by class xmog_options; shared JVM framework options include such items as the connection string and are configured by class xmog_remote_client_options.

The main class responsible for configuring all these options is the xmog_jvm_loader class. It aggregates the above groups of options via inheritance. You typically access all of the options through a singleton instance of type xmog_jvm_loader. You acquire the singleton instance through one of several different factory methods called get_jvm_loader. Each of the methods takes different arguments and selects a different method for initializing the returned instance. The methods include such mechanisms as an old-style JunC++ion configuration file, a .NET style config file, the Windows registry, or environment variables.

Once you have an instance of an xmog_jvm_loader, you can further modify its settings and thereby affect how the JVM is being loaded. Please note that most options can only be set meaningfully before a JVM has been loaded into the native process. This means that you have to be careful to avoid unintentional JVM loading before you have fully configured your runtime environment.

The mechanics of JVM initialization

A JVM is loaded automatically for you the very first time that one of the runtime types needs to access the Java side. This can for example happen because you create a wrapper instance of type String or any other proxy type. You can rely on this behavior and everything will work as expected as long as you have your application correctly deployed and configured.

If at all possible though, you should try to explicitly load the JVM in a well-defined place in your application where you perform initialization tasks. This can help a lot by centralizing error handling and receiving an error that is due to a misconfiguration early rather than halfway through the application. Even if you rely on configuration files or the registry for supplying the configuration information, you might wish to have a block of code like this in your application's main() or in whichever method performs initialization for your use case:

      try
      {
        xmog_jvm_loader::setConfigFile( "c:\\temp\\my.config" );
   
        // explicitly loads the JVM using information from the configuration file
        xmog_jvm * pJvm = xmog_jvm_loader::get_jvm_loader().load();
   
        if( pJvm == NULL )
          ; // handle failure in which no exception was thrown
      }
      catch( xmog_exception & e )
      {
          ; // handle failure in which exception was thrown
      }

Depending on the factory method that you are using to create your xmog_jvm_loader instance, and on what kind of proxy classes are in your process, different activities might take place during the determination of your initialization options.

Most proxy classes will have been generated with a named configuration embedded in them. When these classes are loaded into the process, they will register their named configuration with the runtime framework. When the time comes to load a JVM into the process, all registered named configurations will be inspected and their collective options will be used to initialize the JVM. The 3.0 version of the runtime library is the first version that supports both the consolidation of settings from more than one named configuration and the total absence of named configurations. In the absence of named configuration information, you have to initialize your application using one of the following mechanisms:

• using environment variables
• using a JuggerNET-style XML configuration file
• using program code
• using configuration hooks

Working with a preloaded JVM

When you have proxy types residing in a library that might be used as a native library in a Java application or when the loading of the JVM is outside of your control, you need to take special care about the configuration of the runtime.

First of all, you need to understand that any JVM configuration that you might be performing is almost totally useless because it only gets taken into account when the JVM is loaded. If the JVM is already loaded whatever classpath and -D or -X options you're configuring via the configuration API will simply be ignored. Nevertheless, you might need to configure the interoperability, non-JVM-related aspects of the runtime, for example the error handling policy, the trace level, the native string encoding, etc.

These framework configuration aspects could for example be configured in a configuration hook that is built into your shared library and gets called when the xmog_jvm_loader singleton is created.

Here's a checklist for this kind of usecase:

• are all classes/jarfiles on the classpath (either of the java process or of the out-of-band mechanism that is responsible for loading the JVM)?

• are all other required JVM configuration options specified (-D options, -X options)?

• are you a) happy with the runtime defaults or b) specifying framework initialization options in a way that is sure to get called when the shared library is loaded?

• if you're not running on Windows, are you specifying the identical JvmPath to the one that you're running with? On Windows, we use a platform API to check for an already loaded jvm.dll and use that one. On other platforms, you need to make sure that the configured JvmPath corresponds with the Jvm that is used to execute the Java parts of the application.

Configuration Hooks

Configuration hooks allow you to register a function that will be called before and after the instance of xmog_jvm_loader has been configured as specified by the user. This is a very useful feature when you're using a proxy frmaework or a third-party proxy library that requires certain configuration settings regardless of what else the user might wish to configure. A proxy library might for example always have to add a certain jarfile to the classpath, irrespective of what other classpath roots the user has configured.

While you can register the configuration hook manually if you so desire, it is most useful if it gets registered automatically, for example when a proxy library is being loaded into a process. This is easy to achieve by declaring a static variable whose initializer registers the configuration callback. The following code snippet which would be part of a proxy library illustrates this approach:

      // a class whose only purpose is the registration of a callback hook
      class config_hook
      {
      public:
   
        // the constructor registers the hook
        config_hook()
        {
           xmog_jvm_loader::registerConfigurationHook( myConfigHook );
        }
   
      private:
   
        // the configuration hook 
        static void XMOG_CALLING_CONVENTION myConfigHook( void * pl, int when )
        {
          xmog_jvm_loader *   pLoader = (xmog_jvm_loader*)pl;
   
          // here we can do things before the framework initialization (via
          // reading config files, registry, or environment variables) takes place.
          // XMOG_BEFORE_INITIALIZATION is currently unsupported.
          if( when == XMOG_BEFORE_INITIALIZATION )
          {
            // currently unsupported
          }
          // here we can do things after the framework initialization (via
          // reading config files, registry, or environment variables) has taken place.
          // The user still has a chance to modify our settings in code before the
          // JVM has been loaded.
          else if( when == XMOG_AFTER_INITIALIZATION )
          {
            // append a file to the classpath and add a -D option
            pLoader->appendToClassPath( "../lib/mylib.jar" );
            pLoader->setDashDOption( "mylib-installed", "true" );
          }
          // here we have the last say about configuration and can override any
          // user specified settings.  This callback is called right before the
          // the JVM is loaded.
          else if( when == XMOG_BEFORE_LOADING )
          {
            // make sure we ask for at least 256MB of heap
            if( pLoader->getHeapSizeInMB() < 256 )
              pLoader->setHeapSizeInMB( 256 );
          }
          // here we can perform initialization tasks after the JVM has loaded.
          // This will only be rarely useful, but it could allow you to dynamically
          // add resource roots to the context classloader or to perform some
          // diagnostics right after the JVM is supposedly initialized
          else if( when == XMOG_AFTER_LOADING )
          {
            // add the jar files in a directory to the classpath if the JVM
            // loaded successfully
            if( pLoader->getJvm() != NULL )
                xmog_java_class::addDirectoryJarFiles( "..\\lib" );
          }
        }
      };
   
      // when this object is initialized, the hook is registered
      static config_hook     hooker;

We also support the aliases XMOG_BEFORE for XMOG_BEFORE_INITIALIZATION and XMOG_AFTER for XMOG_AFTER_INITIALIZATION.

Don't assume that your library is going to be the only library that attempts to configure the runtime environment. In particular, is is generally a good practice to do the following in your configuration hook:

• be considerate to others: don't "set" where you can "append". If you need to make sure that your jar file is on the classpath, append to the classpath and don't overwrite the classpath.
• be smart: check whether your setting is already present before specifying it. If you need to make sure that the heap is at least 256MB in size, check first to see whether the user specified more, in which case you shouldn't override the user-provided value.
• don't assume any order for when multiple libraries are loaded. The operating system has control over loading libraries and therefore over the order in which configuration hooks are registered (and executed).

You hopefully have a pretty good idea now of what you can do with this feature if you're shipping libraries to your users.

---

Typedef Documentation

typedef void(XMOG_CALLING_CONVENTION * xmog_jvm_loader::XMOG_CONFIG_HOOK)(void *pLoader, int when) [inherited]

A typedef for registration hooks. Once a registration hook has been registered via the registerConfigHook method, it is called when the xmog_jvm_loader instance is being created. It is called at least three times with different values for when: at first with XMOG_AFTER_INITIALIZATION This call occurs right after the framework initialization for the xmog_jvm_loader has taken place, i.e. after configuration files or the registry have been read. It occurs before the user has a chance to make modifications to the configuration in application code. then with XMOG_BEFORE_LOADING This call occurs right before the framework attempts to load the Java virtual machine, i.e. after the user has had a chance to make modifications to the configuration in application code. Any changes made to the configuration here cannot be overridden by the programmer anymore. and finally with XMOG_AFTER_LOADING This call occurs right after the framework has successfully loaded the Java virtual machine, Any changes to the xmog_jvm_loader's configuration are pointless at this point, but you can use this point in time to check the configuration or dynamically append resource roots to the classpath. This allows you to perform your configuration customizations in a way that makes them the default values (to be overwritten by the user) or in a way that makes them priority values (potentially overriding your user's settings). Parameters: pLoader  a pointer to the xmog_jvm_loader instance. when  one of XMOG_AFTER_INITIALIZATION, XMOG_BEFORE_LOADING or XMOG_AFTER_LOADING. Every installed hook is called multiple times with different values of when. Other calling times might be added later, so please code defensively and always test when for the proper value before executing your configuration task. XMOG_BEFORE is an alias for XMOG_AFTER_INITIALIZATION; XMOG_AFTER is an alias for XMOG_BEFORE_LOADING.

---

Enumeration Type Documentation

enum xmog_bytecode_verification

Bytecode verification levels for JDK 1.1. Enumeration values: VerifyUndefined  No verification override is specified. VerifyNone  Bytecode verification is turned off. VerifyRemote  Bytecode verification is enabled for remotely loaded code. VerifyAll  Bytecode verification is enabled for all code.

enum xmog_jvm_verbosity

Verbosity levels for the JVM. The different levels of verbosity can be ORed to create custom verbosity levels. Enumeration values: VerbosityUndefined  No verbosity level has been defined. VerbosityNone  Verbosity level is set to unverbose. VerbosityClass  Classloading is verbose. VerbosityGC  Garbage collection is verbose. VerbosityJNI  JNI is verbose. VerbosityAll  Everything is verbose.

---