Describing configuration by 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 that contains your service, in the OSGI-INF/metatype directory, in accordance with the specification.

About this task

Providing metadata to describe your 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.

Procedure

Create an xml file in the OSGI-INF/metatype directory of your 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>
```
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 your code and the server.xml file.
```
<OCD name="b2c" description="bundle two config" id="b2c-id">
</OCD>

<Designate pid="testBundleTwo">
<Object ocdref="b2c-id" />
</Designate>
```
Add attribute definition (AD) elements for each configuration property, within the OCD. Each attribute needs an identifier which is also used in the server.xml file 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 your processing code. Specifying a useful default value allows the user-supplied configuration to be minimal, and contains all your configuration defaults in a known location:
```
<AD name="boolProperty" description="a boolean property" id="boolProp" 
    type="Boolean" default="false" />
```

Then you 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>

Code your service to receive the configuration properties. Without the metatype description, all your 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.