Prev		Next

105 Metatype Service Specification

Version 1.4

105.1 Introduction

The Metatype specification defines interfaces that allow bundle developers to describe attribute types in a computer readable form using so-called metadata.

The purpose of this specification is to allow services to specify the type information of data that they can use as arguments. The data is based on attributes, which are key/value pairs like properties.

A designer in a type-safe language like Java is often confronted with the choice of using the language constructs to exchange data or using a technique based on attributes/properties that are based on key/value pairs. Attributes provide an escape from the rigid type-safety requirements of modern programming languages.

Type-safety works very well for software development environments in which multiple programmers work together on large applications or systems, but often lacks the flexibility needed to receive structured data from the outside world.

The attribute paradigm has several characteristics that make this approach suitable when data needs to be communicated between different entities which "speak" different languages. Attributes are uncomplicated, resilient to change, and allow the receiver to dynamically adapt to different types of data.

As an example, the OSGi framework Specifications define several attribute types which are used in a Framework implementation, but which are also used and referenced by other OSGi specifications such as the Configuration Admin Service Specification. A Configuration Admin service implementation deploys attributes (key/value pairs) as configuration properties.

The Meta Type Service provides a unified access point to the Meta Type information that is associated with bundles. This Meta Type information can be defined by an XML resource in a bundle (OSGI-INF/metatype directories must be scanned for any XML resources), it can come from the Meta Type Provider service, or it can be obtained from Managed Service or Managed Service Factory services.

105.1.1 Essentials

Conceptual model - The specification must have a conceptual model for how classes and attributes are organized.
Standards - The specification should be aligned with appropriate standards, and explained in situations where the specification is not aligned with, or cannot be mapped to, standards.
Remote Management - Remote management should be taken into account.
Size - Minimal overhead in size for a bundle using this specification is required.
Localization - It must be possible to use this specification with different languages at the same time. This ability allows servlets to serve information in the language selected in the browser.
Type information - The definition of an attribute should contain the name (if it is required), the cardinality, a label, a description, labels for enumerated values, and the Java class that should be used for the values.
Validation - It should be possible to validate the values of the attributes.

105.1.2 Entities

Meta Type Service - A service that provides a unified access point for meta type information.
Attribute - A key/value pair.
PID - A unique persistent ID, defined in configuration management.
Attribute Definition - Defines a description, name, help text, and type information of an attribute.
Object Class Definition - Defines the type of a datum. It contains a description and name of the type plus a set of AttributeDefinition objects.
Meta Type Provider - Provides access to the object classes that are available for this object. Access uses the PID and a locale to find the best ObjectClassDefinition object.
Meta Type Information - Provides meta type information for a bundle.

Figure 105.1 Class Diagram Meta Type Service, org.osgi.service.metatype

105.1.3 Operation

The Meta Type service defines a rich dynamic typing system for properties. The purpose of the type system is to allow reasonable User Interfaces to be constructed dynamically.

The type information is normally carried by the bundles themselves. Either by implementing the MetaTypeProvider interface on the Managed Service or Managed Service Factory, by carrying one or more XML resources that define a number of Meta Types in the OSGI-INF/metatype directories, or registering a Meta Type Provider as a service. Additionally, a Meta Type service could have other sources that are not defined in this specification.

The Meta Type Service provides unified access to Meta Types that are carried by the resident bundles. The Meta Type Service collects this information from the bundles and provides uniform access to it. A client can requests the Meta Type Information associated with a particular bundle. The MetaTypeInformation object provides a list of ObjectClassDefinition objects for a bundle. These objects define all the information for a specific object class. An object class is a some descriptive information and a set of named attributes (which are key/value pairs).

Access to Object Class Definitions is qualified by a locale and a Persistent IDentity (PID). This specification does not specify what the PID means. One application is OSGi Configuration Management where a PID is used by the Managed Service and Managed Service Factory services. In general, a PID should be regarded as the name of a variable where an Object Class Definition defines its type.

105.2 Attributes Model

The Framework uses the LDAP filter syntax for searching the Framework registry. The usage of the attributes in this specification and the Framework specification closely resemble the LDAP attribute model. Therefore, the names used in this specification have been aligned with LDAP. Consequently, the interfaces which are defined by this Specification are:

AttributeDefinition
ObjectClassDefinition
MetaTypeProvider

These names correspond to the LDAP attribute model. For further information on ASN.1-defined attributes and X.500 object classes and attributes, see [2] Understanding and Deploying LDAP Directory services.

The LDAP attribute model assumes a global name-space for attributes, and object classes consist of a number of attributes. So, if an object class inherits the same attribute from different parents, only one copy of the attribute must become part of the object class definition. This name-space implies that a given attribute, for example cn, should always be the common name and the type must always be a String. An attribute cn cannot be an Integer in another object class definition. In this respect, the OSGi approach towards attribute definitions is comparable with the LDAP attribute model.

105.3 Object Class Definition

The ObjectClassDefinition interface is used to group the attributes which are defined in AttributeDefinition objects.

An ObjectClassDefinition object contains the information about the overall set of attributes and has the following elements:

A name which can be returned in different locales.
A global name-space in the registry, which is the same condition as LDAP/X.500 object classes. In these standards the OSI Object Identifier (OID) is used to uniquely identify object classes. If such an OID exists, (which can be requested at several standard organizations, and many companies already have a node in the tree) it can be returned here. Otherwise, a unique id should be returned. This id can be a Java class name (reverse domain name) or can be generated with a GUID algorithm. All LDAP-defined object classes already have an associated OID. It is strongly advised to define the object classes from existing LDAP schemes which provide many preexisting OIDs. Many such schemes exist ranging from postal addresses to DHCP parameters.
A human-readable description of the class.
A list of attribute definitions which can be filtered as required, or optional. Note that in X.500 the mandatory or required status of an attribute is part of the object class definition and not of the attribute definition.
An icon, in different sizes.

105.4 Attribute Definition

The AttributeDefinition interface provides the means to describe the data type of attributes.

The AttributeDefinition interface defines the following elements:

Defined names (final ints) for the data types as restricted in the Framework for the attributes, called the syntax in OSI terms, which can be obtained with the getType() method.
AttributeDefinition objects should use an ID that is similar to the OID as described in the ID field for ObjectClassDefinition.
A localized name intended to be used in user interfaces.
A localized description that defines the semantics of the attribute and possible constraints, which should be usable for tooltips.
An indication if this attribute should be stored as a unique value, a List, or an array of values, as well as the maximum cardinality of the type.
The data type, as limited by the Framework service registry attribute types.
A validation function to verify if a possible value is correct.
A list of values and a list of localized labels. Intended for popup menus in GUIs, allowing the user to choose from a set.
A default value (String[]). The return depends on the following cases:
- not specified - Return null if this attribute is not specified.
- cardinality = 0 - Return an array with one element.
- otherwise - Return an array with less or equal than the absolute value of cardinality, possibly empty if the value is an empty string.

105.5 Meta Type Service

The Meta Type Service provides unified access to Meta Type information that is associated with a Bundle. It can get this information through the following means:

Meta Type Resource - A bundle can provide one or more XML resources that are contained in its JAR file. These resources contain an XML definition of meta types as well as to what PIDs these Meta Types apply. These XML resources must reside in the OSGI-INF/metatype directories of the bundle (including any fragments).
Managed Service [Factory] objects - As defined in the configuration management specification, ManagedService and ManagedServiceFactory service objects can optionally implement the MetaTypeProvider interface. The Meta Type Service will only search for ManagedService and ManagedServiceFactory service objects that implement MetaTypeProvider if no meta type resources are found in the bundle.
Meta Type Provider service - Bundles can register Meta Type Provider services to dynamically provide meta types for PIDs and factory PIDs.

Figure 105.2 Sources for Meta Types

This model is depicted in Figure 105.2.

The Meta Type Service can therefore be used to retrieve meta type information for bundles which contain Meta Type resources or which provide MetaTypeProvider objects and/or services. If multiple sources define the same Object Class Definition, the Meta Type service must select which source to use. Meta Type Provider services must take precedence over Managed Service [Factory] objects implementing MetaTypeProvider or Meta Type Resources.

The MetaTypeService interface has a single method:

getMetaTypeInformation(Bundle) - Given a bundle, it must return the Meta Type Information for that bundle, even if there is no meta type information available at the moment of the call.

The returned MetaTypeInformation object maintains a map of PID to ObjectClassDefinition objects. The map is keyed by locale and PID. The list of maintained PIDs is available from the MetaTypeInformation object with the following methods:

getPids() - PIDs for which Meta Types are available.
getFactoryPids() - PIDs associated with Managed Service Factory services.

These methods and their interaction with the Meta Type resource are described in Designate Element.

The MetaTypeInformation interface extends the MetaTypeProvider interface. The MetaTypeProvider interface is used to access meta type information. It supports locale dependent information so that the text used in AttributeDefinition and ObjectClassDefinition objects can be adapted to different locales.

Which locales are supported by the MetaTypeProvider object are defined by the implementer or the meta type resources. The list of available locales can be obtained from the MetaTypeProvider object.

The MetaTypeProvider interface provides the following methods:

getObjectClassDefinition(String,String) - Get access to an ObjectClassDefinition object for the given PID. The second parameter defines the locale.
getLocales() - List the locales that are available.

Locale objects are represented in String objects because not all profiles support Locale. The String holds the standard Locale presentation of:

locale = language ( '_' country ( '_' variation))
language ::= < defined by ISO 3166 >
country  ::= < defined by ISO 639 >

For example, en, nl_BE, en_CA_posix are valid locales. The use of null for locale indicates that java.util.Locale.getDefault() must be used.

The Meta Type Service implementation class is the main class. It registers the org.osgi.service.metatype.MetaTypeService service and has a method to get a MetaTypeInformation object for a bundle.

Following is some sample code demonstrating how to print out all the Object Class Definitions and Attribute Definitions contained in a bundle:

void printMetaTypes( MetaTypeService mts,Bundle b ) {
    MetaTypeInformation mti = 
        mts.getMetaTypeInformation(b);
    String [] pids = mti.getPids();
    String [] locales = mti.getLocales();

    for ( int locale = 0; locale<locales.length; locale++) {
        System.out.println("Locale " + locales[locale] );
        for (int i=0; i< pids.length; i++) {
            ObjectClassDefinition ocd = 
                mti.getObjectClassDefinition(pids[i], null);
            AttributeDefinition[] ads = 
                ocd.getAttributeDefinitions(
                    ObjectClassDefinition.ALL);
            for (int j=0; j< ads.length; j++) {
                System.out.println("OCD="+ocd.getName()
                    + "AD="+ads[j].getName());
            }
        }
    }
}

105.6 Meta Type Provider Service

A Meta Type Provider service allows third party contributions to the internal Object Class Definition repository. A Meta Type Provider can contribute multiple PIDs, both factory and singleton PIDs. A Meta Type Provider service must register with both or one of the following service properties:

METATYPE_PID - (String+) Provides a list of PIDs that this Meta Type Provider can provide Object Class Definitions for. The listed PIDs are intended to be used as normal singleton PIDs used by Managed Services.
METATYPE_FACTORY_PID - (String+) Provides a list of factory PIDs that this Meta Type Provider can provide Object Class Definitions for. The listed PIDs are intended to be used as factory PIDs used by Managed Service Factories.

The Object Class Definitions must originate from the bundle that registered the Meta Type Provider service. Third party extenders should therefore use the bundle of their extendee. A Meta Type Service must report these Object Class Definitions on the Meta Type Information of the registering bundle, merged with any other information from that bundle.

The Meta Type Service must track these Meta Type Provider services and make their Meta Types available as if they were provided on the Managed Service (Factory) services. The Meta Types must become unavailable when the Meta Type Provider service is unregistered.

105.7 Using the Meta Type Resources

A bundle that wants to provide meta type resources must place these resources in the OSGI-INF/metatype directory. The name of the resource must be a valid bundle entry path. All resources in that directory must be meta type documents. Resources in that directory that are not valid meta type documents must be ignored and an error should be logged with the Log Service, if present. Fragments can contain additional meta type resources in the same directory and they must be taken into account when the meta type resources are searched. A meta type resource must be encoded in UTF-8.

The MetaType Service must support localization of the

name
icon
description
label attributes

The localization mechanism must be identical using the same mechanism as described in the Core module layer, see Localization, using the same property resource. However, it is possible to override the property resource in the meta type definition resources with the localization attribute of the MetaData element.

The Meta Type Service must examine the bundle and its fragments to locate all localization resources for the localization base name. From that list, the Meta Type Service derives the list of locales which are available for the meta type information. This list can then be returned by MetaTypeInformation.getLocales method. This list can change at any time because the bundle could be refreshed. Clients should be prepared that this list changes after they received it.

105.7.1 XML Schema of a Meta Type Resource

This section describes the schema of the meta type resource. This schema is not intended to be used during runtime for validating meta type resources. The schema is intended to be used by tools and external management systems.

The XML namespace for meta type documents must be:

http://www.osgi.org/xmlns/metatype/v1.4.0

The namespace abbreviation should be metatype. That is, the following header should be:

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

The file can be found in the osgi.jar file that can be downloaded from the www.osgi.org web site.

Figure 105.3 XML Schema Instance Structure (Type name = Element name)

The element structure of the XML file is:

MetaData    ::= OCD* Designate*

OCD         ::= AD*  Icon*
AD          ::= Option*

Designate   ::= Object
Object      ::= Attribute*

Attribute   ::= Value*

The different elements are described in Table 105.1.

Table 105.1 XML Schema for Meta Type resources

	Attribute	Deflt	Type	Method	Description
`MetaData`					Top Element
	`localization`		`string`		Points to the Properties file that can localize this XML. See Localization in OSGi Core Release 7.
`OCD`					Object Class Definition
	`name`	`<>`	`string`	getName()	A human readable name that can be localized.
	`description`			getDescription()	A human readable description of the Object Class Definition that can be localized.
	`id`	`<>`		getID()	A unique id, cannot be localized.
`Designate`					An association between one PID and an Object Class Definition. This element designates a PID to be of a certain type.
	`pid`	`<>`	`string`		The PID that is associated with an `OCD`. This can be a reference to a factory or singleton configuration object. The PID can be a Targeted PID, if `factoryPid` is not set or empty. Either `pid` or `factoryPid` must be specified. See Designate Element.
	`factoryPid`		`string`		If the `factoryPid` attribute is set, this Designate element defines a factory configuration for the given factory. If it is not set or empty, it designates a singleton configuration. The PID can be a Targeted PID. Either `pid` or `factoryPid` must be specified. See Designate Element.
	`bundle`		`string`		The value is used to set the location of any configuration created using this Meta Type resource. This may contain a bundle location or a multi-location. In a Meta Type resource, using the wildcard value (`'*' \u002A`) indicates the bundle location of the bundle containing the resource must be used as the location. See Location Binding This is an optional attribute but can be mandatory in certain usage schemes, for example the Autoconf Resource Processor.
	`optional`	`false`	`boolean`		If `true`, then this Designate element is optional, errors during processing must be ignored.
	`merge`	`false`	`boolean`		If the PID refers to an existing configuration, then merge the properties with the existing properties if this attribute is `true`. Otherwise, replace the properties.
`AD`					Attribute Definition
	`name`		`string`	getName()	A localizable name for the Attribute Definition. `description`
	`description`		`string`	getDescription()	A localizable description for the Attribute Definition.
	`id`			getID()	The unique ID of the Attribute Definition.
	`type`		`string`	getType()	The type of an attribute is an enumeration of the different scalar types. The string is mapped to one of the constants on the AttributeDefinition interface. Valid values, which are defined in the `Scalar` type, are: `String ↔ STRING Long ↔ LONG Double ↔ DOUBLE Float ↔ FLOAT Integer ↔ INTEGER Byte ↔ BYTE Char ↔ CHARACTER Boolean ↔ BOOLEAN Short ↔ SHORT Password ↔ PASSWORD`
	`cardinality`	`0`		getCardinality()	The number of elements an instance can take. Positive numbers describe an array (`[]`) and negative numbers describe a `List` object.
	`min`		`string`	validate(String)	A validation value. This value is not directly available from the `AttributeDefinition` interface. However, the validate(String) method must verify this. The semantics of this field depend on the type of this Attribute Definition.
	`max`		`string`	validate(String)	A validation value. Similar to the `min` field. When `min` or `max` are numbers, attribute values with a numeric data type are valid if `min <= value <= max`. Attribute values with a string (or equivalent) data type are valid if `min <= value.length() <= max`.
	`default`		`string`	getDefaultValue()	The default value. A default is an array of `String` objects. The XML attribute must contain a comma delimited list. The default value is trimmed and escaped in the same way as described in the validate(String) method. The empty string is significant and must be seen as an empty `List` or array if specified as the default for an attribute with a cardinality that is not equal to zero. Default values must be valid or otherwise ignored.
	`required`	`true`	`boolean`		Required attribute. The `required` attribute indicates whether or not the attribute key must appear within the configuration dictionary to be valid.
`Option`					One option label/value for the options in an `AD`. Options are exclusive. The validate(String) method must verify that an attribute value matches one of the option values when present.
	`label`	`<>`	`string`	getOptionLabels()	The label
	`value`	`<>`	`string`	getOptionValues()	The value
`Icon`					An icon definition.
	`resource`	`<>`	`string`	getIcon(int)	The resource is a URL. The base URL is assumed to be the root of the bundle containing the XML file. That is, this URL can reference another resource in the bundle using a relative URL.
	`size`	`<>`	`string`	getIcon(int)	The number of pixels of the icon, maps to the size parameter of the getIcon(int) method.
`Object`					A definition of an instance.
	`ocdref`	`<>`	`string`		A reference to the id attribute of an OCD element. That is, this attribute defines the OCD type of this object.
`Attribute`					A value for an attribute of an object.
	`adref`	`<>`	`string`		A reference to the id of the `AD` in the `OCD` as referenced by the parent `Object`.
	`content`		`string`		The content of the attributes. If this is an array, the content must be separated by commas (`',' \u002C`). Commas must be escaped as described at the `default` attribute of the `AD` element.
`Value`					Holds a single value. This element can be repeated multiple times under an Attribute

105.7.2 Designate Element

For the MetaType Service, the Designate definition is used to declare the available PIDs and factory PIDs; the Attribute elements are never used by the MetaType service.

The getPids() method returns an array of PIDs that were specified in the pid attribute of the Object elements. The getFactoryPids() method returns an array of the factoryPid attributes. For factories, the related pid attribute is ignored because all instances of a factory must share the same meta type.

The following example shows a metatype reference to a singleton configuration and a factory configuration.

    <Designate pid="com.acme.designate.1">
        <Object ocdref="com.acme.designate"/>
    </Designate>
    <Designate factoryPid="com.acme.designate.factory"
        bundle="*">
        <Object ocdref="com.acme.designate"/>
    </Designate>

Other schemes can embed the Object element in the Designate element to define actual instances for the Configuration Admin service. In that case the pid attribute must be used together with the factoryPid attribute. However, in that case an aliasing model is required because the Configuration Admin service does not allow the creator to choose the Configuration object's PID.

105.7.3 Example Metadata File

This example defines a meta type file for a Person record, based on ISO attribute types. The ids that are used are derived from ISO attributes.

<?xml version="1.0" encoding="UTF-8"?>
<MetaData 
    xmlns="http://www.osgi.org/xmlns/metatype/v1.4.0" 
    localization="person">
  <OCD name="%person" id="2.5.6.6"
        description="%person record">
    <AD name="%sex" id="2.5.4.12" type="Integer">
       <Option label="%male" value="1"/>
       <Option label="%female" value="0"/>
    </AD>
    <AD name="%sn" id="2.5.4.4" type="String"/>
    <AD name="%cn" id="2.5.4.3" type="String"/>
    <AD name="%seeAlso" id="2.5.4.34" type="String"
        cardinality="8"
        default="http://www.google.com,http://www.yahoo.com"/>
    <AD name="%telNumber" id="2.5.4.20" type="String"/>
  </OCD>

  <Designate pid="com.acme.addressbook">
    <Object ocdref="2.5.6.6"/>
  </Designate>
</MetaData>

Translations for this file, as indicated by the localization attribute must be stored in the root directory (e.g. person_du_NL.properties). The default localization base name for the properties is OSGI-INF/l10n/bundle, but can be overridden by the manifest Bundle-Localization header and the localization attribute of the Meta Data element. The property files have the base name of person. The Dutch, French and English translations could look like:

person_du_NL.properties:

person=Persoon
person\ record=Persoons beschrijving
cn=Naam
sn=Voornaam
seeAlso=Zie ook
telNumber=Tel. Nummer
sex=Geslacht
male=Mannelijk
female=Vrouwelijk

person_fr.properties:

person=Personne
person\ record=Description de la personne
cn=Nom
sn=Surnom
seeAlso=Reference
telNumber=Tel.
sex=Sexe
male=Homme
female=Femme

person_en_US.properties:

person=Person
person\ record=Person Record
cn=Name
sn=Sur Name
seeAlso=See Also
telNumber=Tel.
sex=Sex
male=Male
female=Female

105.7.4 Object Element

The OCD element can be used to describe the possible contents of a Dictionary object. In this case, the attribute name is the key. The Object element can be used to assign a value to a Dictionary object.

For example:

<Designate pid="com.acme.b">
  <Object ocdref="b">
    <Attribute adref="foo" content="Zaphod Beeblebrox"/>
    <Attribute adref="bar">
      <Value>1</Value>
      <Value>2</Value>
      <Value>3</Value>
      <Value>4</Value>
      <Value>5</Value>
    </Attribute>
  </Object>
</Designate>

105.8 Meta Type Resource XML Schema

<schema xmlns="http://www.w3.org/2001/XMLSchema"
    xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.4.0"
    targetNamespace="http://www.osgi.org/xmlns/metatype/v1.4.0"
    version="1.4.0">

    <element name="MetaData" type="metatype:Tmetadata" />

    <complexType name="Tmetadata">
        <choice minOccurs="0" maxOccurs="unbounded">
            <element name="OCD" type="metatype:Tocd" />
            <element name="Designate" type="metatype:Tdesignate" />
            <!-- It is non-deterministic, per W3C XML Schema 1.0: http://www.w3.org/TR/xmlschema-1/#cos-nonambig
                to use namespace="##any" below. -->
            <any namespace="##other" processContents="lax" />
        </choice>
        <attribute name="localization" type="string" use="optional" />
        <anyAttribute processContents="lax" />
    </complexType>

    <complexType name="Tocd">
        <choice minOccurs="0" maxOccurs="unbounded">
            <element name="AD" type="metatype:Tad" />
            <element name="Icon" type="metatype:Ticon" />
            <!-- It is non-deterministic, per W3C XML Schema 1.0: http://www.w3.org/TR/xmlschema-1/#cos-nonambig
                to use namespace="##any" below. -->
            <any namespace="##other" processContents="lax" />
        </choice>
        <attribute name="name" type="string" use="required" />
        <attribute name="description" type="string" use="optional" />
        <attribute name="id" type="string" use="required" />
        <anyAttribute processContents="lax" />
    </complexType>

    <complexType name="Tad">
        <choice minOccurs="0" maxOccurs="unbounded">
            <element name="Option" type="metatype:Toption" />
            <!-- It is non-deterministic, per W3C XML Schema 1.0: http://www.w3.org/TR/xmlschema-1/#cos-nonambig
                to use namespace="##any" below. -->
            <any namespace="##other" processContents="lax"  />
        </choice>
        <attribute name="name" type="string" use="optional" />
        <attribute name="description" type="string" use="optional" />
        <attribute name="id" type="string" use="required" />
        <attribute name="type" type="metatype:Tscalar" use="required" />
        <attribute name="cardinality" type="int" use="optional"
            default="0" />
        <attribute name="min" type="string" use="optional" />
        <attribute name="max" type="string" use="optional" />
        <attribute name="default" type="string" use="optional" />
        <attribute name="required" type="boolean" use="optional"
            default="true" />
        <anyAttribute processContents="lax" />
    </complexType>

    <complexType name="Tobject">
        <choice minOccurs="0" maxOccurs="unbounded">
            <element name="Attribute" type="metatype:Tattribute" />
            <!-- It is non-deterministic, per W3C XML Schema 1.0: http://www.w3.org/TR/xmlschema-1/#cos-nonambig
                to use namespace="##any" below. -->
            <any namespace="##other" processContents="lax" />
        </choice>
        <attribute name="ocdref" type="string" use="required" />
        <anyAttribute processContents="lax" />
    </complexType>

    <complexType name="Tattribute">
        <choice minOccurs="0" maxOccurs="unbounded">
            <element name="Value" type="string" />
            <!-- It is non-deterministic, per W3C XML Schema 1.0: http://www.w3.org/TR/xmlschema-1/#cos-nonambig
                to use namespace="##any" below. -->
            <any namespace="##other" processContents="lax" />
        </choice>
        <attribute name="adref" type="string" use="required" />
        <attribute name="content" type="string" use="optional" />
        <anyAttribute processContents="lax" />
    </complexType>

    <complexType name="Tdesignate">
        <sequence>
            <element name="Object" type="metatype:Tobject" minOccurs="1"
                maxOccurs="1" />
            <any namespace="##any" processContents="lax" minOccurs="0"
                maxOccurs="unbounded" />
        </sequence>
        <attribute name="pid" type="string" use="optional" />
        <attribute name="factoryPid" type="string" use="optional" />
        <attribute name="bundle" type="string" use="optional" />
        <attribute name="optional" type="boolean" default="false"
            use="optional" />
        <attribute name="merge" type="boolean" default="false"
            use="optional" />
        <anyAttribute processContents="lax" />
    </complexType>

    <simpleType name="Tscalar">
        <restriction base="string">
            <enumeration value="String" />
            <enumeration value="Long" />
            <enumeration value="Double" />
            <enumeration value="Float" />
            <enumeration value="Integer" />
            <enumeration value="Byte" />
            <enumeration value="Character" />
            <enumeration value="Boolean" />
            <enumeration value="Short" />
            <enumeration value="Password" />
        </restriction>
    </simpleType>

    <complexType name="Toption">
        <sequence>
            <any namespace="##any" processContents="lax" minOccurs="0"
                maxOccurs="unbounded" />
        </sequence>
        <attribute name="label" type="string" use="required" />
        <attribute name="value" type="string" use="required" />
        <anyAttribute processContents="lax" />
    </complexType>

    <complexType name="Ticon">
        <sequence>
            <any namespace="##any" processContents="lax" minOccurs="0"
                maxOccurs="unbounded" />
        </sequence>
        <attribute name="resource" type="string" use="required" />
        <attribute name="size" type="positiveInteger" use="required" />
        <anyAttribute processContents="lax" />
    </complexType>

    <attribute name="must-understand" type="boolean">
        <annotation>
            <documentation xml:lang="en">
                This attribute should be used by extensions to documents
                to require that the document consumer understand the
                extension.
            </documentation>
        </annotation>
    </attribute>
</schema>

105.9 Meta Type Annotations

A developer can use Meta Type Annotations on a Component Property Type, see Component Property Types, or an interface to define an Object Class Definition in a type safe manner. The Meta Type Annotations are CLASS retention annotations intended to be used during build time to generate Meta Type Resources from the Java class files providing a convenient way to create the Meta Type Resource XML documents.

Tools processing these annotations must always generate valid Meta Type Resource XML documents. If the Meta Type Annotations are used in a way that is not supported or in error, then the tool must report the error to enable the developer to take corrective action.

105.9.1 ObjectClassDefinition Annotation

The ObjectClassDefinition annotation can be applied to a Component Property Type or an interface. From that type, tooling can generate an OCD element. When applied to an interface, all the methods inherited from supertypes are include as Attribute Definitions. The tool processing the annotations must be able to examine all the types in the hierarchy of the annotated type to generate the Meta Type Resource. It is an error if the tool cannot examine a type in the hierarchy.

It is an error to apply the ObjectClassDefinition annotation to concrete and abstract class types. It is also an error to apply it to an interface if any of the methods of the interface take arguments.

The ObjectClassDefinition annotation can be applied without defining any element values as default values for the ObjectClassDefinition annotation elements can be generated from the annotated type. For example:

@ObjectClassDefinition
@interface Config {
  boolean enabled();
  String[] names();
  String topic();
}

In the following larger example, the ObjectClassDefinition annotation defines the description and name of the OCD which are to be localized using the specified resource as well as an icon resource. Also, AttributeDefinition annotations are applied to the methods to supply some non-default values for the generated AD elements.

@ObjectClassDefinition(localization = "OSGI-INF/l10n/member",
    description = "%member.description",
    name = "%member.name"
    icon = @Icon(resource = "icon/member-32.png", size = 32))
@interface Member {
  @AttributeDefinition(type = AttributeType.PASSWORD,
    description = "%member.password.description",
    name = "%member.password.name")
  public String _password();

  @AttributeDefinition(options = {
    @Option(label = "%strategic", value = "strategic"),
    @Option(label = "%principal", value = "principal"),
    @Option(label = "%contributing", value = "contributing")
    },
    defaultValue = "contributing",
    description = "%member.membertype.description",
    name = "%member.membertype.name")
  public String type();
}

105.9.2 AttributeDefinition Annotation

The AttributeDefinition annotation is an optional annotation which can applied to the methods in a type annotated by ObjectClassDefinition. Each method of the type annotated by ObjectClassDefinition is mapped to an AD child element of the OCD element in the generated Meta Type Resource XML document. The AttributeDefinition annotation only needs to be applied to a method if values other than the defaults are desired.

The id of the Attribute Definition is generated from the method name as follows:

A single dollar sign ('$' \u0024) is removed unless it is followed by:
- A low line ('_' \u005F) and a dollar sign in which case the three consecutive characters ("$_$") are converted to a single hyphen-minus ('-' \u002D).
- Another dollar sign in which case the two consecutive dollar signs ("$$") are converted to a single dollar sign.
A single low line ('_' \u005F) is converted into a full stop ('.' \u002E) unless is it followed by another low line in which case the two consecutive low lines ("__") are converted to a single low line.
All other characters are unchanged.
If the type declaring the method also declares a PREFIX_ field whose value is a compile-time constant String, then the id is prefixed with the value of the PREFIX_ field.

However, if the type annotated by ObjectClassDefinition is a single-element annotation, see 9.7.3 in [3] The Java Language Specification, Java SE 8 Edition, then the id for the value method is derived from the name of the annotation type rather than the name of the method. In this case, the simple name of the annotation type, that is, the name of the class without any package name or outer class name, if the annotation type is an inner class, must be converted to the value method's id as follows:

When a lower case character is followed by an upper case character, a full stop ('.' \u002E) is inserted between them.
Each upper case character is converted to lower case.
All other characters are unchanged.
If the annotation type declares a PREFIX_ field whose value is a compile-time constant String, then the id is prefixed with the value of the PREFIX_ field.

The generated id becomes the value of the id attribute of the AD element in the generated Meta Type Resource XML document.

105.9.3 Designate Annotation

The Designate annotation can be applied to a Declarative Services component class to make the connection between the pid of the component and an Object Class Definition. This annotation must be used on a type that is also annotated with the Declarative Services Component annotation. The component must only have a single PID which is used for the generated Designate element.

In the following example, the Designate annotation is applied to a Declarative Services component and references the Object Class Definition type.

@ObjectClassDefinition(id="my.config.ocd")
@interface Config {
  boolean enabled() default true;
  String[] names() default {"a", "b"};
  String topic() default "default/topic";
}

@Component(configurationPid="my.component.pid")
@Designate(ocd = Config.class)
public class MyComponent {
    static final String DEFAULT_TOPIC_PREFIX = "topic.prefix";
    protected void activate(Config configuration) {
        String t = configuration.topic();
    }
}

Tools processing these annotations will generate a Designate element in the generated Meta Type Resource XML document using the PID of the component and the id of the Object Class Definition. For example:

<Designate pid="my.component.pid">
    <Object ocdref="my.config.ocd"/>
</Designate>

105.10 Limitations

The OSGi MetaType specification is intended to be used for simple applications. It does not, therefore, support recursive data types, mixed types in arrays/lists, or nested arrays/lists.

105.11 Related Standards

One of the primary goals of this specification is to make metatype information available at run-time with minimal overhead. Many related standards are applicable to metatypes; except for Java beans, however, all other metatype standards are based on document formats (e.g. XML). In the OSGi framework, document format standards are deemed unsuitable due to the overhead required in the execution environment (they require a parser during run-time).

Another consideration is the applicability of these standards. Most of these standards were developed for management systems on platforms where resources are not necessarily a concern. In this case, a metatype standard is normally used to describe the data structures needed to control some other computer via a network. This other computer, however, does not require the metatype information as it is implementing this information.

In some traditional cases, a management system uses the metatype information to control objects in an OSGi framework. Therefore, the concepts and the syntax of the metatype information must be mappable to these popular standards. Clearly, then, these standards must be able to describe objects in an OSGi framework. This ability is usually not a problem, because the metatype languages used by current management systems are very powerful.

105.12 Capabilities

Implementations of the Metatype Service specification must provide the following capabilities.

A capability in the osgi.implementation namespace declaring a specification implementation with the name METATYPE_CAPABILITY_NAME. This capability must also declare a uses constraint for the org.osgi.service.metatype package. For example:
```
Provide-Capability: osgi.implementation;
    osgi.implementation="osgi.metatype";
    version:Version="1.4";
    uses:="org.osgi.service.metatype"
```
The RequireMetaTypeImplementation annotation can be used to require this capability.

This capability must follow the rules defined for the osgi.implementation Namespace.
A capability in the osgi.extender namespace declaring an extender with the name METATYPE_CAPABILITY_NAME. This capability must also declare a uses constraint for the org.osgi.service.metatype package. For example:
```
Provide-Capability: osgi.extender;
    osgi.extender="osgi.metatype";
    version:Version="1.4";
    uses:="org.osgi.service.metatype"
```
The RequireMetaTypeExtender annotation can be used to require this capability.

This capability must follow the rules defined for the osgi.extender Namespace.
A capability in the osgi.service namespace representing the MetaTypeService service. This capability must also declare a uses constraint for the org.osgi.service.metatype package. For example:
```
Provide-Capability: osgi.service;
    objectClass:List<String>="org.osgi.service.metatype.MetaTypeService";
    uses:="org.osgi.service.metatype"
```
This capability must follow the rules defined for the osgi.service Namespace.

105.13 Security Considerations

Special security issues are not applicable for this specification.

105.14 org.osgi.service.metatype

Version 1.4

Metatype Package Version 1.4.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.metatype; version="[1.4,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.metatype; version="[1.4,1.5)"

105.14.1 Summary

AttributeDefinition - An interface to describe an attribute.
MetaTypeInformation - A MetaType Information object is created by the MetaTypeService to return meta type information for a specific bundle.
MetaTypeProvider - Provides access to metatypes.
MetaTypeService - The MetaType Service can be used to obtain meta type information for a bundle.
ObjectClassDefinition - Description for the data type information of an objectclass.

105.14.2 public interface AttributeDefinition

An interface to describe an attribute.

An AttributeDefinition object defines a description of the data type of a property/attribute.

ConcurrencyThread-safe

105.14.2.1 public static final int BIGDECIMAL = 10

The BIGDECIMAL type. Attributes of this type should be stored as BigDecimal, List<BigDecimal> or BigDecimal[] objects depending on getCardinality().

DeprecatedAs of 1.1.

105.14.2.2 public static final int BIGINTEGER = 9

The BIGINTEGER type. Attributes of this type should be stored as BigInteger, List<BigInteger> or BigInteger[] objects, depending on the getCardinality() value.

DeprecatedAs of 1.1.

105.14.2.3 public static final int BOOLEAN = 11

The BOOLEAN type. Attributes of this type should be stored as Boolean, List<Boolean> or boolean[] objects depending on getCardinality().

105.14.2.4 public static final int BYTE = 6

The BYTE type. Attributes of this type should be stored as Byte, List<Byte> or byte[] objects, depending on the getCardinality() value.

105.14.2.5 public static final int CHARACTER = 5

The CHARACTER type. Attributes of this type should be stored as Character, List<Character> or char[] objects, depending on the getCardinality() value.

105.14.2.6 public static final int DOUBLE = 7

The DOUBLE type. Attributes of this type should be stored as Double, List<Double> or double[] objects, depending on the getCardinality() value.

105.14.2.7 public static final int FLOAT = 8

The FLOAT type. Attributes of this type should be stored as Float, List<Float> or float[] objects, depending on the getCardinality() value.

105.14.2.8 public static final int INTEGER = 3

The INTEGER type. Attributes of this type should be stored as Integer, List<Integer> or int[] objects, depending on the getCardinality() value.

105.14.2.9 public static final int LONG = 2

The LONG type. Attributes of this type should be stored as Long, List<Long> or long[] objects, depending on the getCardinality() value.

105.14.2.10 public static final int PASSWORD = 12

The PASSWORD type. Attributes of this type must be stored as String, List<String> or String[] objects depending on getCardinality(). A PASSWORD must be treated as a string but the type can be used to disguise the information when displayed to a user to prevent others from seeing it.

Since1.2

105.14.2.11 public static final int SHORT = 4

The SHORT type. Attributes of this type should be stored as Short, List<Short> or short[] objects, depending on the getCardinality() value.

105.14.2.12 public static final int STRING = 1

The STRING type.

Attributes of this type should be stored as String, List<String> or String[] objects, depending on the getCardinality() value.

105.14.2.13 public int getCardinality()

□ Return the cardinality of this attribute. The OSGi environment handles multi valued attributes in arrays ([]) or in List objects. The return value is defined as follows:

 
    x = Integer.MIN_VALUE    no limit, but use List
    x < 0                    -x = max occurrences, store in List
    x > 0                     x = max occurrences, store in array []
    x = Integer.MAX_VALUE    no limit, but use array []
    x = 0                     1 occurrence required

ReturnsThe cardinality of this attribute.

105.14.2.14 public String[] getDefaultValue()

□ Return a default for this attribute. The object must be of the appropriate type as defined by the cardinality and getType(). The return type is a list of String objects that can be converted to the appropriate type. The cardinality of the return array must follow the absolute cardinality of this type. For example, if the cardinality = 0, the array must contain 1 element. If the cardinality is 1, it must contain 0 or 1 elements. If it is -5, it must contain from 0 to max 5 elements. Note that the special case of a 0 cardinality, meaning a single value, does not allow arrays or lists of 0 elements.

ReturnsReturn a default value or null if no default exists.

105.14.2.15 public String getDescription()

□ Return a description of this attribute. The description may be localized and must describe the semantics of this type and any constraints.

ReturnsThe localized description of the definition.

105.14.2.16 public String getID()

□ Unique identity for this attribute. Attributes share a global namespace in the registry. For example, an attribute cn or commonName must always be a String and the semantics are always a name of some object. They share this aspect with LDAP/X.500 attributes. In these standards the OSI Object Identifier (OID) is used to uniquely identify an attribute. If such an OID exists, (which can be requested at several standard organizations and many companies already have a node in the tree) it can be returned here. Otherwise, a unique id should be returned which can be a Java class name (reverse domain name) or generated with a GUID algorithm. Note that all LDAP defined attributes already have an OID. It is strongly advised to define the attributes from existing LDAP schemes which will give the OID. Many such schemes exist ranging from postal addresses to DHCP parameters.

ReturnsThe id or oid

105.14.2.17 public String getName()

□ Get the name of the attribute. This name may be localized.

ReturnsThe localized name of the definition.

105.14.2.18 public String[] getOptionLabels()

□ Return a list of labels of option values.

The purpose of this method is to allow menus with localized labels. It is associated with getOptionValues. The labels returned here are ordered in the same way as the values in that method.

If the function returns null, there are no option labels available.

This list must be in the same sequence as the getOptionValues() method. That is, for each index i in getOptionLabels, i in getOptionValues() should be the associated value.

For example, if an attribute can have the value male, female, unknown, this list can return (for dutch) new String[] { "Man", "Vrouw", "Onbekend" }.

ReturnsA list values

105.14.2.19 public String[] getOptionValues()

□ Return a list of option values that this attribute can take.

If the function returns null, there are no option values available.

Each value must be acceptable to validate() (return "") and must be a String object that can be converted to the data type defined by getType() for this attribute.

This list must be in the same sequence as getOptionLabels(). That is, for each index i in getOptionValues, i in getOptionLabels() should be the label.

For example, if an attribute can have the value male, female, unknown, this list can return new String[] { "male", "female", "unknown" }.

ReturnsA list values

105.14.2.20 public int getType()

□ Return the type for this attribute.

Defined in the following constants which map to the appropriate Java type. STRING,LONG,INTEGER, SHORT, CHARACTER, BYTE,DOUBLE,FLOAT, BOOLEAN, PASSWORD.

ReturnsThe type for this attribute.

105.14.2.21 public String validate(String value)

valueThe value before turning it into the basic data type. If the cardinality indicates a multi-valued attribute then the given string must be escaped.

□ Validate an attribute in String form. An attribute might be further constrained in value. This method will attempt to validate the attribute according to these constraints. It can return three different values:

  null           No validation present
  ""             No problems detected
  "..."          A localized description of why the value is wrong

If the cardinality of this attribute is multi-valued then this string must be interpreted as a comma delimited string. The complete value must be trimmed from white space as well as spaces around commas. Commas ( ',' \u002C) and spaces (' ' \u0020) and backslashes ('\' \u005C) can be escaped with another backslash. Escaped spaces must not be trimmed. For example:

 value="  a\,b,b\,c,\ c\\,d   " => [ "a,b", "b,c", " c\", "d" ]

Returns null, "", or another string

105.14.3 public interface MetaTypeInformation
extends MetaTypeProvider

A MetaType Information object is created by the MetaTypeService to return meta type information for a specific bundle.

Since1.1

ConcurrencyThread-safe

Provider TypeConsumers of this API must not implement this type

105.14.3.1 public Bundle getBundle()

□ Return the bundle for which this object provides meta type information.

ReturnsBundle for which this object provides meta type information.

105.14.3.2 public String[] getFactoryPids()

□ Return the Factory PIDs (for ManagedServiceFactories) for which ObjectClassDefinition information is available.

ReturnsArray of Factory PIDs.

105.14.3.3 public String[] getPids()

□ Return the PIDs (for ManagedServices) for which ObjectClassDefinition information is available.

ReturnsArray of PIDs.

105.14.4 public interface MetaTypeProvider

Provides access to metatypes. This interface can be implemented on a Managed Service or Managed Service Factory as well as registered as a service. When registered as a service, it must be registered with a METATYPE_FACTORY_PID or METATYPE_PID service property (or both). Any PID mentioned in either of these factories must be a valid argument to the getObjectClassDefinition(String, String) method.

ConcurrencyThread-safe

105.14.4.1 public static final String METATYPE_FACTORY_PID = "metatype.factory.pid"

Service property to signal that this service has ObjectClassDefinition objects for the given factory PIDs. The type of this service property is String+.

Since1.2

105.14.4.2 public static final String METATYPE_PID = "metatype.pid"

Service property to signal that this service has ObjectClassDefinition objects for the given PIDs. The type of this service property is String+.

Since1.2

105.14.4.3 public String[] getLocales()

□ Return a list of available locales. The results must be names that consists of language [ _ country [ _ variation ]] as is customary in the Locale class.

ReturnsAn array of locale strings or null if there is no locale specific localization can be found.

105.14.4.4 public ObjectClassDefinition getObjectClassDefinition(String id, String locale)

idThe ID of the requested object class. This can be a pid or factory pid returned by getPids or getFactoryPids.

localeThe locale of the definition or null for default locale.

□ Returns an object class definition for the specified id localized to the specified locale.

The locale parameter must be a name that consists of language[ "_" country[ "_" variation] ] as is customary in the Locale class. This Locale class is not used because certain profiles do not contain it.

ReturnsA ObjectClassDefinition object.

Throws IllegalArgumentException– If the id or locale arguments are not valid

105.14.5 public interface MetaTypeService

The MetaType Service can be used to obtain meta type information for a bundle. The MetaType Service will examine the specified bundle for meta type documents to create the returned MetaTypeInformation object.

If the specified bundle does not contain any meta type documents, then a MetaTypeInformation object will be returned that wrappers any ManagedService or ManagedServiceFactory services registered by the specified bundle that implement MetaTypeProvider. Thus the MetaType Service can be used to retrieve meta type information for bundles which contain a meta type documents or which provide their own MetaTypeProvider objects.

Since1.1

ConcurrencyThread-safe

Provider TypeConsumers of this API must not implement this type

105.14.5.1 public static final String METATYPE_CAPABILITY_NAME = "osgi.metatype"

Capability name for meta type document processors.

Used in Provide-Capability and Require-Capability manifest headers with the osgi.extender namespace. For example:

 Require-Capability: osgi.extender;
  filter:="(&(osgi.extender=osgi.metatype)(version>=1.4)(!(version>=2.0)))"

Since1.3

105.14.5.2 public static final String METATYPE_DOCUMENTS_LOCATION = "OSGI-INF/metatype"

Location of meta type documents. The MetaType Service will process each entry in the meta type documents directory.

105.14.5.3 public static final String METATYPE_SPECIFICATION_VERSION = "1.4.0"

Compile time constant for the Specification Version of MetaType Service.

Used in Version and Requirement annotations. The value of this compile time constant will change when the specification version of MetaType Service is updated.

Since1.4

105.14.5.4 public MetaTypeInformation getMetaTypeInformation(Bundle bundle)

bundleThe bundle for which meta type information is requested.

□ Return the MetaType information for the specified bundle.

ReturnsA MetaTypeInformation object for the specified bundle.

105.14.6 public interface ObjectClassDefinition

Description for the data type information of an objectclass.

ConcurrencyThread-safe

105.14.6.1 public static final int ALL = -1

Argument for getAttributeDefinitions(int).

ALL indicates that all the definitions are returned. The value is -1.

105.14.6.2 public static final int OPTIONAL = 2

Argument for getAttributeDefinitions(int).

OPTIONAL indicates that only the optional definitions are returned. The value is 2.

105.14.6.3 public static final int REQUIRED = 1

Argument for getAttributeDefinitions(int).

REQUIRED indicates that only the required definitions are returned. The value is 1.

105.14.6.4 public AttributeDefinition[] getAttributeDefinitions(int filter)

filter ALL,REQUIRED,OPTIONAL

□ Return the attribute definitions for this object class.

Return a set of attributes. The filter parameter can distinguish between ALL,REQUIRED or the OPTIONAL attributes.

ReturnsAn array of attribute definitions or null if no attributes are selected

105.14.6.5 public String getDescription()

□ Return a description of this object class. The description may be localized.

ReturnsThe description of this object class.

105.14.6.6 public InputStream getIcon(int size) throws IOException

sizeRequested size of an icon. For example, a 16x16 pixel icon has a size of 16

□ Return an InputStream object that can be used to create an icon from.

Indicate the size and return an InputStream object containing an icon. The returned icon maybe larger or smaller than the indicated size.

The icon may depend on the localization.

ReturnsAn InputStream representing an icon or null

Throws IOException– If the InputStream cannot be returned.

105.14.6.7 public String getID()

□ Return the id of this object class.

ObjectDefintion objects share a global namespace in the registry. They share this aspect with LDAP/X.500 attributes. In these standards the OSI Object Identifier (OID) is used to uniquely identify object classes. If such an OID exists, (which can be requested at several standard organizations and many companies already have a node in the tree) it can be returned here. Otherwise, a unique id should be returned which can be a Java class name (reverse domain name) or generated with a GUID algorithm. Note that all LDAP defined object classes already have an OID associated. It is strongly advised to define the object classes from existing LDAP schemes which will give the OID for free. Many such schemes exist ranging from postal addresses to DHCP parameters.

ReturnsThe id of this object class.

105.14.6.8 public String getName()

□ Return the name of this object class. The name may be localized.

ReturnsThe name of this object class.

105.15 org.osgi.service.metatype.annotations

Version 1.4

Metatype Annotations Package Version 1.4.

This package is not used at runtime. Annotated classes are processed by tools to generate Meta Type Resources which are used at runtime.

105.15.1 Summary

AttributeDefinition - AttributeDefinition information for the annotated method.
AttributeType - Attribute types for the AttributeDefinition annotation.
Designate - Generate a Designate element in the Meta Type Resource for an ObjectClassDefinition using the annotated Declarative Services component.
Icon - Icon information for an ObjectClassDefinition.
ObjectClassDefinition - Generate a Meta Type Resource using the annotated type.
Option - Option information for an AttributeDefinition.
RequireMetaTypeExtender - This annotation can be used to require the Meta Type extender to process metatype resources.
RequireMetaTypeImplementation - This annotation can be used to require the Meta Type implementation.

105.15.2 @AttributeDefinition

AttributeDefinition information for the annotated method.

Each method of a type annotated by ObjectClassDefinition has an implied AttributeDefinition annotation. This annotation is only used to specify non-default AttributeDefinition information.

The id of this AttributeDefinition is generated from the name of the annotated method as follows:

A single dollar sign ('$' \u0024) is removed unless it is followed by:
- A low line ('_' \u005F) and a dollar sign in which case the three consecutive characters ( "$_$") are changed to a single hyphen-minus ('-' \u002D).
- Another dollar sign in which case the two consecutive dollar signs ( "$$") are changed to a single dollar sign.
A low line ('_' \u005F) is changed to a full stop ( '.' \u002E) unless is it followed by another low line in which case the two consecutive low lines ("__") are changed to a single low line.
All other characters are unchanged.
If the type declaring the method also declares a PREFIX_ field whose value is a compile-time constant String, then the id is prefixed with the value of the PREFIX_ field.

However, if the type annotated by ObjectClassDefinition is a single-element annotation, then the id for the value method is derived from the name of the annotation type rather than the name of the method. In this case, the simple name of the annotation type, that is, the name of the class without any package name or outer class name, if the annotation type is an inner class, must be converted to the value method's id as follows:

When a lower case character is followed by an upper case character, a full stop ('.' \u002E) is inserted between them.
Each upper case character is converted to lower case.
All other characters are unchanged.
If the annotation type declares a PREFIX_ field whose value is a compile-time constant String, then the id is prefixed with the value of the PREFIX_ field.

This id is the value of the id attribute of the generate AD element and is used as the name of the corresponding configuration property.

This annotation is not processed at runtime. It must be processed by tools and used to contribute to a Meta Type Resource document for the bundle.

See Also The AD element of a Meta Type Resource.

Retention CLASS

Target METHOD

105.15.2.1 String name default ""

□ The human readable name of this AttributeDefinition.

If not specified, the name of this AttributeDefinition is derived from the name of the annotated method. For example, low line ('_' \u005F), dollar sign ('$' \u0024), and hyphen-minus ('-' \u002D) are replaced with space (' ' \u0020) and space is inserted between camel case words.

If the name begins with the percent sign ('%' \u0025), the name can be localized.

See Also The name attribute of the AD element of a Meta Type Resource.

105.15.2.2 String description default ""

□ The human readable description of this AttributeDefinition.

If not specified, the description of this AttributeDefinition is the empty string.

If the description begins with the percent sign ('%' \u0025), the description can be localized.

See Also The description attribute of the AD element of a Meta Type Resource.

105.15.2.3 AttributeType type default STRING

□ The type of this AttributeDefinition.

This must be one of the defined attributes types.

If not specified, the type is derived from the return type of the annotated method. Return types of Class and Enum are mapped to STRING. If the return type is List, Set, Collection, Iterable or some type which can be determined at annotation processing time to

be a subtype of Collection and
have a public no argument constructor,

then the type is derived from the generic type. For example, a return type of List<String> will be mapped to STRING. A return type of a single dimensional array is supported and the type is the component type of the array. Multi dimensional arrays are not supported. Annotation return types are not supported. Any unrecognized type is mapped to STRING. A tool processing the annotation should declare an error for unsupported return types.

See Also The type attribute of the AD element of a Meta Type Resource.

105.15.2.4 int cardinality default 0

□ The cardinality of this AttributeDefinition.

If not specified, the cardinality is derived from the return type of the annotated method. For an array return type, the cardinality is a large positive value. If the return type is List, Set, Collection, Iterable or some type which can be determined at annotation processing time to

be a subtype of Collection and
have a public no argument constructor,

the cardinality is a large negative value. Otherwise, the cardinality is 0.

See Also The cardinality attribute of the AD element of a Meta Type Resource.

105.15.2.5 String min default ""

□ The minimum value for this AttributeDefinition.

If not specified, there is no minimum value.

See Also The min attribute of the AD element of a Meta Type Resource.

105.15.2.6 String max default ""

□ The maximum value for this AttributeDefinition.

If not specified, there is no maximum value.

See Also The max attribute of the AD element of a Meta Type Resource.

105.15.2.7 String[] defaultValue default {}

□ The default value for this AttributeDefinition.

The specified values are concatenated into a comma delimited list to become the value of the default attribute of the generated AD element.

If not specified and the annotated method is an annotation element that has a default value, then the value of this element is the default value of the annotated element. Otherwise, there is no default value.

See Also The default attribute of the AD element of a Meta Type Resource.

105.15.2.8 boolean required default true

□ The required value for this AttributeDefinition.

If not specified, the value is true.

See Also The required attribute of the AD element of a Meta Type Resource.

105.15.2.9 Option[] options default {}

□ The option information for this AttributeDefinition.

For each specified Option, an Option element is generated for this AttributeDefinition.

If not specified, the option information is derived from the return type of the annotated method. If the return type is an enum, a single dimensional array of an enum, or a List, Set, Collection, Iterable or some type which can be determined at annotation processing time to

be a subtype of Collection and
have a public no argument constructor,

with a generic type of an enum, then the value of this element has an Option for each value of the enum. The label and value of each Option are set to the name of the corresponding enum value. Otherwise, no Option elements will be generated.

See Also The Option element of a Meta Type Resource.

105.15.3 enum AttributeType

Attribute types for the AttributeDefinition annotation.

105.15.3.1 STRING

The String type.

Attributes of this type should be stored as String, List<String> or String[] objects, depending on the cardinality value.

105.15.3.2 LONG

The Long type.

Attributes of this type should be stored as Long, List<Long> or long[] objects, depending on the AttributeDefinition#cardinality() cardinality value.

105.15.3.3 INTEGER

The Integer type.

Attributes of this type should be stored as Integer, List<Integer> or int[] objects, depending on the AttributeDefinition#cardinality() cardinality value.

105.15.3.4 SHORT

The Short type.

Attributes of this type should be stored as Short, List<Short> or short[] objects, depending on the AttributeDefinition#cardinality() cardinality value.

105.15.3.5 CHARACTER

The Character type.

Attributes of this type should be stored as Character, List<Character> or char[] objects, depending on the AttributeDefinition#cardinality() cardinality value.

105.15.3.6 BYTE

The Byte type.

Attributes of this type should be stored as Byte, List<Byte> or byte[] objects, depending on the AttributeDefinition#cardinality() cardinality value.

105.15.3.7 DOUBLE

The Double type.

Attributes of this type should be stored as Double, List<Double> or double[] objects, depending on the AttributeDefinition#cardinality() cardinality value.

105.15.3.8 FLOAT

The Float type.

Attributes of this type should be stored as Float, List<Float> or float[] objects, depending on the AttributeDefinition#cardinality() cardinality value.

105.15.3.9 BOOLEAN

The Boolean type.

Attributes of this type should be stored as Boolean, List<Boolean> or boolean[] objects depending on AttributeDefinition#cardinality() cardinality.

105.15.3.10 PASSWORD

The Password type.

Attributes of this type must be stored as String, List<String> or String[] objects depending on cardinality.

A Password must be treated as a String but the type can be used to disguise the information when displayed to a user to prevent it from being seen.

105.15.3.11 public String toString()

105.15.3.12 public static AttributeType valueOf(String name)

105.15.3.13 public static AttributeType[] values()

105.15.4 @Designate

Generate a Designate element in the Meta Type Resource for an ObjectClassDefinition using the annotated Declarative Services component.

This annotation must be used on a type that is also annotated with the Declarative Services Component annotation. The component must only have a single PID which is used for the generated Designate element.

This annotation is not processed at runtime. It must be processed by tools and used to contribute to a Meta Type Resource document for the bundle.

See Also The Designate element of a Meta Type Resource.

Retention CLASS

Target TYPE

105.15.4.1 Class<?> ocd

□ The type of the ObjectClassDefinition for this Designate.

The specified type must be annotated with ObjectClassDefinition.

See Also The ocdref attribute of the Designate element of a Meta Type Resource.

105.15.4.2 boolean factory default false

□ Specifies whether this Designate is for a factory PID.

If false, then the PID value from the annotated component will be used in the pid attribute of the generated Designate element. If true, then the PID value from the annotated component will be used in the factoryPid attribute of the generated Designate element.

See Also The pid and factoryPid attributes of the Designate element of a Meta Type Resource.

105.15.5 @Icon

Icon information for an ObjectClassDefinition.

105.15.5.1 String resource

□ The resource name for this Icon.

The resource is a URL. The resource URL can be relative to the root of the bundle containing the Meta Type Resource.

If the resource begins with the percent sign ('%' \u0025), the resource can be localized.

See Also The resource attribute of the Icon element of a Meta Type Resource.

105.15.5.2 int size

□ The pixel size of this Icon.

For example, 32 represents a 32x32 icon.

See Also The size attribute of the Icon element of a Meta Type Resource.

105.15.6 @ObjectClassDefinition

Generate a Meta Type Resource using the annotated type.

This annotation can be used without defining any element values since defaults can be generated from the annotated type. Each method of the annotated type has an implied AttributeDefinition annotation if not explicitly annotated.

This annotation may only be used on annotation types and interface types. Use on concrete or abstract class types is unsupported. If applied to an interface then all methods inherited from super types are included as attributes.

This annotation is not processed at runtime. It must be processed by tools and used to generate a Meta Type Resource document for the bundle.

See Also The OCD element of a Meta Type Resource.

Retention CLASS

Target TYPE

105.15.6.1 String id default ""

□ The id of this ObjectClassDefinition.

If not specified, the id of this ObjectClassDefinition is the fully qualified name of the annotated type using the dollar sign ('$' \u0024) to separate nested class names from the name of their enclosing class. The id is not to be confused with a PID which can be specified by the pid() or factoryPid() element.

See Also The id attribute of the OCD element of a Meta Type Resource.

105.15.6.2 String name default ""

□ The human readable name of this ObjectClassDefinition.

If not specified, the name of this ObjectClassDefinition is derived from the id(). For example, low line ('_' \u005F) and dollar sign ('$' \u0024) are replaced with space (' ' \u0020) and space is inserted between camel case words.

If the name begins with the percent sign ('%' \u0025), the name can be localized.

See Also The name attribute of the OCD element of a Meta Type Resource.

105.15.6.3 String description default ""

□ The human readable description of this ObjectClassDefinition.

If not specified, the description of this ObjectClassDefinition is the empty string.

If the description begins with the percent sign ('%' \u0025), the description can be localized.

See Also The description attribute of the OCD element of a Meta Type Resource.

105.15.6.4 String localization default ""

□ The localization resource of this ObjectClassDefinition.

This refers to a resource property entry in the bundle that can be augmented with locale information. If not specified, the localization resource for this ObjectClassDefinition is the string "OSGI-INF/l10n/" followed by the id().

See Also The localization attribute of the MetaData element of a Meta Type Resource.

105.15.6.5 String[] pid default {}

□ The PIDs associated with this ObjectClassDefinition.

For each specified PID, a Designate element with a pid attribute is generated that references this ObjectClassDefinition.

The Designate annotation can also be used to associate a Declarative Services component with an ObjectClassDefinition and generate a Designate element.

A special string ("$") can be used to specify the fully qualified name of the annotated type as a PID. For example:

 @ObjectClassDefinition(pid="$")

Tools creating a Meta Type Resource from this annotation must replace the special string with the fully qualified name of the annotated type.

See Also The pid attribute of the Designate element of a Meta Type Resource., Designate

105.15.6.6 String[] factoryPid default {}

□ The factory PIDs associated with this ObjectClassDefinition.

For each specified factory PID, a Designate element with a factoryPid attribute is generated that references this ObjectClassDefinition.

The Designate annotation can also be used to associate a Declarative Services component with an ObjectClassDefinition and generate a Designate element.

A special string ("$") can be used to specify the fully qualified name of the annotated type as a factory PID. For example:

 @ObjectClassDefinition(factoryPid="$")

Tools creating a Meta Type Resource from this annotation must replace the special string with the fully qualified name of the annotated type.

See Also The factoryPid attribute of the Designate element of a Meta Type Resource., Designate

105.15.6.7 Icon[] icon default {}

□ The icon resources associated with this ObjectClassDefinition.

For each specified Icon, an Icon element is generated for this ObjectClassDefinition. If not specified, no Icon elements will be generated.

See Also The Icon element of a Meta Type Resource.

105.15.7 @Option

Option information for an AttributeDefinition.

105.15.7.1 String label default ""

□ The human readable label of this Option.

If not specified, the label of this Option is the empty string.

If the label begins with the percent sign ('%' \u0025), the label can be localized.

See Also The label attribute of the Option element of a Meta Type Resource.

105.15.7.2 String value

□ The value of this Option.

See Also The value attribute of the Option element of a Meta Type Resource.

105.15.8 @RequireMetaTypeExtender

This annotation can be used to require the Meta Type extender to process metatype resources. It can be used directly, or as a meta-annotation.

Since1.4

Retention CLASS

Target TYPE, PACKAGE

105.15.9 @RequireMetaTypeImplementation

This annotation can be used to require the Meta Type implementation. It can be used directly, or as a meta-annotation.

Since1.4

Retention CLASS

Target TYPE, PACKAGE

105.16 References

[1]LDAP.http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol

[2]Understanding and Deploying LDAP Directory servicesTimothy Howes, et al. ISBN 1-57870-070-1, MacMillan Technical publishing.

[3]The Java Language Specification, Java SE 8 Editionhttps://docs.oracle.com/javase/specs/jls/se8/html/index.html

105.17 Changes

AttributeDefinition Annotation is updated to add support for mapping to hyphen-minus in component property names, to add special handling for the mapping of the value method in component property types which are single-element annotations, and to add support for PREFIX_.
The special value "$" can be used in the pid and factoryPid elements of the ObjectClassDefinition annotation. Tools must replace "$" with the fully qualified name of the type annotated by the ObjectClassDefinition annotation.
The RequireMetaTypeExtender and RequireMetaTypeImplementation annotations were added.

Prev		Next
	Home

OSGi Enterprise Release 7

105 Metatype Service Specification

105.1 Introduction

105.1.1 Essentials

105.1.2 Entities

105.1.3 Operation

105.2 Attributes Model

105.3 Object Class Definition

105.4 Attribute Definition

105.5 Meta Type Service

105.6 Meta Type Provider Service

105.7 Using the Meta Type Resources

105.7.1 XML Schema of a Meta Type Resource

105.7.2 Designate Element

105.7.3 Example Metadata File

105.7.4 Object Element

105.8 Meta Type Resource XML Schema

105.9 Meta Type Annotations

105.9.1 ObjectClassDefinition Annotation

105.9.2 AttributeDefinition Annotation

105.9.3 Designate Annotation

105.10 Limitations

105.11 Related Standards

105.12 Capabilities

105.13 Security Considerations

105.14 org.osgi.service.metatype

105.14.1 Summary

105.14.2 public interface AttributeDefinition

105.14.2.1 public static final int BIGDECIMAL = 10

105.14.2.2 public static final int BIGINTEGER = 9

105.14.2.3 public static final int BOOLEAN = 11

105.14.2.4 public static final int BYTE = 6

105.14.2.5 public static final int CHARACTER = 5

105.14.2.6 public static final int DOUBLE = 7

105.14.2.7 public static final int FLOAT = 8

105.14.2.8 public static final int INTEGER = 3

105.14.2.9 public static final int LONG = 2

105.14.2.10 public static final int PASSWORD = 12

105.14.2.11 public static final int SHORT = 4

105.14.2.12 public static final int STRING = 1

105.14.2.13 public int getCardinality()

105.14.2.14 public String[] getDefaultValue()

105.14.2.15 public String getDescription()

105.14.2.16 public String getID()

105.14.2.17 public String getName()

105.14.2.18 public String[] getOptionLabels()

105.14.2.19 public String[] getOptionValues()

105.14.2.20 public int getType()

105.14.2.21 public String validate(String value)

105.14.3 public interface MetaTypeInformation extends MetaTypeProvider

105.14.3.1 public Bundle getBundle()

105.14.3.2 public String[] getFactoryPids()

105.14.3.3 public String[] getPids()

105.14.4 public interface MetaTypeProvider

105.14.4.1 public static final String METATYPE_FACTORY_PID = "metatype.factory.pid"

105.14.4.2 public static final String METATYPE_PID = "metatype.pid"

105.14.4.3 public String[] getLocales()

105.14.4.4 public ObjectClassDefinition getObjectClassDefinition(String id, String locale)

105.14.5 public interface MetaTypeService

105.14.5.1 public static final String METATYPE_CAPABILITY_NAME = "osgi.metatype"

105.14.5.2 public static final String METATYPE_DOCUMENTS_LOCATION = "OSGI-INF/metatype"

105.14.5.3 public static final String METATYPE_SPECIFICATION_VERSION = "1.4.0"

105.14.5.4 public MetaTypeInformation getMetaTypeInformation(Bundle bundle)

105.14.6 public interface ObjectClassDefinition

105.14.6.1 public static final int ALL = -1

105.14.6.2 public static final int OPTIONAL = 2

105.14.6.3 public static final int REQUIRED = 1

105.14.6.4 public AttributeDefinition[] getAttributeDefinitions(int filter)

105.14.6.5 public String getDescription()

105.14.6.6 public InputStream getIcon(int size) throws IOException

105.14.6.7 public String getID()

105.14.6.8 public String getName()

105.15 org.osgi.service.metatype.annotations

105.15.1 Summary

105.15.2 @AttributeDefinition

105.15.2.1 String name default ""

105.15.2.2 String description default ""

105.15.2.3 AttributeType type default STRING

105.15.2.4 int cardinality default 0

105.15.2.5 String min default ""

105.14.3 public interface MetaTypeInformation
extends MetaTypeProvider