Write Metadata XMLs

Writing XML description of a bundle's metatype information.

Each bundle can supply XML resource files with metatype information and specify these files in the bundle's manifest.

Let us try to explain the advantages of using XML description of a bundle's metatype information instead of programming interfaces:

An XML file can be read and parsed before bundle startup. A bundle resource can be changed when the bundle is still in INSTALLED state for example, and when the bundle starts, the resource can receive its new state immediately.
An XML file can be easily edited - it is not necessary to change programming code, recompile it and rebuild the bundle. XML resources take less place than a set of class files, holding the same information.

If the XML files are correct, the Metadata Manager will parse them and persistently store the metadata in the database of the DB Bundle. On request for particular metadata, the Metadata Manager will produce a Metatype Provider for the specified PID and populate the provider with serialized data from the database. When the bundle, providing the XML metadata is updated or removed, the Metadata Manager takes care to reflect the change in its storage.

Metadata XML DTD

A metadata XML should use the following Data Type Definition (DTD):

DTD Elements	Description
<!ELEMENT metatype-provider (objectclass, configobject*)>	Describes a Metatype Provider entry. The metatype-provider element consists of one or more objectclasses and zero or more configobjects.
ObjectClassDefinition	ObjectClassDefinition
<!ELEMENT objectclass (locale, name, id, description, icon, attribute, attribute-ref, objectclass*)>	objectclass contains information about an ObjectClassDefinition as defined in the OSGi Metatype Specification, part of the OSGi Service Platform Specification Release 3. It is obligatory to include in it "name", "id", "description" and at least one "attribute" element. The "icon" and "locale" elements are optional.
<!ATTLIST objectclass load CDATA #IMPLIED>	An attribute of the objectclass element. If it is set to true, the Metadata Manager will construct a configuration from the objectclass's data.
objectclass Elements	objectclass Elements
<!ELEMENT locale (#PCDATA)>	Obsolete. The locale the ObjectClassDefinition is designed for. It affects the language used in the descriptions and names. Currently, the locale element is NOT used - it is left unprocessed, and a warning is logged. We leave the description to meet the case of older metadata XML files.
<!ELEMENT name (#PCDATA)>	The name of the ObjectClassDefinition or AttributeDefinition, which is displayed by the administration applications.
<!ELEMENT id (#PCDATA)>	As termed in the OSGi Metatype Specification, this is the ID of the ObjectClassDefinition or AttributeDefinition.
<!ELEMENT description (#PCDATA)>	A short text, describing resource, again used in the administration applications.
<!ELEMENT icon (#PCDATA)>	Resource's icon, used in the administration applications. You can have more than one icon, or have no icon at all. The properties of this tag are explained below. The location of the icon may be a resource within the bundle JAR, or a user-defined URL.
<!ATTLIST icon size CDATA #REQUIRED>	Image resource taken from bundle's JAR file or an URL. Icon's size of 16 means 16x16 pixels. See this example: <icon size="16">/http16x16.ico</icon>
<!ELEMENT attribute (name?, id, description?, type, cardinality?, key*, value?, (selected-pairs)?)>	Metadata for an AttributeDefinition as defined in OSGi Metatype Specification. The symbols after an attribute define the number of attributes: "*" means 0 or more of this attribute "+" means 1 or more of this attribute "?" means 0 or 1 of this attribute the lack of any symbol means that only 1 attribute can be used
<!ATTLIST attribute modifier CDATA #REQUIRED load CDATA #IMPLIED>	The modifier attribute indicates if the AttributeDefinition is optional (if modifier's value is opt) or required (if modifier's value is req), and if it is used for input data (if modifier's value is in) or output data (if modifier's value is out). The load attribute defines if an optional attribute should be initially loaded or not. By default, the property is accepted as true.
<!ELEMENT cardinality (#PCDATA)>	The maximum size of an array or a vector. Positive value indicates that the attribute's value is an array, negative - that this is a vector, and 0 - that this is a single value attribute.
<!ELEMENT key EMPTY>	Additional attribute modifier. You can use zero or more keys, i.e. modifiers. See key's attributes explained below.
<!ATTLIST key name CDATA #REQUIRED value CDATA #REQUIRED>	Required name and value of the key element.
<!ELEMENT selected-pairs ((scalar, scalar)+)>	Values defined as a list of options to choose from. The first scalar is the option name and the second one - the value.
<!ELEMENT type (#PCDATA)>	This element specifies the type of the property. It must be one of the entity elements below.
The following elements show the possible types for a property	according to the specification
<!ENTITY int "int">	Specifies the type of an integer property.
<!ENTITY byte "byte">	Specifies the type of a byte property.
<!ENTITY boolean "boolean">	Specifies the type of a boolean property.
<!ENTITY string "string">	Specifies the type of a string property.
<!ENTITY long "long">	Specifies the type of a long property.
<!ENTITY short "short">	Specifies the type of a short property.
<!ENTITY char "char">	Specifies the type of a char property.
<!ENTITY double "double">	Specifies the type of a double property.
<!ENTITY float "float">	Specifies the type of a float property.
<!ENTITY dictionary "dictionary">	Specifies the type of a dictionary property.
<!ELEMENT value (scalar \| array\|(property+))>	The attribute's default value. Can be scalar - single value, array - an array or a vector depending on the specified attribute cardinality, or property - a dictionary.
<!ELEMENT array (scalar+)>	The set of scalars (single values) of an array or vector.
<!ELEMENT property (type, scalar?)>	The property of a dictionary. It contains the nested type and scalar elements, which respectively indicates the type and the value of the property.
<!ATTLIST property key CDATA #REQUIRED>	The property name.
<!ELEMENT scalar (#PCDATA)>	The default value of the property, or of the array or vector element. It must be of the same type, as indicated in the type tag.
<!ELEMENT attribute-ref EMPTY>	An attribute reference can be used in nested object classes to point to an attribute already defined into an ancestor object class.
<!ATTLIST attribute-ref refid IDREF #REQUIRED modifier CDATA #REQUIRED load CDATA #IMPLIED>	refid stands for the id of the ancestor's attribute being referenced. For the modifier and load attributes see the description of the attribute tag attributes.
Configuration Object Definition
<!ELEMENT configobject (id, (attribute*))>	configobject keeps data of a particular object class instance (a configuration object), generated using a parent "factory" ObjectClassDefinition. If nothing is defined in the configobject tag, it is assumed to have the same attributes and values as objectclass. New values for the required attributes may be defined and optional ones may be included or excluded depending on the values in the load flags. The id of the configobject should match the PID of the factory defined in the template ObjectClassDefinition. There should be as many configobjects as is the number of required initially-generated object class instances.
<!ELEMENT attribute (id, value?)>	An attribute inherited from the ObjectClassDefinition.
<!ATTLIST attribute modifier CDATA #REQUIRED load CDATA #IMPLIED>	See the description of the attribute tag attributes.

Metadata Manifest Header

A bundle should specify each of its metadata XMLs via a separate manifest header with the following syntax:

header := metadata-type ":" metatype-providers
metatype-providers := metatype-provider ("," metatype-provider)*
metatype-provider := "xml=" xml-resource-path ";pid=" service-pid ";name=" display-name ";version=" metadata-version

where:

metadata-type – Specifies the metadata type of the XML-based Metatype Provider (for example Config, FactoryConfig, Control-Unit, External-Config, etc.). The Metadata Manager determines supported metadata types (and hence manifest headers that it has to look for) through the "MetaData" registration property of the Metadata Plugin services registered in the framework.

Note: In case a configuration XML file is placed on an arbitrary external URL, use the External-Config or the External-FactoryConfig header to specify the provided metadata type.

xml-resource-path – Specifies the path to the XML file inside and outside the bundle JAR file. Beware that you use "/" as path separator.
service-pid – Specifies the ID of the Metatype Provider defined in XML format.
display-name – Specifies the user-friendly name of the ObjectClassDefinition defined in XML format.
metadata-version - Specifies the version of the ObjectClassDefinition defined in the XML format. The version value may be a string in major.minior.micro format, which is used to distinguish changes in the format of a given resource without the need for changing the metadata PID.