Basic Principles of the Software Repository
The Software Repository maintains different file formats for the imported applications. RM supports having client bundles for specific device requirements. Bundle characteristics are used to determine which applications should be delivered to a particular client device.
Overview
The Software Repository manages the applications in the RM system and keeps information about their main characteristics. It is intended mainly for system administrators and service providers. The sub-system for device management requests data about the application requirements and dependencies from the Software Repository.
The Software Repository performs the following tasks:
Stores different applications in a central place and provides easy access to them from all RM's modules.
Supports use of external OSGi Bundle Repositories (a concept defined in the RFC-0112 Bundle Repository introduced by the OSGi Alliance) for significantly extending the range of the applications offered to the RM users.
Manages essential information about applications. For example, if the managed application is an OSGi bundle, the properties from the bundle JAR manifest are used by the Software Repository. If the application is a Provisioning ARchive file, the information from its provisioning XML file is used.
Manages the relationships between stored applications. Bundle dependencies can be resolved dynamically by the repository based on the properties defined by the system when an application is imported and/or by properties explicitly defined by the service provider or system administrator.
Software Repository System Architecture
The system architecture of the Software Repository is presented in the following figure:
Figure 2: . Software Repository Architecture.
Software Repository Content Plug-ins
Software Repository Content Plug-ins are pluggable units which represent in a unified way different types of software components and allow their processing. Content Plug-ins may be separated according to the functionality they represent when a software component is to be processed. For example, the OSGi Bundle Plug-in is responsible for maintaining OSGi bundles and their attributes, the Deployment Package Plug-in is responsible for managing deployment packages and representing them in a way suitable for the Software Repository System, etc.
Software Repository Content Plug-ins are responsible for:
Interpreting the content of the software component during the import process
Checking the validity of the deployment unit attributes by analyzing the import file
Providing metadata about the particular software component
Ensuring the representation and maintenance of specific properties of the particular software component.
Software Repository
The Software Repository is the central unit of the Software Repository System. It ensures:
Storing the content of different types of deployment units and the URLs of external applications
Common representation and management of multiple software types
Providing the different client devices with suitable for deployment units
Software Repository Interface
The Software Repository Interface provides a unified API for maintaining deployment units and their attributes. The Software Repository API can be used to:
Add software components to the repository
Control and monitor existing deployment units and their attributes
Discover the most suitable deployment component for the capabilities of a particular device
Listen for changes in deployment units
Provide Content Plug-ins for managing various software types
Platform Profile Manager
The Platform Profile Manager is responsible for managing platform properties and profiles of a device. It is used to match the requirements of a specific software component to the capabilities of the device and therefore ensure that the most suitable component from the Software Repository will be deployed on the device.
Software Repository DB Services
Common Client Bundle Database – Keeps the metadata information and the content of the deployment units and the URLs and the metadata of the external deployment components.
Platform Profile Database – Keeps the platform properties and profiles of devices which are used to match the requirements of a deployment unit to the capabilities of a specific device.
Custom Plug-in Databases – Software Repository Content Plug-ins may use their own databases in addition to the Common Client Bundle Database.
Software Repository Deployment Units
The basic deployment units maintained by the Software Repository are client bundles. They represent an arbitrary type of software resource that can be downloaded via the network and executed on a client device. The term client bundle is interpreted according to the JSR 124, J2EE Client Provisioning.
The client bundle concept serves as a base for creating superior maintenance models. The Software Repository manages the functional characteristics of deployment units like OSGi Bundles, Bundle Groups, Deployment Packages, Provisioning Archives and MIDlet Suites.
A deployment unit can have one or more client bundles, intended for deployment on specific device platforms. Client bundles can have the same content identifier although they can have different versions and platform requirements depending on the targeted device.
A deployment unit always has at least one client bundle. Otherwise, it would not be recognized as an entry in the Software Repository
Client Bundles
Client Bundle Attributes
The Software Repository maintains the following attributes for a client bundle:
General type – Describes the general product or media type of the client bundle, for example IMAGE. If a client bundle is not associated with any of the types familiar to the Software Repository, it is referred to as "Unclassified". The RM supports different general types, defined by the JSR 124, J2EE Client Provisioning, such as APPLICATION, ANIMATION, LOGO, SCREENSAVER, WALLPAPER, AUDIO, etc.
Concrete type – Describes client bundle specific characteristics. The concrete bundle types recognized by Software Repository include Bundle Group, OSGi Bundle, MIDlet Suite and OSGi Deployment Package.
Bundle ID – The unique identifier of each client bundle added to the repository.
Global ID – An optional client bundle property. Only one client bundle with the same type, global id and version can be added to the Software Repository.
Content ID – A logical identifier for the content a client bundle. Client bundles with different versions or platform requirements but with the same content ID are considered as mutually replaceable client bundles, bringing different functionality or targeting different kinds of devices.
Display name – User-friendly name of the client bundle.
Copyright – A copyright notice for the client bundle that may be shown to the user.
Version – A version string (e.g. 1.2.2 or 1.3) for the client bundle. If no version is available, the client bundle is treated as having the lowest version among the other client bundles with the same content identifier.
State – Indicates whether the client bundle is ready to be used by the end user. There are three states: importing, imported and published.
Upload time – The exact time when the client bundle was added to the Software Repository.
Size - The size of the client bundle.
Description – A human readable description of the client bundle functionality.
Vendor – The client bundle vendor that can be provided with a name, URL and description.
Catalog Properties - Client bundles may be organized using their catalog properties. For example they can be divided into categories that are understandable to the users. All properties have unique names.
Capabilities – The new features that a client bundle adds to a device when the bundle is deployed on it. For example, in case an OSGi bundle is successfully deployed on a specific client device, the packages and services it exports are considered as capabilities that extent the current device capabilities.
Requirements - The requirements of the client bundle towards the capabilities of the device platform or the capabilities provided by another client bundle. For more information about the dependencies between client bundle requirements and capabilities, refer to the "Client Bundle Requirements and Capabilities" section below.
Client Bundle Identification
RM identifies and classifies all client bundles added to the Software Repository by their type and identifier. This is accomplished by the registered Software Repository Content Plug-ins and helps the management of the client bundles in the repository and the deployment of the most suitable client bundle for a specific device.
General and Concrete Type
The general type of a client bundle introduced by Bosch. is the Bundle Type defined in the JSR 124, J2EE Client Provisioning specification. It classifies client bundles according to their content into product or media types.
The supported general types are:
APPLICATION
AUDIO
ICON
SCREENSAVER, etc.
In case the Software Repository encounters a client bundle with unfamiliar general type, it will be processed using only the basic Software Repository functionality and its general type will be UNCLASSIFIED.
Client bundles are further sorted by their concrete type. It extends the general type and allows the repository to finer sort the added software components.
Client Bundle Identifiers
Each client bundle as a unit in the Software Repository can be differentiated among the other deployment units with the help of three identifiers. These are the bundle ID, global ID and content ID.
The bundle identifier is unique for each client bundle and is generated by the Software Repository during the component's addition to the repository.
The global identifier is an optional characteristic for the client bundle and is used by the repository to make sure that one and the same client bundle is not imported twice. It is an obligatory attribute for the client bundles with "OSGi Bundle" and "OSGi Deployment Package" concrete type, while for the software components with "MIDlet Suite" and "Bundle Group" concrete type, it is an optional attribute. The value of the global ID for an OSGi bundle is the bundle symbolic name specified in the manifest file. For an OSGi deployment package is the value of the DeploymentPackage-SymbolicName manifest header is used as a global identifier by the Software Repository.
The content identifier is defined in the JSR 124, J2EE Client Provisioning specification. It is used to refer to client bundles which have the same basic functionality but differ in their version, localization, required capabilities or the capabilities they will provide to the specific device. In other words, the content identifier allows the developers to logically organize the variants of the same basic software component. For example, applications that receive notifications for the state of a lamp and are available in versions 1.0, 1.1 and 1.2, can be notified for the state of the lamp of a refrigerator, microwave oven and washing machine. Developers wishing to use the content identifier characteristic can assign an unique content identifier to a group of logically connected client bundles, in our example it may be "lamp.currentstate.notifier".
The Software Repository allows filtering client bundles through their types and identifiers. For more information, refer to the "Querying for Deployment Units" section from the Managing Deployment Units Programmer Guide.
Client Bundle Requirements and Capabilities
The client bundle is defined to work on one or more devices whose capabilities match specific bundle requirements. When a client bundle is to be deployed on a device with special system characteristics (retrieved when the device is registered in the system), then the repository selects the most suitable client bundle for that device platform and RM deploys it. In this case, the Software Repository contacts the Profiles Manager. The Profiles Manager matches the requirements of the client bundles against the properties of the platform specifics. Then if the requirements of two client bundles match to some extent the capabilities of the device, the Software Repository selects the one with the higher matching score. If the capabilities of the device do not satisfy the requirements of any of the client bundles, none of them is deployed.
For example, if a software component (in particular some of its variants) has a capability requirement SoftwarePlatform.Package=com.acme.mycompany and is to be deployed on a device with capability SoftwarePlatform.Package=com.acme.*, then the device capabilities satisfy the requirements of the client bundle and it can be successfully deployed on the device.
A client bundle requirement can have one or more values and depending on the property options, the device must match all these properties or any of them.
Besides the requirements a client bundle can have towards a specific device, it can require capabilities provided by other client bundles. Consequently, when such client bundle is deployed on a device, the client bundles it depends on are also deployed on the device. For example, in case an OSGi bundle uses a specific service, it requires the OSGi bundle which exports this service and therefore provides it as a capability.
Software Repository provides also mechanisms to specify even more precisely the requirements of a client bundle towards the capabilities of a specific device or other client bundles. A requirement can be optional, multiple or extend. It can also declare the incompatibility of the client bundle with other client bundles or device capabilities. See the "Resolving Client Bundle Dependencies" section below for further information.
The following specific requirement properties can be used by client bundles which depend on the capabilities of other client bundles:
SoftwarePlatform.Component.BundleId – Specifies the bundle ID of the client bundle that the current client bundle depends on.
SoftwarePlatform.Component.ContentId – Specifies the content ID of the client bundle that the current bundle depends on. On deploying a client bundle with such requirement, the repository searches through all client bundles with a specific content ID and selects the most suitable one for the device.
SoftwarePlatform.Component.GlobalId – Specifies the global ID of the client bundle that is required by the current software component for its proper work.
BundleAttribute.Filter – Specifies the string representation of an LDAP filter that defines some more specific device or client bundle capabilities and follows the syntax defined in RFC1960 - A String Representation of LDAP Search Filters. This requirement property is currently used by RM only for representation of complex OBR filter requirements. You can manually define such a requirement for any bundle, being internal or external. For more information refer to the "OBR Integration" section below.
RM offers ready capability requirement properties with all necessary relations set. For further information refer to the Device Platform Capabilities guide.
Resolving Client Bundle Dependencies
Resolving client bundle dependencies during the import process is done in two basic ways. The two types of resolving depend on the initial set of involved client bundles. The one resolving type takes only one client bundle through its unique bundle identifier and checks whether the device capabilities satisfy its required capabilities. The second resolving type takes all client bundles with a given content identifier determining the most suitable of them to be deployed on the client device.
A client bundle can depend on the capabilities provided by another client bundle which is specified with the specific requirement properties described in the section above. They indicate the dependence of the client bundle from another client bundle and automatically lead to resolving the dependencies of the second client bundle.
A requirement can be optional or multiple. If a requirement is defined as optional, the dependency resolving process will be successful even if this requirement is not satisfied. In case a requirement is specified as multiple, the repository tries to find out more than one solution for the requirement and considers them all useful. For example, if an OSGi bundle states a specific package as multiple requirement, all discovered OSGi bundles that satisfy this requirement are installed on the client device.
A client bundle can also declare that it serves as an extension to another client bundle, i.e to define an extends requirement. For example, a fragment bundle can state through the extends requirement its host bundle. The extend relationship presumes that the extended client bundle is not aware of its extensions until it requires its dependencies to be resolved. Then during the resolving of the host bundle, all capabilities and requirements of the fragment bundle are attached to the requirements and capabilities of its host.
Furthermore, the repository allows a client bundle to declare explicitly incompatibility requirements. These requirement can be related to the device capabilities, as well as to other client bundles. During the deployment process if the incompatibility requirements match the device or other client bundles capabilities, the specific client bundle is considered not suitable for deployment on the device.
The solution results returned for a client bundle during the resolving process depend on the sharing options defined by the involved client bundles. For example, if a client bundle requires a capability provided by another client bundle that is not in the visibility scope of the current RM user, the resolving process fails. Refer to the "Sharing Options" section further in this document for more information.
The RM offers an opportunity for customization of the resolving process according to the developer's needs. For further information refer to the Managing Deployment Units Programmer Guide.
State
The client bundle state indicates whether the application can be deployed on client devices. The Software Repository distinguishes three states of a client bundle:
Importing – Indicates that the client bundle is still not imported in the Software Repository or it is updating. The end users cannot use it if it is in this state.
Imported – Indicates that the client bundle is saved in the Software Repository but cannot be deployed on a client device.
Published – Indicates that the client bundle is added to the Software Repository and the administrator approves this. Its previous state should be imported. It is not recommended to publish currently processing client bundles.
Organizing Client Bundles
Deployment units, including their client bundles, can be organized in groups to fit the logical classification of the user.
For example, a developer can use Catalog Properties to group client bundles into specific categories or according to their deployment policy (see the "Catalog Properties" section from
Software Repository Management through the console
user guide).
Client bundles can be also logically organized using their content ID (see the "Client Bundle Identifiers" section above).
Access Roles
Access roles for the Software Repository determine what an RM user can do with the client bundles there:
If participating in the Bundle – View group, the user can view those client bundles, along with their attributes, for which he or she has the access role explicitly set. By default, members of the administration group and users having the "manage" permissions for the repository are allowed to view stored client bundles.
If participating in the Bundle – Import group, the user can add client bundles to the Software Repository. By default, all RM users can add client bundles to the repository. Users who imported a client bundle in the repository are automatically granted the "view" and "manage" permissions for that software component.
If participating in the Bundle – Manager group, the user can modify and view client bundles in the Software Repository. By default, users participating in the administration group (i.e. device operators) have management right for all bundles in the repository and users who have imported client bundles to the repository have management rights limited to the imported client bundles.
See "Handling Client Bundle Access Roles" section of the
Software Repository Management through the console
user guide for more information.
Sharing Options
The sharing options of a client bundle are used to determine the scope of RM users who have access to it. Actually, these options offer a more user-friendly and convenient way to define user view access rights for specific client bundles.
Sharing options are separated as follows:
Private (accessible only by the bundle owner) – Indicates that the client bundle is accessible only by the user who imported it in the repository.
Public (accessible to all users) – Indicates that all RM users can access the client bundle. Though depending on their access roles they have different permissions for the client bundle.
Shared with specified users – Shows that only the specified RM users have access to the contents of the client bundle. Their permissions to manage the client bundle are defined by the access roles they have.
Composition
A composition is a deployment unit built by client bundles from different concrete types (refer to "General and Concrete Type" section above). Each client bundle that takes part in a composition can exist independently, while the composition needs all its components to exist.
A client bundle may have properties that are valid only within a composition. For example, in a composition of type "Bundle Group" each client bundle included is provided with additional properties:
startup order – Indicates the sequence in which client bundles should be handled when the composition is installed on a device.
Figure 3: . Software Repository Architecture.
optional – Such component will be installed only on suitable platform and if it is not appropriate for some platform, will not prevent installation of other components.
Figure 4: . Software Repository Architecture.
lazy start – Represents the ability to install components of Bundle Groups with lazy activation policy.
Figure 5: . Software Repository Architecture.
Provisioning Archives
The Provisioning Archive (PAR) files have a .par extension and contain a provisioning descriptor (a XML). The term provisioning refers to the activities of advertising client bundles to a client device, and to the process of delivering the bundles to the device.
The PAR format is a file format for packaging multiple client (OSGi-compliant) bundles, similar to the Java ARchive format and based on the familiar ZIP format. The PAR format is defined by JSR 124, J2EE Client Provisioning.
PAR Format Overview in Regard to Remote Manager
By specification, a Provisioning Archive (PAR) file can contain one or more logical client bundles, based on the Java ARchive format. The Remote Manager (RM) server will provide these client bundles. The archive also contains an XML file under the ZIP entry name: /META-INF/provisioning.xml. This XML file is known as a provisioning descriptor and it contains information, describing the bundles to be included within the archive.
If the client bundle does not have a provisioning descriptor, it must hold a content file providing information about the content that will be delivered by the provisioning server. If the PAR does not contain a content file, the provisioning descriptor must provide the correct URLs for the provisioning server to obtain the bundle's content (as a <content-file> or a <descriptor-file> entry). The content URLs can be absolute (i.e. they contain a scheme, such as http://_ or _ftp://), or relative to the root of the PAR file and must begin with leading '/'.
Following is a DTD-like description of the provisioning descriptor part concerning client bundles.
|
Provisioning Descriptor Element |
Description |
|
<!ELEMENT client-bundle(content-id, version, bundle-type , (content-file descriptor-file) , tool-descriptions?, device-requirement*, catalog-property*)> |
The <client-bundle> tag of the provisioning descriptor format. |
|
Elements describing the properties of a client bundle |
|
|
<!ELEMENT content-id (#PCDATA)> |
Contains the content ID, which uniquely identifies the bundle, according to the file descriptor mime type. |
|
<!ELEMENT version (#PCDATA)> |
Contains a string indicating the version of the application the client bundle represents (mime-type="mprm/bundle-descriptor") |
|
<!ELEMENT bundle-type (#PCDATA)> |
Contains a string that categorizes the type of application or content held in the bundle. Set it to APPLICATION in RM. |
|
<!ELEMENT content-file (#PCDATA)> |
Contains the URI of the client bundle content file - absolute or relative to the PAR file root. |
|
<!ELEMENT descriptor-file (#PCDATA)> |
Contains the URI of the client bundle descriptor file - absolute or relative to the PAR file root. |
|
<!ATTLIST descriptor-file mime-type CDATA #IMPLIED> |
Contains the descriptor MIME type. |
|
<!ATTLIST content-file mime-type CDATA #IMPLIED> |
Contains the content-file MIME type. For example, it can have the following RM-related values for client bundle with concrete type:
|
|
<!ELEMENT device-requirement (requirement-name, requirement-value)> |
Contains information about all requirements that the client bundle has towards the capabilities of devices. |
|
<!ELEMENT requirement-name (#PCDATA)> |
Contains the requirement name. |
|
<!ELEMENT requirement-value (#PCDATA)> |
Contains the requirement value. |
|
<!ELEMENT catalog-property (property-name, property-value)> |
Contains the various catalog properties that can be used to organize bundles. For example, catalog properties can be used to assign bundles into categories understandable to users, or to indicate the billing model to be used for each client bundle. Catalog properties are unique by name. |
|
<!ELEMENT property-name (#PCDATA)> |
Contains the catalog property name. |
|
<!ELEMENT property-value (#PCDATA)> |
Contains the catalog property value. |
OBR Integration
Overview
The growing need for quick and easy access to OSGi deployment units provided by different open source communities has led to introducing a support for linking external repositories to the RM Software Repository. Such repositories are the OSGi Bundle Repositories (OBR) which are defined in the RFC-0112 Bundle Repository specification introduced by the OSGi Alliance. An external OBR is described in specific XML file which follows the XML Schema defined in the specification. It may contain metadata for different client bundles and also referrals to other repository XML files, i.e. other external repositories.
When the RM Software Repository is linked to an external repository, the external client bundles are added to the internal repository by means of metadata and URLs to external resources content. External client bundles cannot be removed or updated as the rest of the stored deployment units. Only removing the link to the external OBR leads to removing its external client bundles from the RM repository. The RM Software Repository periodically retrieves the information from the repository XML file in order to update, if needed, the metadata it stores for the external client bundles.
The RM Software Repository provides the External Repository Configuration to allow its configuration in regards to the external OBRs. Further information about how to configure the RM repository is enclosed in the next section.
Setup and Configuration
The OBR integration functionality is handled by the OBR Integration bundle from the Software Repository package (packages/sr/sr.obr.be.jar) on the backend hosts' frameworks. This bundle is started by default.
The OBR Integration bundle provides a configuration factory with name External Repository Configuration and FPID: mprm.external.repository. Each configuration instance from this factory is dedicated to a specific external repository. Hence, to link a new repository to RM, create a new instance from the External Repository Configuration and configure the integration if needed.
A configuration instance contains the following properties:
|
Property ID |
User-Friendly Name |
Type |
Description |
|
external.repository.url |
External Repository URL |
String |
Indicates the URL to the external OBR XML file. |
|
external.repository.depth |
External Repository Depth |
int |
Holds the maximum number of referrals this external OBR acknowledges. If the value of this property is set to 1, the external repository will not follow any referrals to other external OBRs defined in its XML file. If the depth is greater than one, the external OBR must follow as many referrals it contains as the property value. The default value is 1. |
|
external.repository.time |
Time Interval |
int |
Contains the time interval in minutes used by the Software Repository to update the external bundle metadata from the corresponding external repository. The default value is 10. |
The External Repository Configuration can be managed in terms of the OSGi Configuration Admin Service Specification through the console System Configuration dashboard view. Select the Configurations tab and locate the External Repository Configuration configuration factory.
Figure 6: . Configuring the access of the RM Software Repository to external repositories.
To create a new configuration out of the configuration factory, right-click the External Repository Configuration node and select Create Configuration from the popup menu. The newly created configuration will appear by its persistent identifier (PID) and you can edit its properties described above. Right-click on a configuration instance and use the Delete configuration option from the popup menu to delete a selected configuration instance from the configurations list and therefore remove the link with an external OBR.
The Save button applies all the changes made to the configuration instance(s).
User Interface
The console provides a full access to the functionality of the Software Repository. You can find more information on configuring the Software Repository with the console in Software Repository Management through the console.
Software Repository API
The Software Repository API allows adding various types of software components and managing their properties. In addition, it enables developing custom software component providers which will extend the managed file types supported by the Software Repository. For further information refer to the documents in the Developer Guide.