Create a ProcessEngine with the ConfigurationAdminService

There is a new feature in the camunda BPM OSGi extension and I would like to introduce it to you. So, let's start with the news.

What's new?

The OSGi extension now exports a ManagedServiceFactory to provide another way to configure and automatically share a ProcessEngine. The factory will be automatically exported when the OSGi compendium classes are present. You can then provide your configuration and the engine will be created and exported.

If you've never heard of the ConfigurationAdminService I would like to give you a short introduction.

What is the ConfigurationAdminService?

The ConfigurationAdminService is supposed to make the provision and change of configuration during easier. When you provide a configuration object (a dictionary) the service will find the according ManagedService or ManagedServiceFactory based on a pid (persistent id) and pass the configuration to it.

There are (way ;-) ) better descriptions in the OSGi Alliance blog and the Apache Felix documentation if you want to learn a little bit more about it. Let's see how we can use the service.

How to use it?

As I mentioned before the configuration is just a dictionary. The keys have to corresspondent to the fields of a ProcessEngineConfiguration object. Simply create a HashTable and put everything in it you need to run your engine:

    Hashtable<String, Object> props = new Hashtable<String, Object>();  
    props.put("databaseSchemaUpdate", ProcessEngineConfiguration.DB\_SCHEMA\_UPDATE\_CREATE\_DROP);  
    props.put("jdbcUrl", "jdbc:h2:mem:camunda;DB\_CLOSE\_DELAY=-1");  
    props.put("jobExecutorActivate", true);  
    props.put("processEngineName", "TestEngine");

Next you gotta get the ConfigurationAdminService and call createFactoryConfiguration() with the following PId:
org.camunda.bpm.extension.osgi.configadmin.ManagedProcessEngineFactory

There is also a constant in the ManagedProcessEngineFactory interface. After that pass your dictionary to the Configuration object by calling the update() method. And that's it. Your ProcessEngine will be created and exported.

Now that you know how to use the service I would like to tell you what makes it special.

Why use the ConfigurationAdminService?

I remember when I first read about the ConfigurationAdminService my thought was: "That's a really great idea!". By using the service you have several ways of providing configuration for your ProcessEngine. The easiest thing to image is that you store your configuration files in separate bundles. Every time something changes you update that bundle.

Depending on your environment there are more ways. In Apache Karaf you could place a file named
org.camunda.bpm.extension.osgi.configadmin.ManagedProcessEngineFactory.cfg in the etc directory. Karaf would find the factory and pass the configuration to it.
Apache Felix and Equinox also provide ways to read and use configuration files.

Also, the ConfigurationAdminServices helps you to provide different configurations for different environments. At least text files are to change and provide than .class files.

Finally I want to tell you some details about the implementation.

How is it implemented?

I gotta admit that the implementation is not that special. The factory uses Commons BeanUtils to find the setters for the properties. Because the setters of ProcessEngineConfiguration provide a fluent way I couldn't use the classes BeanUtils or PropertyUtils. That's why I "combine" the setter-name on my own and invoke the method with MethodUtils.

Every time the configuration of a ProcessEngine changes I stop that engine, unregister it and create a new one and register that one. That is the only way to "change" the configuration of a ProcessEngine. Maybe a ProcessEngine/Configuration needs an update() method.

I would appreciate any hints or recommendations on how to improve the factory. Since it's my first try implementing a ManagedServiceFactory.

So, enjoy the new service!