The RM OSGi Device Management package provides functionality which extends the generic capabilities of the RM Software Repository module.
Additional utilities are provided for maintaining of OSGi bundles designed for deployment on OSGi devices. In this document, it is assumed that the reader is familiar with the basic concepts of the RM Software Repository described in the Software Repository package documentation.

Basic Principles

The OSGi bundles in the RM system are represented and managed as client bundles on behalf of the Software Repository. It keeps information about their common client bundle attributes, while the Software Repository Content Plug-in provided specifically for the OSGi bundles has the following features:

• Simplifies the import process of OSGi bundles by automatically retrieving the client bundle attributes from the provided metadata and the content of the OSGi bundle JAR file
• Provides a number of custom properties specific for the OSGi bundles.

The generic functionality of the Software Repository module together with the OSGi Bundle Content Plug-in perform the following tasks:

• Storing the OSGi bundle JARs and provides easy access to them from all RM's modules.
• Managing information about the OSGi bundles, which may involve the properties from the OSGi bundle JAR manifest and from the configuration XML file.
• Managing the relationships between stored OSGi bundles, that is, getting the OSGi bundles necessary for the proper operation of a designated bundle. OSGi bundle dependencies can be resolved dynamically by the repository-based on the properties from the manifest and/or by properties explicitly defined by the service provider or system administrator.
• Managing driver bundles and the information related to the RM Driver Locator. The Software Repository also provides driver matching facilities, which the RM modules supporting the OSGi device driver model use.

OSGi Bundle Attributes

General Client Bundle Characteristics

The general Software Repository-defined attributes of the client bundles are mapped to the specific characteristics of the OSGi bundle. The following attributes have specific values in the context of the OSGi bundles:

• General Type – The general product type of OSGi bundles is APPLICATION.
• Concrete Type – OSGi bundles are represented as client bundles with concrete type OSGi Bundle.
• Global ID – An identifier of an OSGi bundle which specifies that two OSGi bundles with the same global ids and versions are not accepted in the Software Repository. The value of the global identifier is considered to be the unique Bundle-SymbolicName header. In case the bundle does not have a symbolic name, its Bundle-Name becomes the value of this attribute.
• Content ID – The logical identifier of the bundle. Bundles having the same content ID are considered as client bundles and are mutually replaceable. By default, the unique Bundle-SymbolicName manifest header is considered as content ID. If an OSGi bundle does not have a symbolic name – it is meant to run on the framework implementation, which is compliant with OSGi Service Platform Specification, Release 3 – the unique Bundle-Name manifest header is used as a content ID. The default value of the content ID can be predefined in three ways:
• Through the content-id element of an OSGi bundle descriptor file
• Through the content-id element of a provisioning descriptor contained in a Provisioning Archive file (see the JSR 124, J2EE Client Provisioning specification)
• Manually by the RM user on adding the OSGi bundle to the Software Repository.
• Display Name – A user-friendly name specified by the user or the value of the Bundle-Name header taken from the manifest file of the bundle.
• Version – The version of the OSGi bundle. If is has no version, it is considered as having the lowest version. The value of this attribute is considered the Bundle-Version manifest header value.
• Catalog Properties – The categories that separate OSGi bundles according to their functionality. This attribute can have as value the Bundle-Category manifest property.
• Requirements – The requirements of the OSGi bundle towards the capabilities of the client device such as imported packages and services. It is possible that an OSGi bundle depends on other bundles, although it does not import any of their packages directly. By inputting the global or content IDs of such additional client bundles and adding them to the bundle dependency list, important dependencies can be resolved. The values of this OSGi bundle attribute can include the Import-Package and Import-Service manifest properties. For thorough information about the client bundle requirements, refer to the "Client Bundle Requirements and Capabilities" section of the "Basic Principles of the Software Repository" conceptual guide of the Software Repository package documentation.
• Capabilities – The attributes a device inherits from the OSGi bundle after it is deployed on the device such as the packages and services exported by the bundle. Possible values of this attribute are the Export-Service and Export-Package manifest properties.

The default set of requirements and capabilities an OSGi bundle provides can be preliminary defined in three ways:

• Through the elements of an OSGi bundle descriptor XML (see table below)
• Through the elements of a provisioning descriptor XML provided in a Provisioning Archive file (refer to the JSR 124, J2EE Client Provisioning specification)
• Manually by the RM user after the OSGi bundle is added to the Software Repository.

Custom Client Bundle Characteristics

In addition to the general client bundle characteristics, the Software Repository supports the following OSGi bundle specific properties:

• Manifest – Represents the manifest properties of the OSGi bundle.
• Zero or more conditional configurations – Represents the set of new configuration properties that should be used when an OSGi bundle is deployed on a device with specific platform capabilities. The configuration properties of the conditional configuration can change the default ones and therefore change the functionality of the bundle in order to make it appropriate for work on the device. You can define as many configuration properties as is the number of original bundle plain configurations.
• Zero or more configuration variants – Represents a predefined bundle configuration. Bundles can have more than one predefined configuration. They are identified by PIDs. On bundle delivery the needed configuration is pointed by its unique PID. In case the PID of the configuration variant is not specified, a default configuration is used, if any.
• Permissions – The permissions that the bundle needs when installed on a device with security on.
• Certificate – The certificate that is used to sign the OSGi bundle, if any.
• Access rights – The rights that RM's users have on the bundle. For more information refer to the "Software Repository" package documentation.
• Driver – The service properties of the devices which the OSGi bundle can handle if it is a RM Driver Locator.

OSGi Bundle Requirements and Capabilities

OSGi bundles can require specific conditions in order to work properly on a device. These requirements may be connected with the platform capabilities provided by the device or with the capabilities provided by another OSGi bundle. On behalf of the Software Repository, the imported services and packages of an OSGi bundle are considered as bundle requirements, while the exported services and packages are considered as bundle capabilities.
The OSGi Bundle Content Plug-in automatically determines a set of bundle requirements and capabilities by analyzing the manifest file when the OSGi bundle is added to the Software Repository. The following manifest properties are used:

• Require-Bundle header – Represents the bundle requirement with property name SoftwarePlatform.Component.GlobalId which is used to specify the dependence of the OSGi bundle from other bundles.
• Bundle-ManifestVersion header – Represents the bundle requirement with name SoftwarePlatform.OSGi.Specification which is used to specify the version of the OSGi Framework Specification on the device needed by the OSGi bundle to work properly. This bundle requirement is defined using the manifest header and the version of the org.osgi.framework package specified in the Import-Package manifest header.
• Bundle-RequiredExecutionEnvironment – Represents the OSGi bundle requirement with property name SoftwarePlatform.EE which is used to define the execution environment needed by the OSGi bundle to operate properly on an OSGi device. For more information on the automatic determining of the EEs required by an OSGi bundle, refer to the Execution Environment Management document.
• Import-Package header – Represents the bundle requirement with name SoftwarePlatform.Package which is used to specify the dependence of the bundle from specific packages.
• Import-Service header – Represents the bundle requirement with property name SoftwarePlatform.Service which is used to specify the dependence of the bundle from specific services.
• Export-Package header – Represents the bundle capability with property name SoftwarePlatform.Package which is used to specify the packages provided by the bundle.
• Export-Service header – Represents the bundle capabilities with property name SoftwarePlatform.Service which is used to specify the services provided by the bundle.

For thorough information on maintaining the requirements and capabilities of a client bundle, refer to the "Basic Principles of the Software Repository" document from the Conceptual Guide of the Software Repository package documentation.

Conditional Configurations

If an OSGi client bundle manifests a dictionary of configuration properties in terms of the OSGi Configuration Admin and Metatype specifications, and the bundle provides the metadata of these properties in a configuration XML file in the format defined by the Config bundle, then you can define one or more conditional configurations of the client bundle.

Usage Principles

A conditional configuration contains specific values of the configuration properties of some of the variants of an OSGi client bundle. These values should substitute the currently set ones in case the deployment environment matches the platform properties defined in a specific client bundle requirement. If the OSGi client bundle is to be deployed on a device which matches its requirements, the system checks if the bundle has conditional configurations. If some of the bundle requirements of these conditional configurations match the device capabilities, the property values in the matching conditional configuration substitute the ones in the original bundle configuration.
For example considering that a bundle has a "COM Port" property with initial value "COM1" and you are installing the bundle on a Linux OS, then you may define a client bundle with a conditional configuration with bundle requirement "SoftwarePlatform.OSName" equal to "Linux" and with value "/dev/ttyS0" of the "COM Port" property.

Specifying Conditional Configurations in an XML

You can preliminary specify conditional configurations. This is done through a bundle requirement XML (included in the JAR of the client bundle) holding information about the platform profiles required by the bundle. Each platform profile is mapped to a separate conditional configuration. The XML has the following syntax:
The XML must have the encoding="UTF-8" attribute.
The root of the XML must be <BundleRequirements>...</BundleRequirements>. All platform profiles with their properties must be contained there.
The tags reserved for platform profiles are:

The following listing contains an example bundle requirement XML with conditional configuration of an HTTP server for platform Linux/JDK1.8.8.
An example XML with platform requirements:

Besides the XML describing the bundle requirements, the requester bundle must contain a Bundle-Requirements header in its manifest file. Its value must contain the location of the XML plus "requirement=platforms". For example:
Bundle-Requirements: requirement/platforms.xml;requirement="platforms"

Bundle Configurations

The additional features of the Software Repository provided for management of OSGi bundles enable the RM user with the opportunity to edit the default configuration of an OSGi bundle. This is possible only in case the application is configured through the OSGi Configuration Admin service. An editable bundle should contain metadata information for its configuration objects in a XML format defined by the OSGi Metatype Service from the OSGi Service Platform Service Compendium or in the Bosch Digital proprietary XML format.
The RM user can plan configuration variants for devices that meet certain criteria not closely related to device platforms. For example, if a server bundle allocates a port for communication and on a sub network of devices this port is already occupied by another application, then you may define a configuration variant with different port number. Having predefined some configuration variants for a specific bundle configuration, the user can choose between them when installing the bundle on different OSGi devices. As a result the property values of the selected configuration variant replace the ones of the original configuration. In case the RM user does not explicitly specify a configuration variant, the default one is used.
There is always one bundle configuration variant – the default one. Initially, the default bundle configuration is the original configuration from the metatype XML resource file residing in the OSGi-INF/metatype directory of the bundle JAR or from the Bosch Digital formatted XML file placed inside the bundle JAR.

Permissions

The permissions that an OSGi bundle needs to operate properly on a device with security on can be preliminary specified in a permissions.perm file placed in the OSGI-INF directory of the bundle JAR file. The system administrator and the device operator are can view bundle permissions in the console (see the OSGi Bundles in the Software Repository document from the User's Guide).
Permissions set for an OSGi bundle are useful when the target device is running the OSGi Permission Admin service. When a bundle is installed, the RM management agent sets the corresponding client bundle permissions in the Permission Admin service.

Signed OSGi Bundle JARs

An OSGi client bundle JAR can be signed using a specific PK algorithm and a certificate. It is possible to view the certificate of the client bundle JAR and to publish it in the Certificate Repository of the RM Certificate Management.

Bundle Descriptor

The most important properties of an OSGi bundle can be preliminary described in an XML file, called bundle descriptor. The OSGi bundle descriptor must be called mprm-bd.xml and must be placed in the META-INF directory of the OSGi bundle JAR.
The bundle descriptor has the following DTD:

An example bundle descriptor:

Installation and Setup

The OSGi bundles functionality on the backend is supported by the RM Bundles:
genericosgi.sr.bundles.api.jar
genericosgi.sr.bundles.be.api.jar
genericosgi.sr.bundles.be.jar
genericosgi.sr.bundles.db.jar
which are loaded by default at host startup.

User Interface

The console provides a full access to the functionality of the OSGi bundles in the Software Repository. You can find more information on managing the OSGi bundles with the console in the User Guide. For information on configuring the Software Repository with the console, refer to the Software Repository Management through console User Guide.

API

There is a front-end API that allows adding OSGi bundles and defining client bundles that suit best a target deployment platform as well as tracing bundle dependencies. A description of how to use it is available in Developer Guide.