Bundle Requirements

This document describes the concepts behind bundle requirements definition and management.

Contents:

Overview
Requirement XML
Bundle-Requirements Manifest Header

Overview

Every bundle can describe its own requirements for system resources, security permissions and runtime platforms. Different modules - resource manager, permission manager or platform manager can analyze and resolve these requirements.

A resource requirement includes the name of the resource and the amount of this resource required
A permission requirement includes the name of the permission, its target and requested actions.
A platform requirement includes the platform properties that identify the target platform and the modifications in the configuration of the bundle which take place when the bundle is deployed on the platform.

ProSyst offers managers for all the three types of requirements:

The resource manager of the mBS framework manages resource requirements.
The permission admin, included in the mBS Security package, handles permission requirements. More information about permission requirements is available in the Security package documentation.
Note: The use of permission requirements is reasonable only with releases of the mBS framework, compliant with Release 3 of the OSGi Service Platform specifications. With the current release of the mBS framework, which is compliant with Release 4 of the specifications, use local permissions for defining the maximum set of permission a bundle should have.
The gateway manager in cooperation with the bundle inventory of the mPower Remote Manager 3.3 by ProSyst uses platform requirements when a bundle is to be deployed on a specific platform. mPRM keeps information about the platform of each OSGi-enabled device added to it. For further details on how platforms requirements are defined and used, refer to the documentation of the mPower Remote Manager 3.3 .

Requirement XML

An XML file - a requirement XML - holds all managed requirements of a bundle including the ones for system resources. Therefore, different managers can use the information in it to allow or restrict the operation of the bundle.

Note: Describing permission requirements in a requirement XML is needed only if the target bundle is compliant with the OSGi Service Platform Specification Release 3. For Release 4 compliant bundles, this is not required - you are expected to describe required permissions (termed as local permisisons) in an OSGI-INF/permissions.perm file within the bundle JAR file, whose syntax is defined by the OSGi standard.

Following is the document type description (DTD) of the resource requirements section within the requirement XML:

DTD Element	Description
<!ELEMENT BundleRequirements Resources?, Platforms?, Permissions?)>	The BundleRequirements element marks the XML file as a collection of bundle requirements. This element may contain system resources wrapped by the Resources tag, platforms wrapped by the Platforms tag, and permissions wrapped by the Permissions tag.
Elements Related to Resource Requirements
<!ELEMENT Resources (VM+)>	Marks the section as a list of resource requirements. This element must have at least one VM entry.
<!ELEMENT VM (Resource+)>	Contains the resources whose allocation is managed by the specified virtual machine. A VM entry must have at least one Resource element. If there is a resource, which can be managed by more than one VM (for example, `Thread` creation can be managed using the JDK1.1 API), then it should be enclosed by a VM tag with no attribute.
<!ATTLIST VM name CDATA #IMPLIED>	Identifies a specific virtual machine by its name. For example, you may put the <VM name="J9"> tag for the J9 VM.
<!ELEMENT Resource (Name, Requirement)>	Contains the properties of the required resource. It consists of a Name and a Requirement.
<!ELEMENT Name (#PCDATA)>	Indicates the name of the required resource. For example, for the J9 VM this can be "NewSegmentSize".
<!ELEMENT Requirement (#PCDATA)>	Shows the amount of the resource required by the bundle.
Elements Related to Platform Requirements
<!ELEMENT Platforms (Platform+)>	Indicates that the block that follows describes the platform requirements of the bundle.
<!ELEMENT Platform (Description?, ConfigMods?)>	Keeps information about a single platform. This includes description of the platform and of the associated conditional configuration properties.
<!ATTLIST Platform id CDATA #IMPLIED>	Uniquely identifies the platform through an ID.
<!ELEMENT Description (ProfileProperty+)>	Indicates that the information that follows is about the platform properties
<!ELEMENT ProfileProperty (Name, Value)>	Defines a platform property.
<!ELEMENT Name (#PCDATA)>	Contains the name of the property. It should correspond to the conventional properties for platform profiles.
<!ELEMENT Value (#PCDATA)>	Provides the value of the property. Should be a legal string for OS, processor, VM, etc.
<!ELEMENT ConfigMods (Configuration+)>	Indicates that the information that follows is about the conditional configuration set for the specified platform.
<!ELEMENT Configuration (AddProperty+)>	Indicates the following data is about a conditional configuration.
<!ATTLIST Configuration pid CDATA #REQUIRED>	Specifies the service PID of the original bundle configuration which is to be replaced with this conditional configuration.
<!ELEMENT AddProperty (Id, ConfigValue)>	Specifies the property to be changed by conditional configuration.
<!ELEMENT Id (#PCDATA)>	Contains the ID of the property to change.
<!ELEMENT ConfigValue (Scalar \| Array)>	Holds the format of the new value of the property.
<!ELEMENT Array (Scalar+)>	Indicates that the value is an array
<!ELEMENT Scalar (#PCDATA)>	Holds the value of the property if it is a scalar or the value of an array element if the property is an array.
Elements Related to Permission Requirements
<!ELEMENT Permissions (Permission+)>	Indicates that the block that follows describes the permissions required by the bundle.
<!ELEMENT Permission (Type, (Name, Action)?)>	Describes a permissions.
<!ELEMENT Type (#PCDATA)>	Indicates the full Java class name of the requested permission.
<!ELEMENT Name (#PCDATA)>	Indicates the full name of the permission target.
<!ELEMENT Action (#PCDATA)>	Defines the action that the bundle will execute on the permission target. It is permission-specific.

Note: The bundle requirement XML parser expects that the XML file is in ASCII format. This violation of XML specification is in order to make things simpler as well as provide a quick and cheap parsing of the file. Included data does not require a more complicated encoding.

Tip: You can use the Bundle Requirement utility to examine the contents of requirement XMLs.

Bundle-Requirements Manifest Header

The location of this file within the bundle JAR is indicated in the manifest header Bundle-Requirements:

"Bundle-Requirements" := 1*(<location of xml file> +(;requirement=<type of requirement>))

where:

<location of xml file> is the location of the requirement XML within the bundle JAR.
<type of requirement> indicates the type of requirements in the XML. It can be "resources", "permissions" and/or "platforms".

Note: You can have more than one requirement XML in a bundle JAR. For example, a bundle can provide separate XMLs for its permission and resource requirements and then use the requirements token in the Bundle-Requirements header to indicate the difference.

References

Framework Architecture