Configuring RCP Applications With Pax ConfMan

most applications require configuration settings. applications are often deployed in multiple environments (dev, test, prod, etc) and these environments often require different runtime configurations. also, it’s useful to be able to update an application configuration without a restart. if you find yourself with requirements like these for your eclipse rcp application, you should really check out the osgi configuration admin service.

specifically, the configuration admin service allows you to:

• configure the osgi services that you provide as part of your application.
• configure osgi services that others provide. an example of this is the ability to configure the pax logging service, which i’ll explore in a second post.
• configure spring beans when using spring dm. here is a good reference for using config admin with spring dm .

if you’d like to learn more about the configuration admin service, check out this post or the osgi compendium specification . in this post i’m going to describe how to set up the configuration admin service in an rcp application using pax confman.

what is pax confman?

the configuration admin service doesn’t specify any particular way of storing and accessing properties. each implementation can do what it likes, and pax confman has opted for the simplest approach – properties files.

setting up the target platform

the first step in getting pax confman working in your rcp application is to add the required bundles to your target platform. here is the complete list of bundles which need to be added:

• org.eclipse.equinox.cm ( download )
• org.eclipse.osgi.services ( download )
• org.ops4j.pax.confman.pax-confman-propsloader ( download )
• org.ops4j.pax.logging.pax-logging-api ( download )
• org.ops4j.pax.logging.pax-logging-service ( download )

also make sure to add these bundles to your product configuration and run configuration so they will be included in builds and at runtime.

forcing pax confman to start

if you run your rcp application at this point and examine the running bundles in an osgi console, you’ll notice that the bundles added above are not started. to make the service available at runtime, we need to force them to start using the configuration page (new in galileo) of the product configuration editor.

this page allows us to specify that specific bundles should be automatically started when the application is launched. note that adding bundles to this page currently wipes out necessary rcp bundle settings. after adding these back in, your config page should look like this:

now if you run your rcp application, you should see pax confman logging output to your console. these logs will tell you that the configuration folder cannot be found. so on to the next step!

adding a configuration folder

pax confman allows you to configure your osgi application using standard java properties files, so we need to create a directory to hold these files. to get started, create a folder called confadmin in one of plug-ins that is part of your rcp application. you can call this folder anything you like, and the confman default is configurations. i think confadmin is a better name in that it distinguishes it from the configuration folder used by the osgi framework.

inside the confadmin folder, create two sub-folders called services and factories. these folder names are required.

finally, you need to tell pax confman where your folder is located, and this is done using a java system property called bundles.configuration.location.

when running inside the eclipse ide, the simplest way to do this is to add an argument to your run configuration. mine looks like this:

now when you run the application you should see confman messages indicating that your configuration folder has been located. of course we haven’t added any properties files yet, but the wiring is all in place.

how to handle deployment

there are a variety of ways to handle configuration files in a deployed rcp application:

• place your configuration files in a separate bundle and deploy that bundle as a folder instead of a jar file.
• add your configuration folder to the install directory by utilizing the root property in the build.properties file for a feature.
• use an installer script to copy the configuration files into another directory on a users machine.

no matter which option you choose, you’ll need to provide a bundles.configuration.location vm argument that points to the configuration directory.

what’s next?

well you can now start to configure your own osgi services using pax confman. in my next post i’ll show how to use confman to configure pax logging in an rcp application.

from http://rcpquickstart.com