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.
-
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.
-
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.
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.
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.
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.
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 forObjectClassDefinition
. -
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.
-
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
andManagedServiceFactory
service objects can optionally implement theMetaTypeProvider
interface. The Meta Type Service will only search forManagedService
andManagedServiceFactory
service objects that implementMetaTypeProvider
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.
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());
}
}
}
}
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.
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.
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 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 8. |
|||
OCD |
Object Class Definition |
||||
name |
<> |
string |
A human readable name that can be localized. |
||
description |
A human readable description of the Object Class Definition that can be localized. |
||||
id |
<> |
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
|
||
factoryPid |
string |
If the |
|||
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 ( This is an optional attribute but can be mandatory in certain usage schemes, for example the Autoconf Resource Processor. |
|||
optional |
false |
boolean |
If |
||
merge |
false |
boolean |
If the PID refers to an existing configuration,
then merge the properties with the existing properties if this
attribute is |
||
AD |
Attribute Definition |
||||
name |
string |
A localizable name for the Attribute Definition.
|
|||
description |
string |
A localizable description for the Attribute Definition. |
|||
id |
The unique ID of the Attribute Definition. |
||||
type |
string |
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
|
|||
cardinality |
0 |
The number of elements an instance can take.
Positive numbers describe an array ( |
|||
min |
string |
A validation value. This value is not directly
available from the |
|||
max |
string |
A validation value. Similar to the |
|||
string |
The default value. A default is an array of
|
||||
required |
true |
boolean |
Required attribute. The |
||
Option |
One option label/value for the
options in an |
||||
label |
<> |
string |
The label |
||
value |
<> |
string |
The value |
||
Icon |
An icon definition. |
||||
resource |
<> |
string |
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 |
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 |
||
content |
string |
The content of the attributes. If this is an array,
the content must be separated by commas ( |
|||
Value |
Holds a single value. This element can be repeated multiple times under an Attribute |
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.
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
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>
<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>
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.
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();
}
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 thePREFIX_
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 thePREFIX_
field.
The generated id becomes the value of the id
attribute of the AD
element in the generated Meta Type
Resource XML document.
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>
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.
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.
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 theorg.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 theorg.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 theorg.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.
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)"
-
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.
An interface to describe an attribute.
An AttributeDefinition
object defines a description of the data type
of a property/attribute.
Thread-safe
The BIGDECIMAL
type.
Attributes of this type should be stored as BigDecimal
,
List<BigDecimal>
or BigDecimal[]
objects depending on
getCardinality().
As of 1.1.
The BIGINTEGER
type.
Attributes of this type should be stored as BigInteger
,
List<BigInteger>
or BigInteger[]
objects, depending on
the getCardinality() value.
As of 1.1.
The BOOLEAN
type.
Attributes of this type should be stored as Boolean
,
List<Boolean>
or boolean[]
objects depending on
getCardinality().
The BYTE
type.
Attributes of this type should be stored as Byte
,
List<Byte>
or byte[]
objects, depending on the
getCardinality() value.
The CHARACTER
type.
Attributes of this type should be stored as Character
,
List<Character>
or char[]
objects, depending on the
getCardinality() value.
The DOUBLE
type.
Attributes of this type should be stored as Double
,
List<Double>
or double[]
objects, depending on the
getCardinality() value.
The FLOAT
type.
Attributes of this type should be stored as Float
,
List<Float>
or float[]
objects, depending on the
getCardinality() value.
The INTEGER
type.
Attributes of this type should be stored as Integer
,
List<Integer>
or int[]
objects, depending on the
getCardinality() value.
The LONG
type.
Attributes of this type should be stored as Long
,
List<Long>
or long[]
objects, depending on the
getCardinality() value.
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.
1.2
The SHORT
type.
Attributes of this type should be stored as Short
,
List<Short>
or short[]
objects, depending on the
getCardinality() value.
The STRING
type.
Attributes of this type should be stored as String
,
List<String>
or String[]
objects, depending on the
getCardinality() value.
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
The cardinality of this attribute.
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.
Return a default value or null
if no default exists.
Return a description of this attribute. The description may be localized and must describe the semantics of this type and any constraints.
The localized description of the definition.
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.
The id or oid
Get the name of the attribute. This name may be localized.
The localized name of the definition.
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" }
.
A list values
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" }
.
A list values
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.
The type for this attribute.
The 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" ]
null
, "", or another string
A MetaType Information object is created by the MetaTypeService to return meta type information for a specific bundle.
1.1
Thread-safe
Consumers of this API must not implement this type
Return the bundle for which this object provides meta type information.
Bundle for which this object provides meta type information.
Return the Factory PIDs (for ManagedServiceFactories) for which ObjectClassDefinition information is available.
Array of Factory PIDs.
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.
Thread-safe
Service property to signal that this service has
ObjectClassDefinition objects for the given factory PIDs. The
type of this service property is String+
.
1.2
Service property to signal that this service has
ObjectClassDefinition objects for the given PIDs. The type of
this service property is String+
.
1.2
Return a list of available locales.
The results must be names that consists of language [ _ country [ _
variation ]] as is customary in the Locale
class.
An array of locale strings or null
if there is no locale
specific localization can be found.
The ID of the requested object class. This can be a pid or factory pid returned by getPids or getFactoryPids.
The 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.
A ObjectClassDefinition
object.
IllegalArgumentException
– If the id or locale arguments are not
valid
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.
1.1
Thread-safe
Consumers of this API must not implement this type
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)))"
1.3
Location of meta type documents. The MetaType Service will process each entry in the meta type documents directory.
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.
1.4
Description for the data type information of an objectclass.
Thread-safe
Argument for getAttributeDefinitions(int)
.
ALL
indicates that all the definitions are returned. The value is
-1.
Argument for getAttributeDefinitions(int)
.
OPTIONAL
indicates that only the optional definitions are
returned. The value is 2.
Argument for getAttributeDefinitions(int)
.
REQUIRED
indicates that only the required definitions are
returned. The value is 1.
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.
An array of attribute definitions or null
if no
attributes are selected
Return a description of this object class. The description may be localized.
The description of this object class.
Requested 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.
An InputStream representing an icon or null
IOException
– If the InputStream
cannot be returned.
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.
The id of this object class.
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.
-
AttributeDefinition
-AttributeDefinition
information for the annotated method. -
AttributeType
- Attribute types for the AttributeDefinition annotation. -
Designate
- Generate aDesignate
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.
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 thePREFIX_
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 thePREFIX_
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.
The AD element of a Meta Type Resource.
CLASS
METHOD
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.
The name attribute of the AD element of a Meta Type Resource.
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.
The description attribute of the AD element of a Meta Type Resource.
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.
The type attribute of the AD element of a Meta Type Resource.
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.
The cardinality attribute of the AD element of a Meta Type Resource.
The minimum value for this AttributeDefinition.
If not specified, there is no minimum value.
The min attribute of the AD element of a Meta Type Resource.
The maximum value for this AttributeDefinition.
If not specified, there is no maximum value.
The max attribute of the AD element of a Meta Type Resource.
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.
The default attribute of the AD element of a Meta Type Resource.
The required value for this AttributeDefinition.
If not specified, the value is true
.
The required attribute of the AD element of a Meta Type Resource.
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.
The Option element of a Meta Type Resource.
Attribute types for the AttributeDefinition annotation.
The String
type.
Attributes of this type should be stored as String
,
List<String>
or String[]
objects, depending on the
cardinality value.
The Long
type.
Attributes of this type should be stored as Long
,
List<Long>
or long[]
objects, depending on the
AttributeDefinition#cardinality() cardinality
value.
The Integer
type.
Attributes of this type should be stored as Integer
,
List<Integer>
or int[]
objects, depending on the
AttributeDefinition#cardinality() cardinality
value.
The Short
type.
Attributes of this type should be stored as Short
,
List<Short>
or short[]
objects, depending on the
AttributeDefinition#cardinality() cardinality
value.
The Character
type.
Attributes of this type should be stored as Character
,
List<Character>
or char[]
objects, depending on the
AttributeDefinition#cardinality() cardinality
value.
The Byte
type.
Attributes of this type should be stored as Byte
,
List<Byte>
or byte[]
objects, depending on the
AttributeDefinition#cardinality() cardinality
value.
The Double
type.
Attributes of this type should be stored as Double
,
List<Double>
or double[]
objects, depending on the
AttributeDefinition#cardinality() cardinality
value.
The Float
type.
Attributes of this type should be stored as Float
,
List<Float>
or float[]
objects, depending on the
AttributeDefinition#cardinality() cardinality
value.
The Boolean
type.
Attributes of this type should be stored as Boolean
,
List<Boolean>
or boolean[]
objects depending on
AttributeDefinition#cardinality() cardinality
.
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.
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.
The Designate element of a Meta Type Resource.
CLASS
TYPE
The type of the ObjectClassDefinition for this Designate.
The specified type must be annotated with ObjectClassDefinition.
The ocdref attribute of the Designate element of a Meta Type Resource.
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.
The pid and factoryPid attributes of the Designate element of a Meta Type Resource.
Icon
information for an ObjectClassDefinition.
CLASS
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.
The resource attribute of the Icon element of a Meta Type Resource.
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.
The OCD element of a Meta Type Resource.
CLASS
TYPE
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.
The id attribute of the OCD element of a Meta Type Resource.
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.
The name attribute of the OCD element of a Meta Type Resource.
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.
The description attribute of the OCD element of a Meta Type Resource.
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().
The localization attribute of the MetaData element of a Meta Type Resource.
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.
The pid attribute of the Designate element of a Meta Type Resource.
, Designate
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.
The factoryPid attribute of the Designate element of a Meta Type Resource.
, Designate
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.
The Icon element of a Meta Type Resource.
Option
information for an AttributeDefinition.
CLASS
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.
The label attribute of the Option element of a Meta Type Resource.
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.
1.4
CLASS
TYPE
, PACKAGE
[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