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.