Configurator

Tools Location
Source Code https://bitbucket.org/amdatu/amdatu-configurator
Wiki https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Configurator
Issue Tracking https://amdatu.atlassian.net/browse/AMDATUCONF
Continuous Build https://amdatu.atlassian.net/builds/browse/AMDATUCONF

Introduction

Amdatu configurator provides a simple way of provisioning configuration files to your OSGi application, allowing you to use the
same set of configuration files to run your OSGi application locally as you would need for deploying your application
using Apache ACE or DeploymentAdmin.

It provides the following features:

  • provisions MetaType/AutoConf based configuration files;
  • provisions property-file based configuration files;
  • allow simple variable substitutions similar as to Apache ACE supports;
  • a simple API to provision configuration files programmatically;
  • a couple of simple Felix Gogo commands to list and update configurations.

What this project does not provide:

  • a FileInstall like functionality, where configuration files and bundles are automatically monitored and updated if
    necessary. The reason for this is that we do not want to mimic the behaviour of FileInstall (FileInstall does this
    already), and that in production systems this functionality is often not desired nor used. However, this functionality
    can be mimicked by using the programmatic API of Amdatu Configurator;
  • A set of Gogo shell commands to alter configurations such as provided by 1.

Components

Bundle Required Description
org.amdatu.configurator.autoconf yes Service that can provision configurations to ConfigurationAdmin using file-based resources
org.amdatu.configurator.properties yes Reads Java properties files and provisions them to ConfigurationAdmin
org.amdatu.configurator.shell no Provides Felix Gogo commands to list and update configurations

Dependencies

The following table is an overview of the required and optional dependencies for Amdatu Testing:

Bundle Required Description
org.apache.felix.dependencymanager yes Apache Felix Dependency Manager is used internally by all Amdatu components
OSGi ConfigurationAdmin service (e.g. Apache Felix ConfigAdmin v1.8.0) yes Used to configure the services which are going to be tested
OSGi LogService (e.g. Apache Felix LogService v1.0.1) no Used to log output

Even though you are free to provide your own implementations, all dependencies (as the given examples where applicable) can be resolved from the Amdatu dependencies repository.

Deployment

Deploy the org.amdatu.configurator.autoconf and/or org.amdatu.configurator.properties bundle with your application.
When this bundle is started by the OSGi framework, it will look for a directory named conf in the current working
directory of your framework and regard all files ending in .xml as possible AutoConf resources. Files ending in
.cnf, .cfg or .config are considered property file resources.

Usage

The API of Amdatu Configurator is relatively straight forward, you can use the org.amdatu.configurator.Configurator
services to provision a single configuration resource, provision all configuration resources in a given directory, or
list the already provisioned configurations. Distinction between various configurator services can be made by using the
type and/or file.extensions service properties. For example, you can ask for a configurator that is capable of
handling .cfg files by:

ServiceReference[] serviceRefs =
  bundleContext.getServiceReferences(Configurator.class.getName(), "(file.extensions=.cfg)");

Or, if you want a specific type of configurator (currently autoconf and property are the only supported types):

ServiceReference[] serviceRefs =
  bundleContext.getServiceReferences(Configurator.class.getName(), "(type=autoconf)");

Configuration

A couple of configuration options exist for the Amdatu Configurator project. These options can be set as framework
options in the run configuration of your application. For the AutoConf bundle, the following options are recognized:

  • org.amdatu.configurator.autoconf.dir, takes a string argument that is used as directory where your configuration
    files are stored. Defaults to ./conf;
  • org.amdatu.configurator.autoconf.prefix, allows one to specify the common prefix used for all placeholders in your
    configuration files. By default, the same prefix is used as Apache ACE, which is context.;
  • org.amdatu.configurator.autoconf.verbose, if set to true, increases the verbosity of logging to show more details
    on the whole provisioning process. By default, non-verbose/sparse logging is enabled (false).

For the Properties bundle, the following options are recognized:

  • org.amdatu.configurator.properties.dir, takes a string argument that is used as directory where your configuration
    files are stored. Defaults to ./conf;
  • org.amdatu.configurator.properties.prefix, allows one to specify the common prefix used for all placeholders in your
    configuration files. Defaults to context.;
  • org.amdatu.configurator.properties.verbose, increases the verbosity of logging to show additional details on the
    provisioning process. Defaults to false.

In addition, the logging of the bundles can be managed as well, by using the following option:

  • org.amdatu.configurator.loglevel, takes a value of [0..4] denoting the log level to use in which a higher value
    means more verbosity of logging. So, a value of 0 means no logging, 1 to only show errors and so on
    to 4 which shows all messages. Currently, log messages are printed to the console (stdout).

Using AutoConf configurations

Amdatu Configurator only accepts AutoConf/MetaType configuration if the bundle attribute has the following format:
osgi-dp:my.bundle.symbolicname. The my.bundle.symbolicname should be a BSN of an existing bundle, and is used to bind the configuration to this particular bundle.

<Designate pid="designate" bundle="osgi-dp:my.bundle.symbolicname">
  <Object ocdref="ocd">
    <Attribute adref="server" name="serverurl" />
  </Object>
</Designate>

As a result, AutoConf/MetaType configurations can only be provisioned if there is only a single bundle with the requested symbolic
name. This means that provisioning configurations to multiple bundles with the same symbolic name but with different versions is not possible.

Variable/placeholder substitution

Though not allowed by the AutoConf specification, the Amdatu Configurator allows AutoConf resources to be parameterized
with variables (or placeholders) in order to make them a little more reusable for different deployment scenarios.
Variables are considered all strings that start with ${ and end with }. When an AutoConf resource is
processed by Amdatu Configurator, it will try to replace all variables with values found as framework properties. So,
for example, a variable ${context.serverUrl} will be replaced with the value of the framework property serverUrl
(the context. prefix is stripped off, see [configuration](#configuration)). If no framework property is found, no
substitution will take place.

Example

Consider the following AutoConf resource, named myConfig.xml, stored in a directory named config:

 <?xml version="1.0" encoding="UTF-8"?>
  <metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.1.0">
    <OCD id="ocd" name="ocd">
      <AD id="server" type="String" />
    </OCD>
    <Designate pid="org.amdatu.conf" bundle="osgi-dp:org.amdatu.sample.bundle">
      <Object ocdref="ocd">
        <Attribute adref="server" name="serverurl" content="${context.serverUrl}" />
      </Object>
    </Designate>
  </metatype:MetaData>

If we would start our OSGi application, for example, using a Bnd Run Descriptor with the following content:

-runbundles: \
  osgi.cmpn;version="[4.2,5)",\
  org.apache.felix.configadmin;version="[1.8,1.9)",\
  org.apache.felix.dependencymanager;version="[3.1,3.2)",\
  org.apache.felix.log;version="[1.0.1,1.0.2)",\
  org.amdatu.configurator.autoconf;version=latest
  # ...many more properties...
-runproperties: \
  serverUrl=http://my.server.host:8080/,\
  org.amdatu.configurator.autoconf.dir=/path/to/config

The Amdatu Configurator will provision a configuration with a single property of serverUrl=http://my.server.host:8080/ to ConfigAdmin.
The result will be that this property will be given to the ManagedService implementation registered with the org.amdatu.conf PID.

Invalid configurations

Please note that invalid configurations will be rejected by Amdatu Configurator.
This means that invalid configurations will not be deployed.
Configurator will do several validation checks to determine whether a configuration is valid or not. If it finds any problems with provided
configurations it will output it’s logging on a warning or information level, as opposed to problems related to Configurator itself, which will be logged on a debug level.

References

1 OSGi Configuration Admin command line client