Getting started with Kilim: Introduction to Kilim Configuration Files

Abstract

The purpose of this document is to introduce the two types of Kilim Configuration Files, the bootstrap and the runtime ones.

The examples in this document are extremely simple, since they are based on setting String properties. For an in-depth example of leveraging the more advanced constructs in Kilim (atoms, assemblages, factories, ...) refer to the Getting started with Kilim guide.

Create a new Kilim configuration

Kilim Configuration Files

Kilim Configuration Files (kcfs) are xml files that comply with the Kilim configuration DTD.

Here is a very simple kcf example:

<?xml version="1.0" encoding='ISO-8859-1' ?>
<!DOCTYPE Configuration SYSTEM "configuration.dtd">
<CONFIGURATION generated="Config" bootstrap="org.objectweb.jonathan.libs.kernel.helpers.Kernel">
  <ELEM name="text">
    <PROPERTY type="String" value="Kilim is great"/>
  </ELEM>
</CONFIGURATION>
      

This configuration contains just one String property called text. The value of this property is Kilim is great.

Do not worry about the various fields in the CONFIGURATION tag, they will be explained further on.

The Kcf2java compiler

From now, you just have to know how to access this property from your Java application.

Kilim provides a tool which converts any kcf to a Java class. This tool is org.objectweb.jonathan.tools.Kcf2java, and it is available in kilim-tools.jar.

The name of the generated Java class is provided in the configuration via the generated attribute to the CONFIGURATION tag.

In the example above, the generated file will be Config.java.

Technically, a number of internal parameters must be set in a compiled kcf in order for Kilim to bootstrap. However for convenience's sake we provide a bootstrap kernel class which takes care of this, so that you do not have to worry about it. This class is org.objectweb.jonathan.libs.kernel.helpers.Kernel and should you wish to use it, you must specify it as bootstrap class in the bootstrap attribute of the root CONFIGURATION element.

Unless you require some specific bootstrap code, the rule of thumb is: always use bootstrap="org.objectweb.jonathan.libs.kernel.helpers.Kernel.

Here is the command line to compile the kcf file to a java source file:

$ java org.objectweb.jonathan.tools.Kcf2java -s . -noc Config.kcf

Note that the following jar files must be accessible from your classpath when you invoke the Kcf2java tool: kilim.jar, kilim-tools.jar and nanoxml-lite-2.2.1.jar.

The following java class shows how the property is loaded when needed:

import org.objectweb.jonathan.apis.kernel.Context;

public class Main {

   public static void main(String[] args) {
      Context $config = Config.newConfiguration(Main.class);
      Object $object = $config.getValue("text", (char)0);
      System.out.println("Found : "+$object);
   }
}

The org.objectweb.jonathan.apis.kernel.Context class represents a set of typed objects, each identified by a name. This class is part of kilim.jar.

After you compile Config.java and Main.java, you can run the Main class (be sure that kilim.jar and nanoxml-lite-2.2.1.jar are accessible from your classpath):

$ java Main
WARNING: alias of name ../../runtime configuration file not found.
Found : Kilim is great

Do not worry about the warning message, it will be explained later.

Externalise the architecture

From now, we would like to extends this basic configuration (which will be named bootstrap configuration) with some others components. But unlike to the ones defined in the bootstrap configuration, these new components have to be dynamic (we want to be able to change them without recompiling the kcf and the generated Java class).

Therefore, we will just add in the bootstrap configuration a new PROPERTY called runtime configuration file. The value of this property will be the name of the kcf which contains the description of the new components. This configuration will be named runtime configuration.

Here is the new Config.kcf file:

<?xml version="1.0" encoding='ISO-8859-1' ?>
<!DOCTYPE Configuration SYSTEM "configuration.dtd">
<CONFIGURATION generated="Config" bootstrap="org.objectweb.jonathan.libs.kernel.helpers.Kernel">
  <ELEM name="text">
    <PROPERTY type="String" value="Kilim is great"/>
  </ELEM>
  <ELEM name="runtime configuration file">
    <PROPERTY type="String" value="runtime.kcf"/>
  </ELEM>
</CONFIGURATION>

Then, we have to create the runtime.kcf file:

<?xml version="1.0" encoding='ISO-8859-1' ?>
<!DOCTYPE Configuration SYSTEM "configuration.dtd">
<CONFIGURATION>
  <ELEM name="another text">
    <PROPERTY type="String" value="Kilim is dynamic!"/>
  </ELEM>
</CONFIGURATION>

Consequently, we can access transparently, like previously, the configuration:

import org.objectweb.jonathan.apis.kernel.Context;

public class Main {

   public static void main(String[] args) {
      Context $config = Config.newConfiguration(Main.class);
      Object $object = $config.getValue("text", (char)0);
      System.out.println("Found : "+$object);
      $object = $config.getValue("another text", (char)0);
      System.out.println("Found : "+$object);
    }
}

After you regenerate the Config.java class, and recompile Config.java and Main.java, you can run the example again:

$ java Main
Found : Kilim is great
Found : Kilim is dynamic!

Now, you can change the property in runtime.kcf and run the Main class without recompiling.

Bootstrap configuration vs runtime configuration

So it is possible to put components either int the bootstrap configuration or in the runtime configuration. Here are some factors to take into consideration when you decide:


Last updated: 2002-09-09

Sylvain Chambon and Bruno Michel.