Describing configuration using the OSGi Metatype service

The configuration properties for each service can be described in metadata that complies with the OSGi Metatype Service specification. The metadata can include default values, translatable names and descriptions, and information to allow validation of input values. The resulting XML file is packaged into the bundle in the OSGI-INF/metatype directory, in accordance with the specification.

Provide metadata to describe the configuration is optional, but it does provide the following benefits:

• default values can be separated from the implementation code into the metatype XML file where they are easy to locate;

• appropriate data types and other validation data can be specified for each attribute, allowing validation by the configuration parser and developer tools, and simplifying the code you write to process the attributes;

• your configuration will be included in the XML schema that describes the available configuration to the developer tools and other utilities;

• translatable names and descriptions can be provided for each attribute, and will be displayed in the developer tools.

1. Create an xml file in the OSGI-INF/metatype directory of the bundle and add a namespace declaration for the OSGi Metatype namespaces:.

   <metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.1.0">
   </metatype:MetaData>

2. Add an object class definition (OCD) element to contain the set of attributes, with an identifier and, optionally, a name and description. Also provide a Designate element to map the OCD to the PID used in the code and server.xml.

   <OCD name="b2c" description="bundle two config" id="b2c-id">
   </OCD>
   
   <Designate pid="testBundleTwo">
   <Object ocdref="b2c-id" />
   </Designate>

3. Add attribute definition (AD) elements for each configuration property, within the OCD. Each attribute needs an identifier which is also used in server.xml and in the code that receives the injected configuration. It can optionally have a name and description which can be used by the developer tools and other graphical tools. Specifying a data type allows the runtime environment to validate the input for that type and simplifies the processing code. Specifying a useful default value allows the user-supplied configuration to be minimal, and contains all the configuration defaults in a known location:

   <AD name="boolProperty" description="a boolean property" id="boolProp" 
       type="Boolean" default="false" />

4. Then we have the following metatype.xml file.

   <?xml version="1.0" encoding="UTF-8"?>
   <metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.1.0" >
   
    <OCD name="b2c" description="bundle two config" id="testBundleTwo-2-id">
     <AD name="textProperty" description="a text property"
                 id="textProp" type="String" default="default string" />
     <AD name="boolProperty" description="a boolean property"
                 id="boolProp" type="Boolean" default="false" />
     <AD name="intProperty" description="an integer property"
                 id="intProp" type="Integer" default="14" /> 
    </OCD>
   
    <Designate pid="testBundleTwo-2">
     <Object ocdref="testBundleTwo-2-id" />
    </Designate>
   
   </metatype:MetaData>

5. Code the service to receive the configuration properties. Without the metatype description, all the properties will be provided as String values and will be processed as follows:

   String textProp = (String) properties.get("textProp");
   Boolean boolProp = Boolean.parseBoolean((String) properties.get("boolProp"));
   int intProp = Integer.parseInt((String) properties.get("intProp"));
   
   String textProp = (String) properties.get("textProp");
   Boolean boolProp = (Boolean) properties.get("boolProp");
   int intProp = (Integer) properties.get("intProp");

   And the runtime environment will already have validated that the input values are of the correct types.

What to do next

Provide translated strings for configuration property labels and descriptions.

Parent topic: Advanced Configuration

Concepts:

Server configuration

Product extension

Reference:
OSGi Service Platform Release 4 Version 4.2 Enterprise Specification