Overview

The metadata model in control units is based on the OSGi Metatype Service.

Metadata Model

The metadata management model of the OSGi Metatype Service Specification is based on definitions of object classes and of their attributes. A collection of object classes and attributes associated with a common entity define a metatype for that entity. The structure of an object class is described in its ObjectClassDefinition, which consists of zero or more AttributeDefinitions for required and/or optional attributes. Metadata within a metatype is delivered by a Metatype Provider, which holds ObjectClassDefinitions, each identified by its Persistent IDentity (PID).

OSGi Metatype Providers

According to the OSGi Metatype Service Specification a Metatype Provider should implement the org.osgi.service.metatype.MetaTypeProvider interface. A MetaTypeProvider provides its locale-specific object class definitions as org.osgi.service.metatype.ObjectClassDefinition instances. On its behalf, an ObjectClassDefinition provides org.osgi.service.metatype.AttributeDefinition instances to represent the definitions of its attributes.

However, there are cases when the OSGi metatyping is not sufficient to describe specific metadata like for control units. Hence, an extension to the OSGi metatype model is introduced for resolving such issues.

Metatype Extension API

The Metatype Extension API, mainly in the org.mbs.services.metatype Java package, enables developers to define nested ObjectClassDefinitions as well as ObjectClassDefinition modifiers. The Metadata Extension API also introduces the use of XML files for convenient metatype definition.

The API contains components extending the OSGi Metatype Provider, ObjectClassDefinition and AttributeDefinition as well as provides some useful utilities for mapping metadata XML files to metatype objects.

Extended Metatype Interfaces

The next table describes the extension classes to the OSGi basic metatype elements with regard to the control unit abstraction.


Interface

Additional Functionality

MetypeProviderExtern

Defined to contain metadata of a specified type and version. As the MetatypeProviderExtern interface extends com.prosyst.util.io.Externalizable, it can be transmitted between RM backend servers through the RM RPC Service.

ObjectClassDefinitionEx

Defined to provide:

  • Nested ObjectClassDefinitions.

  • Means to search an attribute by its ID.

  • Means to filter input (the INPUT filter) and output (the OUTPUTfilter) attributes besides optional and required. This can be used to get input and output action arguments.

  • The super class definition of this ObjectClassDefinition (by using the SUPER filter).

ObjectClassDefinitionEx instances should be returned by the getObjectClassDefinition method of the corresponding MetaTypeProvider.

AttributeDefinitionEx

Defined to provide:

  • Dictionaries as attributes.

  • Attribute key/value modifiers.

  • More fine-grained constraints on allowed attribute values.

AttributeDefinitionEx instances should be supplied by the corresponding ObjectClassDefinition.

Metadata XMLs

Each Control Unit Provider can supply metadata via XML files with metatype information in a format instead of programming an implementation of a Metatype Provider. You can then, convert the metadata XML into a set of Java metatype objects by using some utilities like com.prosyst.mprm.util.metatype.MetaTypeProviderInfo (available in the System Package) or org.mbs.services.metatype.ObjectClassCreator.

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


DTD Elements

Description

<!ELEMENT metatype-provider (objectclass+)>

Describes a Metatype Provider entry. The metatype-provider element consists of one or more objectclasses.

ObjectClassDefinition


<!ELEMENT objectclass (locale*, name, id, description, icon*, attribute*, attribute-ref*, objectclass*)>

objectclass contains information about an ObjectClassDefinition as defined in the OSGi Metatype Specification, part of the OSGi Service Platform Specification. It is obligatory to include in it "name", "id", "description" and at least one "attribute" element. The "icon" and "locale" elements are optional.

objectclass Elements


<!ELEMENT locale (#PCDATA)>

The locale the ObjectClassDefinition is designed for. It affects the language used in the descriptions and names.


Currently, the locale element is NOT read.

<!ELEMENT name (#PCDATA)>

The name of the ObjectClassDefinition or AttributeDefinition, which is displayed by the administration applications.

<!ELEMENT id (#PCDATA)>

As termed in the OSGi Metatype Specification, this is the ID of the ObjectClassDefinition or AttributeDefinition.

<!ELEMENT description (#PCDATA)>

A short text, describing resource, again used in the administration applications.

<!ELEMENT icon (#PCDATA)>

Resource's icon, used in the administration applications. You can have more than one icon, or have no icon at all. The properties of this tag are explained below. The location of the icon may be a resource within the bundle JAR, or a user-defined URL.

<!ATTLIST icon size CDATA #REQUIRED>

Image resource taken from bundle's JAR file or an URL. Icon's size of 16 means 16x16 pixels. See this example: <icon size="16">/http16x16.ico</icon>

<!ELEMENT attribute (name?, id, description?, type, cardinality?, key*, value?, (selected-pairs)?)>

Metadata for an AttributeDefinition as defined in OSGi Metatype Specification. The symbols after an attribute define the number of attributes:

  • "*" means 0 or more of this attribute

  • "+" means 1 or more of this attribute

  • "?" means 1 of this attribute

  • the lack of any symbol means that only 1 attribute can be used

<!ATTLIST attribute modifier CDATA #REQUIRED>

Represents the purpose or the availability of the attribute. Predefined values are "req" or "opt" and "in" or "out".

  • When the attribute represents a state variable, that is the attribute tag is nested in the main objectclass tag, the modifier attribute should be equal to "req".

  • When the attribute represents an action argument, that is the attribute tag is nested in an action objectclass tag, the modifier attribute indicates if the relevant AttributeDefinition is used for input data (if modifier's value is "in") or output data (if modifier's value is "out").

<!ELEMENT cardinality (#PCDATA)>

The maximum size of an array or a vector. Positive value indicates that the attribute's value is an array, negative - that this is a vector, and 0 - that this is a single value attribute.

<!ELEMENT key EMPTY>

Additional attribute modifier. You can use zero or more keys, i.e. modifiers. See key's attributes explained below.

<!ATTLIST key name CDATA #REQUIRED value CDATA #REQUIRED>

Required name and value of the key element.

<!ELEMENT selected-pairs ((scalar, scalar)+)>

Values defined as a list of options to choose from. The first scalar is the option name and the second one - the value.

<!ELEMENT type (#PCDATA)>

This element specifies the type of the property. It must be one of the entity elements below.

The following elements show the possible types for a property, according to the specification


<!ENTITY int "int">

Specifies the type of an integer property.

<!ENTITY byte "byte">

Specifies the type of a byte property.

<!ENTITY boolean "boolean">

Specifies the type of a boolean property.

<!ENTITY string "string">

Specifies the type of a string property.

<!ENTITY long "long">

Specifies the type of a long property.

<!ENTITY short "short">

Specifies the type of a short property.

<!ENTITY char "char">

Specifies the type of a char property.

<!ENTITY double "double">

Specifies the type of a double property.

<!ENTITY float "float">

Specifies the type of a float property.

<!ENTITY dictionary "dictionary">

Specifies the type of a dictionary property.

<!ELEMENT value (scalar | array|(property+))>

The attribute's default value. Can be scalar - single value, array - an array or a vector depending on the specified attribute cardinality, or property - a dictionary.

<!ELEMENT array (scalar+)>

The set of scalars (single values) of an array or vector.

Definition of Object Class Inheritance

The Metadata Manager is capable of handling inheritance among not-nested object classes. It is the descendant's responsibility to indicate its superior by including in its ObjectClassDefinition the super attribute with value the ID of the super object class. As a result, the descendant inherits all attributes of the superior. If you want to exclude one or more ObjectClassDefinitions of a super object class you should insert the ObjectClassDefinition of these object class(s) in the metatype with ID !<ID_to_exclude>.

Control Unit Metatyping

This section describes the commons in the metadata of control unit interfaces (identified by control unit type).

The metatype of a control unit interface obeys the OSGi Metatype Specification (org.osgi.service.metatype) and its extension (org.mbs.services.metatype), described in the previous section.

The metatype of a control unit type is represented by an ObjectClassDefinitionEx instance, with the same ID (returned by the getID method) as the control unit type. The name, description and icon properties of an ObjectClassDefinitionEx might be used by management tools to provide user-friendly description of control units.

There are several attributes (returned by the getAttributeDefinitions method) with predefined keys, which must not be treated as definitions of the state variables. These special attributes are the following:

  • mbs.control.parent.type – The type of this attribute is String, the cardinality is Integer.MAX_VALUE (meaning that the actual type of the attribute is String[]), and its default value (returned by AttributeDefinition's getDefaultValue method) contains all types of control units that are parents of control units of the type represented by this ObjectClassDefinition.

  • super – The type of this attribute is String, the cardinality is 0, and its default value (returned by AttributeDefinition's getDefaultValue method) indicates the type of the "super" control unit. This means that control units of this type will inherit all state variables and actions of the "super" ObjectClassDefinition.

State Variable Metadata Definition

State variables are represented as AttributeDefinitionEx objects returned by the getAttributeDefinitions method of ObjectClassDefinition. Each state variable is mapped to one AttributeDefinitionEx as follows:

  • getID – Returns the identifier of the state variable.

  • getType and getCardinality – Form the type of the state variable.

  • getName, getDescription, getOptionalLabels and getOptionalValues – Provide user-friendly description of the state variable to management tools.

  • getProperties – Provides additional constraints over the allowed values of the state variable, such as minimum, maximum, etc.

Action Metadata Definition

Actions are represented as nested ObjectClassDefinitionEx objects available through the getObjectClassDefinitions method of the main ObjectClassDefinitionEx. Each action is represented by one ObjectClassDefinitionEx as follows:

  • getID – Returns the identifier of the action.

  • getAttributes(ObjectClassDefinitionEx.INPUT) and getAttributes(ObjectClassDefinitionEx.OUTPUT) – Return respectively the input and output arguments of the action. The returned AttributeDefinitionEx instances present the arguments in a manner similar to state variables (described above).

  • getName, getDescription, and getOptionalLabels and getOptionalValues – Provide user-friendly description of the actions to management tools.

Special Control Unit Actions

There are several actions with predefined semantics, which might be optionally supported by Control Unit Providers.

State Variable Setters

The Control Unit Provider of a particular CU type may support several actions with identifiers in the form $set.<state_var_id>, where <state_var_id> must be an identifier of a state variable supported by the control units of the type. Such actions must have one input argument of the same type as the type of the corresponding state variable, and must not have output arguments. Invoking such actions should change the value of the state variable with the supplied argument.

Control Unit Finders

The Control Unit Provider of a component CU type may optionally support one or more methods for filtering control units. These methods are called finders and are defined as actions with identifiers starting with "$find.". Every finder action can have different number and/or type of arguments.

Finders are not executed as regular actions (in the invokeAction method of the provider's com.prosyst.mprm.backend.ms.cu.spi.component.DeviceControlUnitFactory), but are implemented by method findControlUnits of DeviceControlUnitFactory (see Adding New Device and Component Types).

Control Unit Constructors

The Control Unit Provider of a particular CU type may optionally support one or more methods for explicit creation of control units. These methods are called constructors and are defined as actions with identifiers starting with "$create.". Every constructor action can have different number and/or type of arguments.

Constructors are not executed as regular actions (in the invokeAction method of com.prosyst.mprm.backend.ms.cu.spi.root.DeviceRootControlUnitProvider or com.prosyst.mprm.backend.ms.cu.spi.component.DeviceControlUnitFactory), but are implemented by method createControlUnit (see Adding New Device and Component Types).

Control Unit Destructors

The Control Unit Provider of a particular CU type may optionally support explicit removal of control units. This is indicated by defining an action with identifier $destroy without arguments, called destructor.

The destructor is not executed as regular actions (by in the invokeAction method of com.prosyst.mprm.backend.ms.cu.spi.root.DeviceRootControlUnitProvider or com.prosyst.mprm.backend.ms.cu.spi.component.DeviceControlUnitFactory), but is implemented by method destroyControlUnit (see Adding New Device and Component Types).

Supported Types

The following Java types are supported as values of state variables and arguments of actions:

  • Wrappers of primitive Java types – Integer, Long, Byte, Short, Double, Float, Character, Boolean

  • String

  • Array of primitive types, and array or Vector of the above types

  • Dictionary with keys of type String and values of type wrappers of primitive Java types or String

Control Unit Metadata Example

The next example CU metadata XML describes the structure of control units of type "my.device.cu". The metatype defines that control units of type "my.device.cu" will have state variables ID, name and "on", and actions "turnOn" and "turnOff".

The "my.device.cu" type provides a constructor "$create." for creating a "my.device.cu" control unit, taking as input arguments the ID, name and "on" state of the unit. There is also a destructor "$destroy" for explicitly destroying a control unit.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE metatype-provider SYSTEM "metatype.dtd">
<metatype-provider>
  <objectclass>
    <locale>en</locale>
    <name>My Device</name>
    <id>my.device.cu</id>
    <description/>
    <attribute modifier="req" load="true">
      <name>Device ID</name>
      <id>id</id>
      <description/>
      <type>&string;</type>
      <cardinality>0</cardinality>
    </attribute>
    <attribute modifier="req">
      <name>Device Display Name</name>
      <id>name</id>
      <description/>
      <type>&string;</type>
      <cardinality>0</cardinality>
    </attribute>
    <attribute modifier="req">
      <name>Switched State</name>
      <id>on</id>
      <description/>
      <type>&boolean;</type>
      <cardinality>0</cardinality>
    </attribute>
    <objectclass>
      <locale>en</locale>
      <name>Create My Device</name>
      <id>$create.</id>
      <description/>
      <attribute modifier="in">
        <name>On</name>
        <id>on</id>
        <description/>
        <type>&boolean;</type>
        <cardinality>0</cardinality>
        <value>
          <scalar>false</scalar>
        </value>
      </attribute>
      <attribute modifier="in">
        <name>ID</name>
        <id>id</id>
        <description/>
        <type>&string;</type>
        <cardinality>0</cardinality>
      </attribute>      <attribute modifier="in">
        <name>Name</name>
        <id>name</id>
        <description/>
        <type>&string;</type>
        <cardinality>0</cardinality>
      </attribute>    </objectclass>    <objectclass>
      <locale>en</locale>
      <name>Delete Device</name>
      <id>$destroy</id>
      <description/>
    </objectclass>    <objectclass>
      <locale>en</locale>
      <name>Turn ON</name>
      <id>turnOn</id>
      <description/>
    </objectclass>
    <objectclass>
      <locale>en</locale>
      <name>Turn OFF</name>
      <id>turnOff</id>
      <description/>
    </objectclass>
  </objectclass>
</metatype-provider>

References