Kilim 2 Tutorial

0 - Kilim2, what is it for ?

Kilim is a generic open-source configuration framework for Java, which can be used easily with existing applications, frameworks, and systems. It gives your applications the opportunity to be configured :

statically by simple and readable XML files,
dynamically via any generic JMX console.

It is not intrusive at all, and makes no assumption on how your existing code has been developped:

no particular interfaces need to be implemented,
the application's architecture does not need to be modified.

If you are tired of writing boring configuration code right in the middle of your business logic, Kilim might just be the solution.

0-1 - Overview

Kilim 2 enables :
1) the defininition of composable abstractions called Templates, capturing encasulated sub-systems defining :

their properties,
their connectivity (slots).

2) the definition of the mapping of these abstractions to existing code in terms of :

constructors used to create the various instances they may contain,
setters/methods used to configure...
and to connect them.

3) the recursive assembly of these bricks, allowing to build complex systems :

without any programming skill,
allowing dynamic extension,
and re-configuration,
in a hierarchical, self-documented, clean and maintainable way.

1 - Static Definition of Templates

1-1 - Definition of an Abstract Template

All the examples given in this tutorial are implemented in the Kilim2Tutorial distribution available through CVS.

All the templates are contained in the kilim directory,

All the sources are contained in the src repository,

The needed .jar (included the kilim2.jar) can be found in the libs directory,

This documentation is in the doc directory.

The build.xml file contains the following ant tasks :

compile compiles the examples,

run.test runs a test with template quotes/application/Yet Another Composite Inherited, you can try it with another template simply by changing the value of the argument in the build.xml file,

run.test.JMX launches a JMX server. To see/configure the component, launch any browser on the following URL http://localhost:8082. It instantiates the template quotes/application/Yet Another Composite Inherited with JMX, you can try it with another template simply by changing the value of the argument in the build.xml file.

Let us define in the Kilim description language (which is an XML dialect) the Channel Template of the publish & subscribe paradigm :

a Publisher publishes financial data in a Channel,
Subscribers receive the published data,
Console is a subscriber able to display the received data,
MultiConsole is a container of Consoles.

The name attribute of the Template tag defines the name of the template. The templates can belong to a package (like in Java), in this case, the name in the attribute tag must be its fully qualified name, using / as a separator.
In this example, the Template belongs to package quotes, it must be stored in a file contained in a subdirectory quotes of the CLASSPATH.

Then we add in the template body a property tag defining the type, the value and the accessibility of the property name. Available types are :


byte, short, int, long
char
float, double
boolean
string

The different levels of accessibility are

public, the property can be accessed from any template,
private, it can be accessed only from the containig template,
protected, it can be accessed by all the templates extending the containing template.

These levels of accessibility will be the same for all the members of the template, with the same semantics.

We can then define two extension slots. They will be used to plug publishers and subscribers into the channel. In this first definition step, we stay at a very abstract level, an do not make any assumption about :

the number and type of the objects needed to map a Channel abstraction,
the type and name of the templates that can be plugged in the slots.

1-2 - Specifying an abstract object mapping for the `Template`

Now we will define the object interfaces offered and required by the Template. These interfaces will, in the next section, be mapped on one, or many, language objects. The aim of the current step is not to describe the precise mapping of the template yet, but to define, for each interface (we call them ports) :

its name,
its visibility (from inside/outside the template), private, protected or public,
its arity (will it be mapped on one, or many language objects),
is it offered or required by the template.

Ports are used to exchange references on object instances between the template and the rest of the system. The ports defined directly in the template body are used to provide/retrieve references to/from the outside of the template. The ports defined in the slot blocks are used to define how the template exchanges references with another template when it is plugged into it.
The template expects to :

retrieve from the plugged template all the offered ports
provide the plugged template with all the required ports it offers.

In out example, the template Channel :

offers a port "channel", which is the interface of the language object implementing the channel concept (probably some kind of stub),
when a template is inserted in its "publisher" slot, it expects to retrieve from it a reference to a publisher, through a "publisher" port,
when a template is inserted in its "subscriber" slot, it expects to retrieve from it a reference to a subscriber, through a "subscriber" port.

The subscriber port has an "any" arity, it means that many subscriber templates can be inserted in the slot, while only one publisher can be inserted in the subscriber slot because port "publisher" has an arity of 1.

This template is still abstract, as, if it is instantiated, no language object will be instantiated.

The template Channel is defined in file kilim/quotes/Channel.kilim.

1-3 - Pinning a template to code

Now time has come to define how this template will be mapped on language objects.
First, we want to preserve the genericity of our abstract template Channel, in order to define, if necessary, different mappings, all of them compliant with the abstract specification.

We will do that by a classical extension mechanism. LocalChannel template extends Channel, this means that it inherits all the properties, slots and ports of Channel.

Let us now precise how the port channel is mapped on code. This mapping will be achieved by a bind block. In this bind we declare that the binding of the port is done by instanciating a new object of class quotes.local.LocalChannel. This instanciation is done by calling the constructor taking a String as parameter. This parameter will be provided by the property name defined in the super template. This is achieved through a reference tag designing the property through is name.

Next step will be to describe what happens when a template is plugged into each slot. When a template instance is plugged into a slot, a binding event is generated by the runtime. This event can trigger a call to any specified method on any given interface, with an arbitrary number of parameter among :

a reference to any property,
a reference to any port of the template,
a reference to any port of the plugged template instance.

We will now describe what happens when a subscriber is plugged into the channel. The binding event triggers a call to the method addSubscriber() on the instance mapping the port channel, with the object mapping que port subscriber of the plugged component as a parameter.

What happens with the publisher port is quite different. Here, the event that triggers the call to the method setChannel() is the binding of the port channel itself. This means that as soon as the LocalChannel instance will be created, the method will be called. This will work only if the plug of the publisher into the channel has been done prior to the instanciation of the template.

The template LocalChannel is defined in file kilim/quotes/local/LocalChannel.kilim.

1-4 - Assembling Components

Let us now build a template by simply assembling existing templates. For example we want to build a template representing a sub-system with one channel, one publisher plugged into it, and one subscriber.

The tag instance allows us tu create an instance of a given template. The attributes will define :

the visibility of the created instace,
its name
and the fully qualified name of the instantiated template.

In the instance block we can override existing properties in order to change their default value. Here the property name, the default value of which was "Default Channel", is replaced by "USD Channel".

Now we will specify which template instance (we will call these "components" from now on) is plugged in which slot of the channel. To do that, we use the tag plug. Its attributes reference :

the name of the instance that should be plugged,
the name of the slot where the plug occurs.

In this example we want to make this template ready to be assembled with others, with a view to building a global console displaying the quotations of different currencies. To achieve this goal, we create an external port, named console which makes the port console of an inner component available from the outside. It is thus ready to be plugged, in turn, in an other higher level template, like in the following example :

Many assembly examples are available in the distribution, all of them in the kilim/quotes/application directory :

JPY Example.kilim is the example detailed in the preceding paragraph,

USD Example.kilim is nearly the same, but with USD currency,

JPY and USD Example.kilim shows how to build higher level templates by assembling the two preceding templates,

the others toy with the existing templates, assembling and re-assembling them recursively, and shows different ways of achieving the same purpose.

1-5 - Creating a component from Java code

Now we can try to instantiate one of the components we have previously specified via .kilim files.

The API to do so is extremely straightforward :

First, we use the method newComponent() from helper class org.objectweb.kilim.helpers.KilimHelper

the fully qualified name of the template that should be instantiated,

a class, the ClassLoader of which should be used to load the classes specified in the .kilim file.

Then, we use method getInterface() to retrieve a reference on the console interface, which the runtime representation of the console port,
Finally, we use method getValue() to retrieve a reference on the language object (here a javax.swing.JFrame

Of course, due to the lack of genericity in Java, we then have to cast this reference into a javax.swing.JFrame reference in order to make it visible.

In order to correctly instantiate and configure the console interface, all required objects will be instantiated and configured lazily, according to the .kilim specification.

The Launcher's code can be found in src/test/Launcher.java

2 - Dynamic Reconfiguration

2-1 - Reconfiguration API

Now we have an instantiated component running (e.g. a Channel), mapped on instantiated language objects. Kilim 2.0 gives us the possibility of, to some extent, to reconfigure the Component once instantiated. In order to do that the only thing we need is have kept, in some way, a reference on the Component we want to modify. Here are the different modifications we can make on a component :

Modify the value of a `property`

This can be achieved in two easy steps :

First, retrieve a reference on the interface bearing the property's name : component.getValue("propertysName"), what we get then is a ComponentInterface,
We then check wether this interface is a ComponentProperty by calling the isProperty() method,
if the result is true, then we cast is into a ComponentProperty reference,
and simply call the setValue(value) method.

This changes the value of the ComponentProperty, but not the state of the underlying language object.

This is not a drawback, this is a feature ! In fact, we probably want to change the value of many properties before we actually change the state of the real objects (for example we change the value of property A and B, and then trigger a unique call to the setAandB(A,B) of the language object)). The moment when we want the changes to take effect on the objects must then be explicit, and this is precisely what we explain in the next paragraph.

Update the state of the underlying language object

Another question that rises when it comes to change a property's value is :

What happens when I change the value of a property which is used to configure the state of many language object, through different methods

The answer is quite simple : you will have to call explicitly the method update() on all the ComponentInterfaces that are likely to be concerned by the property's modification.

Plugging and unplugging components

This is as simple as it gets :

get a reference on the ComponentSlot where you want to plug your new Component, through a call to cmpnnt.getSlot("slotName"),
call method slt.plug(newComponent).

In this case, nothing more needs to be done, as the semantics of insertion is intrinsicly atomic.

The unplug is done exactly in the same way. This code snippet sums up the whole thing.

2-2 - Reconfiguration through JMX

The Java Management Extensions (JMX) technology represents a universal, open technology for management, and monitoring that can be deployed wherever management and monitoring are needed. In Kilim, JMX is used to :

give distant access to Components through different protocols (RMI, HTTP, etc.),
and thus allow remote reconfiguration :

properties reconfiguration,

runtime plug and unplug of components,

and monitoring.

Specifying what is monitorable/visible/configurable in an existing `Component`

Making an existing component monitorable through JMX can easily be achieved in a few simple steps :

create a new template extending the template you want to monitor,
to make a property or a slot visible/monitorable/reconfigurable :

add an instance of template JMX Deployment Data named JMX near the member tou want to monitor,

and bind its ports {visible,editable} to the members you want to make {visible,editable}.

if you want to make members of sub-instances visible, bind the monitored sub-components port of the JMX instance to the port THIS of the sub-component you want to monitor.

See template kilim/quotes/application/Yet Another Composite Inherited with JMX.kilim for more details.

Launching the JMX server, registering the `Component`

Now take the usual steps to launch you JMX server and your adaptors (a complete example is given in the test.LauncherJMX class).

The only thing you have to do to make your Kilim Component visible through any JMX console is to register it on the server. This can be achieved simply by :

instanciating an instance of org.objectweb.kilim.tools.jmx.ComponentMBean wrapping the Kilim Component,
registering it on the server by calling method registerMBean().

And this is it. Your component is now visible, with all its exported properties and slots. You can now, through any JMX compliant console, do all the operations listed in the previous section (Reconfiguration API) without a line of Java, simply by clicking.

The LauncherJMX's code can be found in src/test/LauncherJMX.java