|
Knopflerfish OSGi 1.3.3 | |||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
PIDProvider | Interface which allows a service to provide sets of service and factory PID (Persistant ID) strings. |
Class Summary | |
AD | Implementation calss for AttributeDefinition. |
Loader | Helper class which loads (and saves) KF Metatype XML. |
Main | Main class for testing metatype XML files |
MTP | Implementation of the MetaTypeProvider interface. |
OCD | Implementation of the ObjectClassDefinition interface. |
SystemMetatypeProvider | Class which monitors installed bundles for metatype and CM default data. |
The OSGi specification defines a Configuration Manager, CM, capable
of storing configuration data for installed bundles. Such configuration data
is sent to the bundle using instances of java.lang.Dictionary
,
containing name/value pairs. The CM specification itself does not mandate
any specific means of initializing, storing or specifying such data. This
is left to the implementation.
OSGi also specifies a set of Metatype interfaces, which allows an OSGi bundle to provide metatype to configurations used by CM. Such metatype contains
The types supported by the Metatype API is limited to primitive types as string, int, long, short, float, double, char and boolean, plus vectors and arrays of primitive
types. Vectors and arrays only differ in their run-time format, java.lang.Vector
respective java arrays of primitive types.
XML Schemas (http://www.w3.org/XML/Schema) are commonly used for specifying metatype information in XML format, examples are the Web Services (SOAP) specification, the UPnP specification and commercial systems for data exchange.
XML Schema is a rich specification, which is able to define a much larger set of types than OSGi Metatype supports. Thus, only a subset of the XML Schema datatypes need to be supported in KF XML Metatype.
The last step in the above list could be replaced by a CM utility automatically creating configurations from default data, if not otherwise present.
xmlns:xsd = "http://www.w3.org/2001/XMLSchema"
xmlns:metatype = "http://www.knopflerfish.org/XMLMetatype"
A CM service is a configuration intended to be received
by a CM ManagedService
. At most one CM configuration for a given
persistant ID (PID) exists at a given time.
A CM factory is a configuration intended to be received by a CM
ManagedServiceFactory
. Several CM configurations can exists
for a given PID.
Metatype declaration in an XML document must use the
<metatype>
element as top level element.
This element can only
contain the <xsd:schema>
,
and <metatype:values>
elements. Each of these is optional.
Services and factories are specified as complexType
elements
inside the schema
element. The only difference between a service and a
factory definition is the maxOccurs
value. A factory may occur
more than once in a value document, a service just once.
Each service or factory defines a possible PID, represented by an object definition containing a set of attribute definitions.
<metatype:metatype xmlns:metatype = "http://www.knopflerfish.org/XMLMetatype" xmlns:xsd = "http://www.w3.org/2001/XMLSchema"> <xsd:schema> <xsd:complexType name = "ServiceID" maxOccurs = "1"> ... </xsd:complexType> ... <xsd:complexType name = "FactoryID" maxOccurs = "unbounded"> ... </xsd:complexType> ... </xsd:schema> <!-- optional default values --> <metatype:values> ... </metatype:values> </metatype:metatype>
All service and factory definitions are instances of a
complexType
specification.
This complexType
fully defines the array of
AttributeDefinitions
in the resulting metatype definition.
A service definition is a complexType with the maxOccurs
attribute set to one.
A factory definition is a complexType with the maxOccurs
attribute
larger than one. Default is a service definition.
The name of the service/factory complexType
defines the object identifier. During run-time, the name also defines
the persistant ID of configurations.
<xsd:complexType name="service1"> <xsd:element name="string1" type="xsd:string"/> </xsd:complexType>
<xsd:complexType name="factory1" maxOccurs="unbounded"> <xsd:element name="int1" type="xsd:int"/> </xsd:complexType>
Vector and arrays are specified using the <xsd:sequence>
element. The default format is vector.
The nice thing
with arrays is that they have a well-defined item class even if empty. Arrays
are also easier to use for a ManagedService since the can avoid verbose
to<Type>()
calls.
<xsd:complexType name="service2"> <xsd:complexType name = "intvector1"> <xsd:sequence> <xsd:element name = "item" type="xsd:int"/> </xsd:sequence> </xsd:complexType> </xsd:complexType>
Note: <xsd:sequence>
must have exacly one element
be named "item".
A service's (and factory's) description is set using schema annotations on
the top level complexType
. If no description is set, the
empty string will be used.
<xsd:complexType name="service1">
<xsd:annotation>
<xsd:documentation>
This is a service annotation
</xsd:documentation>
</xsd:annotation>
...
</xsd:complexType>
A service/factory icon URL can be set by adding an option iconURL
attribute to the service's defining element.
URLs starting with "/" should be considered relative to the defining bundle's jar file, i.e, bundle resource names.
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" > <xsd:complexType name = "service1" iconURL = "/image.gif"> ...
An attribute description is set using schema annotations on the attribues defining element. If no description is set, the empty string will be used.
<xsd:complexType name="service1">
<xsd:element name="string1" type="xsd:string">
<xsd:annotation>
<xsd:documentation>
This is an attribute annotation
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:complexType>
Locale specific description strings can be set on annotations, using the
standard xml:lang
attribute:
<xsd:element name="string1" type="xsd:string"> <xsd:annotation> <xsd:documentation xml:lang="en"> This is the English description. </xsd:documentation> <xsd:documentation xml:lang="se"> Detta ?r beskrivningen p? svenska. </xsd:documentation> </xsd:annotation> </xsd:element>
Optionally, the <xsd:appInfo>
element can be used to specify a an
URL or resource file to localization property file. The appInfo
should then be set on the object class definition element.
Standard file name expansion for locales may be done on
the URL.
URLs starting with "/" should be considered relative to the defining bundle's jar file, i.e, bundle resource names.
The key for lookup in the external localization file
will be the attribute's ID, plus either ".desc"
for attribute
description and, optionally, ".name"
for attribute names.
If the the key is not found, the xsd:documentation
will be
searched for default values.
<xsd:complexType name="service1"> <xsd:annotation> <xsd:appInfo>/settings.props<xsd:/appInfo> </xsd:annotation> <xsd:element name="string1" type="xsd:string"/> ...
The file /settings.props
in the bundle jar should
contain lines as:
string1.desc=This is the description for string1 string1.name=First string
A Swedish translation /settings_se.props
in the bundle jar could
contain lines as:
string1.desc=Humdihumdididum string1.name=Chef #1
The name of each service/factory data element represent the ID of an attribute definition. If nothing else is specified in the element annotation, the name of the attribute equals its ID.
The type of each service/factory data element represent the type of the attribute definition.
<xsd:annotation>
elements can optionally be used to set
an attribute or enumeration description.
Datatype | XML specification | Java representation | Comment | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Primitive types | |||||||||||||||||||||||||
string | <xsd:element name="NAME" type="xsd:string"/>
| java.lang.String | NAME is the ID and default name of the Metatype
AttibuteDefinition .
NAME must be possible to use as a valid XML tag name. |
||||||||||||||||||||||
integer | <xsd:element name="NAME" type="xsd:int"/>
| java.lang.Integer | |||||||||||||||||||||||
long | <xsd:element name="NAME" type="xsd:long"/>
| java.lang.Long | |||||||||||||||||||||||
short | <xsd:element name="NAME" type="xsd:short"/>
| java.lang.Short | |||||||||||||||||||||||
char | <xsd:element name="NAME" type="xsd:char"/>
| java.lang.Character | |||||||||||||||||||||||
float | <xsd:element name="NAME" type="xsd:float"/>
| java.lang.Float | |||||||||||||||||||||||
double | <xsd:element name="NAME" type="xsd:double"/>
| java.lang.Double | |||||||||||||||||||||||
boolean | <xsd:element name="NAME" type="xsd:boolean"/>
| java.lang.Boolean | |||||||||||||||||||||||
BigInteger | <xsd:element name="NAME" type="xsd:integer"/>
| ||||||||||||||||||||||||
BigDecimal | <xsd:element name="NAME" type="xsd:decimal"/>
| java.math.BigDecimal | If running on a JVM without the BigDecimal class, double is used instead. | ||||||||||||||||||||||
Primitive types with restrictions | |||||||||||||||||||||||||
Enumerated types |
<xsd:simpleType name = "NAME"> <xsd:restriction base="TYPE"> <xsd:enumeration value="VALUE1"/> <xsd:enumeration value="VALUE2"/> ... </xsd:restriction> </xsd:simpleType> |
As defined by TYPE. See primitive types above. | Enumeration values will be stored as attribute definition option values. | ||||||||||||||||||||||
Enumerated types with labels |
<xsd:simpleType name = "NAME"> <xsd:restriction base="TYPE"> <xsd:enumeration value="VALUE1"/> <xsd:annotation> <xsd:documentation> Label for VALUE1 </xsd:documentation> </xsd:annotation> ... </xsd:restriction> </xsd:simpleType> |
As defined by TYPE. See primitive types above. | If <xsd:annotation> elements are added to an
enumeration , the annotation documentation will be used as
the attribute definition's option label. If no annotation documentations
are found, the values are used as labels.
|
||||||||||||||||||||||
Vectors and arrays | |||||||||||||||||||||||||
Vector | <xsd:complexType name="NAME"> <xsd:sequence [array="false"] [maxOccurs="MAX"]> PRIMITIVE_TYPE </xsd:sequence> </xsd:complexType> |
java.util.Vector, where each item is of the type specified by PRIMITIVE_TYPE
Note: The specifed PRIMITIVE_TYPE must have a name of "item" |
The default value for the array property is "false". The default value for the maxOccurs property is
java.lang.Integer.MAX_VALUE . |
||||||||||||||||||||||
Array | <xsd:complexType name="NAME" [maxOccurs="MAX"]> <xsd:sequence array="true"> PRIMITIVE_TYPE </xsd:sequence> </xsd:complexType> |
Java array, where each item is of the unboxed type specified by
PRIMITIVE_TYPE.
Note: The specifed PRIMITIVE_TYPE must have a name of "item" |
Resulting arrays will be represented as:
|
Attributes can be specified to be optional by setting the
minOccurs
attribute to zero on the attribute element.
By default, attributes are required -- which also can be specified by
setting minOccurs
to one.
Setting minOccurs > 1
is not allowed.
<xsd:element name = "string1" type = "xsd:string" minOccurs = "0"/>
Configuration values are specified using the
<metatype:values>
element. This contains a set of XML elements as defined by the Metatype
schema.
A <metatype:values>
element can be embedded in
<metatype:metatype>
. The values should then be considered default values for the specified metatypes.
<?xml version="1.0"?> <metatype:values xmlns:metatype = "http://www.knopflerfish.org/XMLMetatype"> [VALUE_DECLARATIONS] </metatype:values>
[VALUE_DECLARATIONS] is thus a sequence of top level elements, named as the PIDs used when defining the metatypes. Each such PID element contains elements matching the attribute definitions.
<service1> <string1>this the string value</string1> </service1>
<service2> <intvector1> <item>1</item> <item>2</item> <item>3</item> </intvector1> </service2>
As value specifications are instances of a schema, the system is assumed to have access to the schema specification when parsing a value document. This can be accomplished by at least three different methods:
metatype:services
and/or metatype:factories
elements.
type="TYPE"
on each value element.
<service3> <string1 type="xsd:string"/> <intvector1 type="xsd:int" array="true"> <item>1</item> <item>2</item> <item>3</item> </intvector1> </service2>
A bundle can store URLs to metatype and value document in its Manifest attributes. The run-time system is then responsible for reading these attributes when the bundle is started (or deployed) and converting them to suitable run-time format (Metatype API and/or CM dictionaries).
URLs starting with "/" should be considered relative to the defining bundle's jar file, i.e, bundle resource names.
Manifest attribute | Description | Default value |
---|---|---|
Bundle-MetatypeURL | URL to XML document describing metatype |
/metatype.xml |
Bundle-CMDefaultsURL | URL to XML document with CM default values |
/cmdefaults.xml |
A draft implementation is available at
https://www.knopflerfish.org/svn/knopflerfish.org/trunk/osgi/bundles/metatype
See http://www.knopflerfish.org for details on how to access the code repository.
Conclusion: The Locale-specific methods
OCD.getName, OCD.getDescription, OCD.getIcon AD.getName, AD.getDescription and AD.getOptionLabelsshould be themselves take a Locale argument, not the MetatypeProvider.
(...and while I'm at it, the getIcon argument "size" could just as easily be dumped since there is no chance of relying on the results. Also, returning a stream from getIcon effectively removes any possibility of remoting OCD instances. an URL string would be much better)
|
Knopflerfish OSGi 1.3.3 | |||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |