The RM system keeps device specific properties which can be used for matching the requirements of a client bundle to the capabilities of a client device when the bundle is to be deployed on the device.
Definitions
A client bundle requirement is a key-value pair of specific conditions needed by a client bundle in order to work properly after deployment on a client device. Such requirements can exist between two client bundles or between a client bundle and specific device platform capabilities. Client bundle requirements can be optional, multiple and extend. Furthermore, a client bundle can explicitly state an incompatibility requirement. For further information about the different types of requirements, refer to the "Client Bundle Requirements and Capabilities" section of the Basic Principles of the Software Repository Conceptual Guide.
A client bundle capability is a key-value pair describing the functionality a client bundle can add to the device after it is deployed on it and therefore increase the device complexity.
A device capability represents a key-value pair of specific properties characterizing the aspects of the hardware and software systems of a specific device. The device capabilities determine the ability of the device to execute particular applications. Initially, device capabilities can be the device virtual machine, the unique identifier of the device class, etc. After a software component is deployed on the device, its capabilities are extended with the capabilities of the imported client bundle.
A platform property reflects specific characteristics of a device. It is a collective term for client bundle requirements and capabilities, and device capabilities. It is a set of name-value properties where the key is the unique name of the platform property which can have several values. For example, for an OSGi-enabled device such platform properties can be the operating system, the version of the OSGi framework specification, etc. Initially, the RM contains properties defined in the JSR 124 J2EE Client Provisioning. Of course, new properties can be introduced to refine the matching of client bundle requirements against device capabilities.
A platform profile is a named set of platform properties with specific values set.
The profiles manager is responsible for classifying and managing predefined hardware and software platform properties and profiles. It is used to determine the right client bundle for a particular device.
Basic Principles
The Role of Platform Properties in the Bundle Deployment Process
The capabilities of a device are specified when it is added to the RM system. When a client bundle is installed on the device, device manager module contacts the Basic Principles of the Software Repository to get the most suitable client bundle. On its behalf, the Software Repository contacts the profiles manager to match the requirements of the client bundle against the device capabilities according to predefined property and profile relations and rules. As a result, the Software Repository determines the best client bundle for the device.
If a client bundle has declared an incompatibility requirement that matches the device capabilities, the Software Repository considers this application as unsuitable for deployment on the specific device.
The profiles manager is able to match bundle requirements against device capabilities, mapped to a common property that does not exist in the manager storage. In this case requirements and capabilities either fully match or do not match at all.
How RM Determines Device Capabilities
There are four basic ways in which RM determines the capabilities of a device according to the way of retrieving information:
- Automatic - RM retrieves the available device capabilities.
- User-defined - The system administrator can define device capabilities for a specific device on device registration in the RM system as well as after the device has been registered.
- Plug-ins - Developers can extend the supported device types and provide different device capabilities to characterize the supported devices.
- Configuration files - A XML-formatted configuration file with the device capabilities descriptions.
The RM retrieves a set of device capabilities when activated on a client device or when the device is synchronized. RM offers several ready platform properties with all necessary relations set. They are used in the process of client bundle requirement matching and deployment on devices:
Device Capability Key | Base Value Type | Description |
|---|---|---|
| Vendor/Model | Represents the unique identifier class of the device. For example, OSGi enabled devices are identified with the "mprm.osgi.device" device capability value. |
| Platform Profile ID | Represents a platform profile whose requirements the current profile satisfies. See Extending Profiles. |
| CPU Type | Represents the processor of the device. This property is analogous to the |
| Client Bundle ID | Represents the unique bundle identifier of a client bundle installed on the device which can be used to resolve the dependencies of a client bundle. |
| Client Bundle Content ID | Represents the logical identifier of the content that a client bundle running on the device represent. Can be used to resolve the dependencies of a deployment unit that is to be installed on the device. |
| Client Bundle Global ID/ Version | Represents the global unique identifier of a client bundle which is used in case an imported client bundle depends on another client bundle. |
| Exported Package/ Specification-Version | Represents the packages exported by client bundles running on the device. |
| Exported Service | Represents the services registered by client bundles running on the device. |
| Defined Execution Environment Name | Represents the execution environment of the target device. See "Execution Environment Management" Conceptual Guide from the OSGi Device Management package documentation for more details. |
| OS Name | Represents the operating system of the device. |
| Java Platform Name/Version | Represents the Java virtual machine (its class library in particular) installed on the device. |
| OSGi Specification Name/Version | Represents the version of the OSGi Framework Specification implemented on the device. It can be 1.2, 1.3+, etc. The "+" character indicates equal or greater than the stated version. |
| OSGi Framework/Version | Represents the version of the vendor-specific OSGi framework. For Bosch IoT Gateway Software this can be Release 5.1, Release 5.2, etc. |
All retrieved capabilities are merged and sent to the backend where they can be used in the client bundle deployment process.
Limitations
When importing files to the Software Repository the system applies certain limitations to the:
- file types
- file size
- file count
Platform Properties
Property Matchers
As it was said above, the matching algorithm for a property is executed by a matcher. JSR 124 defines the basic types of matchers and their algorithms. RM introduces an additional matcher - com.prosyst.mprm.backend.impl.platforms.FuzzyVersionMatcher. You can develop your own property matchers in a programming way if needed – see Developer Guide.
Depending on the matching algorithm, the following matcher options are available:
wildCardsOn– A capability value may contain wild cards (* characters), which match any sequence of characters in a bundle requirement value. Defined in JSR 124.allMustMatch– A capability should match all values of a bundle requirement. By default, it is sufficient that the capability matches any requirement value. Defined in JSR 124.caseInsensitive– A capability value is compared with a requirement value regardless of the case. The "-" and "_'" characters are treated as matching. Defined in JSR 124.useRelations– A requirement is matched against a capability benefiting from the relations defined for the corresponding properties.
By default, for a newly created property no matcher options are assigned.
Following is a description of the initial matchers (shown by their Java classes) provided by RM.
Matcher | Supported Options | Description |
|---|---|---|
|
| Matches a capability string against a requirement string(s). There are only two possible results:
|
|
| Similar to StringMatcher, but it is able to provide a match value greater than 0.0 (stands for no match) and less than 1.0 (stands for full match). For example can be used for language localization properties. |
|
| Matches a capability integer against a requirement integer. A capability string can be parsed as a Java int. Requirement strings are the same and they can contain the "+" suffix, which means that a larger number is acceptable too. Matching here means checking equality, or if the capability is equal or greater than the requirement. |
|
| Computers the matching between two-dimensional capabilities and requirements. Each dimension is treated as an int and when in the requirement may contain the "" suffix (see the previous matcher). The matcher checks for a full match or in the case "" for a partial match if the capability is greater than the requirement. This matcher can be applied for screen size. |
|
| Matches version properties with the following syntax:
A requirement matches a capability if they have the same name and the requirement version string matches the capability version ID. Matching between version string and version ID is described in Appendix A of JSR 56, Java Network Launching Protocol& API Specification. |
|
| It is similar to VersionMatcher, but it takes into account how big is the difference between the required and the available version. |
|
| Matches execution environments by their "inclusion" relation. Designed especially for use with the SoftwarePlatform.EE property (see the "Execution Environment Management" Conceptual Guide from the OSGi Device Management package documentation). |
|
| Matches the import and export packages of a client bundle. Designed especially for use with the SoftwarePlatform.Package property. |
More details about the matching algorithms above are available in JSR 124.
Value Relations
You can define if two (or more) property values are compatible to some extent – this eases the matching process. One property value is compatible with another if the first one implies the second one. In particular, this can be used to define the capability values that match a requirement value. For example, if you set the x86 value of the HardwarePlatform.CPU property to be compatible with i386, i486, i586, etc., matching will be successful for a bundle requiring an x86 processor and for a device using i486.
Transform Rules
A transform rule defines the way in which a collection of capabilities is "transformed" into a specific property value. Then, this value can be specified as a requirement for a bundle (in the Software Repository). The profiles manager executes the transformation if a specific condition(s) is satisfied. Such a condition is defined with a string representation of an LDAP search filter, whose grammar is defined in RFC 1960, A String Representation of LDAP Search Filters.
For example, if you have a property, reflecting the device type of the device, with a transform rule condition:
(device_type=*printer*)
and a target value printer, then all devices which are some kinds of printers (i.e. their "device_type" capability contains the printer key) will be unified under the printer value and bundle requirements will be matched against this value.
Platform Profiles
A platform profile is a platform property which reflects the specifics of a particular device platform. It consists of platform properties with specific values set and can be used as client bundle requirement (with one or more values) or as device capability. The concept of platform profiles includes compatibility and inheritance as well.
Profiles Compatibility
Platform profiles can be linked with compatibility relations. We say that one profile is compatible with another if the second one is included in the first one. "Includes" is a one way relation, i.e. if one profile "includes" another, this do not necessary mean that the second includes the first one. For example, J2SE platform includes the WinNT/x86/JDK1.2* platform and therefore the WinNT/x86/JDK1.2* is compatible with J2SE. If a bundle requires J2SE and the target device is running on WinNT/x86/JDK1.2.2, then the bundle will be successfully deployed.
It is also possible to define how much a profile is compatible with another profile – this is a number between 0 and 1, or between 0% and 100%.
Mapping of a required profile to a compatible one is done regardless of the profile properties relations. If a profile has no compatibles, but there are compatibility relations for its properties, then these relations are considered (in case useRelations is on). For example, if a bundle requires a Windows/x86 platform and the x86 property is related to i386, then a device with capability i386 satisfies the bundle requirement.
Extending Profiles
RM allows the system administrator to define a profile that "extends" one or more existing profiles. The new profile inherits the attributes of its parents and they are set as its compatibles, that is it is compatible with the extended ones.
For the extending profile, the profiles manager internally uses a property called Profile Capabilities with value the extended profile. This means that the child profile is "capable" of the requirements that the parent profile outlines.
Property Aliases
If two or more properties have the same meaning, for example HardwarePlatform.CPU (defined in JSR 124) and org.osgi.framework.processor (a system property defined in the OSGi Framework specification), it is possible to unite them by defining one of them as a property and the other(s) as this property alias(s) – for example org.osgi.framework.processor can be set as an alias of HardwarePlatform.CPU.
If specific values for the alias are detected or required, these values are attached to the value list of the property itself and matching towards them is applied. For example if a registered device has org.osgi.framework.processor=i386 and a bundle (in particular some of its variants) has a requirement HardwarePlatform.CPU=i386, then the "processor" device capability satisfies the bundle requirement.
Access Rights
The profiles manager restricts access to the operations that can be executed on stored platform properties and profiles:
- View device platform properties – The right to view platform properties without changing is provided to the users, members of the Permission - Platform - View group. By default, users with "modify" permission for the profiles manager can view properties and profiles.
- Modify device platform properties – The right to modify platform properties (add/remove properties, define relations between them, etc.) is provided to the users participating in the Permission - Platform - Modify group. By default, users from the administration group (i.e. device operators) or from the ServiceProviders group (i.e. service providers) have the "modify" right for the profiles manager.
The Remote Manager does not allow a user to change/delete files of other users. Downloads from the SR by users that are not authorized to do so is restricted.
Installation and Setup
The profiles manager is implemented by the Platform Profiles Manager bundle, whose JAR is foundation.platform.be.jar from the packages/foundation RM directory. This bundle is included in the package descriptor XML of the OSGi Device Management package and is started at host startup.
Profiles Manager API
RM provides a front-end API for defining platform properties and profiles. It also supports developing a custom property matcher. Refer to Developer Guide for further details.