Introduction

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.

How to use

Configurator 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 OSGi Configuration Admin command line client.

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.

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. If no framework property is found, no substitution will take place.

Example

Consider the following AutoConf resource, named myConfig.xml, stored in the conf directory

myConfig.xml
<?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: \
  org.apache.felix.configadmin,\
  org.apache.felix.dependencymanager,\
  org.apache.felix.dependencymanager.runtime,\
  org.apache.felix.metatype,\
  org.ops4j.pax.logging.pax-logging-api,\
  org.ops4j.pax.logging.pax-logging-service,\
  org.amdatu.configurator.autoconf,\
  org.amdatu.sample.bundle
  # ...many more bundles...

-runproperties: \
  serverUrl=http://my.server.host:8080/

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.

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 onto _4 which shows all messages. Currently, log messages are printed to the console (stdout).

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)

yes

Used to configure the services which are going to be tested

OSGi LogService (e.g. Apache Felix LogService)

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.

Resources

Tools

Location

Source Code

https://bitbucket.org/amdatu/amdatu-configurator

Issue Tracking

https://amdatu.atlassian.net/browse/AMDATUCONF

Continuous Build

https://bitbucket.org/amdatu/amdatu-configurator/addon/pipelines/home