134 Subsystem Service Specification

134.1 Introduction

The OSGi Core Release 7 specifies a life-cycle model where bundles can be installed, resolved, and started in order to provide their own classes and services as well as use those provided by other bundles in the system. In the core framework, the bundle is the coarsest deployment unit that a management agent is able to work with; however, oftentimes it is necessary to work with collections of bundles and other types of resources, such as subsystems and implementation specific resources. For example, a collection of bundles may correspond to a particular feature of a middleware product, such as a Web container. The applications deployed to that container may also be developed as a collection of bundles that an administrator is required to manage as a consistent whole. The Subsystems specification provides a declarative model for defining resource collections, including bundles, and an API for installing and managing those collections of resources.

Many use cases only require unscoped resource collections where all provided capabilities are freely exported to and all required capabilities are freely imported from the system. However, in some cases, it is important to allow the exporting of provided capabilities to be scoped such that they can only be used by a subset of resources in the system. It may also be necessary to restrict the importing of required capabilities from outside the collection to ensure its internal capabilities are always preferred over capabilities outside the collection. For example, applications running on a Web application server or in a cloud environment may be deployed to the same server instance. The side-effects of co-locating applications on the same server must be minimized, and scoping is used to ensure each application does not use the classes and services of the others.

The framework provides hooks for influencing resolution, and access to bundles and services. These framework hooks may be used to implement scoping for a collection of bundles. The Subsystems specification provides a higher-level declarative model for defining scoping for collections of resources, including bundles.

When deploying a collection of bundles in an OSGi framework, gaps can exist between the requirements of the bundles and the capabilities provided by the target runtime. Management agents are responsible for ensuring additional bundles are installed to plug these gaps such that the collection of bundles will resolve and run. The [10] Resolver Service Specification and Repository Service Specification help management agents address these needs but do not cover how deployment works for resource collections, especially when those collections are scoped. Scoping affects requirement and capability resolution and therefore affects the choice of resources. The Subsystems specification defines resolution and provisioning rules to help management agents consistently deploy collections of resources. The specification also defines a format for developers and testers to provide predetermined deployment resolutions to help ensure consistency between test and production environments.

134.1.1 Essentials

  • Collections - Allow the management of a collection of resources as a whole.

  • Scoping - Provide support for isolating resources in the collection such that a subset of their capabilities (for example packages and services) are available to satisfy requirements outside the Subsystem and a subset of their requirements are able to resolve to capabilities provided outside the Subsystem.

  • Sharing - Allow Scoped Subsystems to share their resources with others and share resources from others.

  • Dynamic - Provide life cycle information to users of Subsystems and be able to react to changes in the state of the environment in which a Subsystem is deployed.

  • Flexible - Enable a flexible definition with subsequent resolution to determine the resources to be used.

  • Deterministic - Enable the choice of resources deployed for a Subsystem to be determined ahead of deployment.

  • Life-cycle - Define a life cycle for a Subsystem describing how it affects the Subsystem's resources and allow the life cycle to be observed.

  • Reflective - Allow discovery of runtime structural and state information.

  • Resolution - Allow the resolution of a flexible definition during installation to determine the resources to be used.

  • Recursive - Allow Subsystems to be defined in terms of other Subsystems.

134.1.2 Entities

  • Subsystem - A collection of resources, such as bundles, or other Subsystems, administered as a whole through a Subsystem service.

  • Subsystem Manifest - A manifest used to provide a Subsystem definition.

  • Deployment Manifest - A manifest used to provide a deployment definition for a Subsystem. The definition identifies the exact resources to be deployed for the Subsystem.

  • Subsystem Archive - A zip file with an .esa extension that describes a Subsystem definition. It may include the Subsystem Manifest, Deployment Manifest, or resource files that constitute the Subsystem.

  • Resource - An element which may be used in the composition of a Subsystem, such as a bundle or another Subsystem.

  • Repository - A service that is used to discover a Subsystem's content and dependencies. The repository service is described in the Repository Service Specification.

  • Resolver - A service used to resolve requirements against capabilities to determine the resources required by a Subsystem. The resolver service is described in the [10] Resolver Service Specification.

  • Constituent - A resource that belongs to one or more Subsystems.

Figure 134.1 Entities org.osgi.service.subsystem

Entities org.osgi.service.subsystem

134.1.3 Synopsis

The OSGi framework does not provide any support for managing collections of resources. Management of collections of resources is enabled by a Subsystems implementation. When a Subsystems implementation is installed into the framework, it registers a Subsystem service. This service represents the framework as the Root Subsystem, which is a Subsystem that provides the capability to install and manage other child Subsystems, and is the parent of those Subsystems, but does not itself have a parent.

A Subsystem Archive provides a definition of a Subsystem that is read by the Subsystem implementation as part of installation. The Subsystem is packaged in a Subsystem Archive (.esa) file which is the Subsystem equivalent of a bundle .jar file. The Subsystem definition can be described using a Subsystem Manifest or defaulted based on the name and contents of the Subsystem Archive. Installing a new Subsystem results in another Subsystem service being registered to represent that Subsystem in the runtime. Each Subsystem service enables management and reflection of the Subsystem it represents.

A Subsystem Manifest allows flexibility in the identification of the Subsystem's content resources through version ranges and optionality. The exact versions to be deployed and any required dependencies (resources required to satisfy unresolved requirements of the Subsystem's content resources) can be identified in an optional Deployment Manifest. The corresponding resource binaries can be packaged in the Subsystem Archive, or found in a repository. Depending on the type of Subsystem the Subsystem Manifest may describe a sharing policy for the Subsystem, such as the packages or services the Subsystem exports or imports. The Deployment Manifest also describes the sharing policy details for the Subsystem and is defined by the type of Subsystem and the sharing policy described in the Subsystem Manifest.

A Subsystem that does not have a Deployment Manifest has its deployment details calculated during installation. This may be done using the [10] Resolver Service Specification, if available. The starting set of requirements to be resolved are those identifying the Subsystem content (that is, requirements for content resources). The Subsystems implementation provides a resolve context that implements the policy for the Subsystem and consults the configured Repository services to find candidates to satisfy requirements.

This resolve context can also represent the target deployment environment, which might be a live framework, or a static definition of a target runtime. The resulting resolution is used to determine the exact resources to provision, equivalent to those identified in the deployment manifest. If any of the Repository or Resolver services are unavailable, then a Subsystem implementation can use its own means to determine the deployment, or fail the installation.

A Subsystem definition includes sharing policy configuration to scope requirements and capabilities visibility into and out of a Subsystem. The Subsystems specification defines the concept of Subsystem types to help simplify the configuration of sharing policies. Each type has its own default sharing policy, for example, to forbid the sharing of capabilities out, or to share all capabilities in. Three Subsystem types are defined in the Subsystems specification: application, composite and feature.

An Application Subsystem is a Scoped Subsystem with a sharing policy associated with what is often considered to be an application. An application does not share (export) any capabilities. Any requirements that are not satisfied by the application's contents are automatically imported from outside the application.

A Composite Subsystem is a Scoped Subsystem with a fully explicit sharing policy. Capabilities may be explicitly imported into, or exported out of, the Composite Subsystem.

A Feature Subsystem is an Unscoped Subsystem and so all its requirements and capabilities are shared.

This specification allows for other types to be defined, including ones outside this specification.

134.2 Subsystems

This specification defines a unit of installation called a Subsystem. A Subsystem is comprised of resources, including OSGi bundles and other Subsystems, which together can provide functions to end users.

A Subsystem is deployed as a Subsystem Archive (.esa) file. Subsystem Archives are used to store Subsystems and optionally their resources in a standard ZIP-based file format. This format is defined in [4] Zip File Format. Subsystems normally use the Subsystem Archive extension of .esa but are not required to. However there is a special MIME type reserved for OSGi Subsystems that can be used to distinguish Subsystems from normal ZIP files. This MIME type is:

application/vnd.osgi.subsystem

The type is defined in [5] IANA application/vnd.osgi.subsystem. A Subsystem is a ZIP file that:

  • Contains zero or more resources. These resources may be OSGi bundles or other Subsystems. Subsystems may be nested or included to any depth.

  • Contains an optional Subsystem Manifest named OSGI-INF/SUBSYSTEM.MF. The Subsystem Manifest describes the contents of the Subsystem Archive and provides information about the Subsystem. The Subsystem Archive uses headers to specify information that the Subsystems implementation needs to install, resolve and start the Subsystem correctly. For example, it can state the list of content resources that comprise the Subsystem and the Subsystem's type.

  • Contains an optional Deployment Manifest file named OSGI-INF/DEPLOYMENT.MF. The Deployment Manifest describes the content resources, dependencies, and sharing policy that need to be provisioned to satisfy the Subsystem definition and ultimately allow it to resolve at runtime.

The Subsystem and Deployment Manifest follow the JAR manifest format (version 1.0), but with the following relaxed rules:

  • No limit on the line length. Lines are allowed to exceed the JAR manifest maximum of 72 bytes.

  • The last line is not required to be a carriage-return new-line combination.

  • There is only one section in the manifest (the main section). A Subsystems implementation is free to ignore other sections of the manifest.

Once a Subsystem is started, its functionality is provided. Depending on the type of Subsystem it may expose capabilities, such as packages and services, to other resources installed in the OSGi framework.

134.2.1 Subsystem Manifest Headers

A Subsystem can carry descriptive information about itself in the Subsystem manifest file contained in its Subsystem Archive under the name OSGI-INF/SUBSYSTEM.MF. This specification defines Subsystem manifest headers, such as Subsystem-SymbolicName and Subsystem-Version, which Subsystem developers use to supply descriptive information about a Subsystem. A Subsystems implementation must:

  • Process the main section of the manifest. Any other sections of the manifest can be ignored.

  • Ignore unknown manifest headers. The Subsystem developer can define additional manifest headers as needed.

  • Ignore unknown attributes and directives.

All specified manifest headers are listed in the following sections. All headers are optional. Example values are provided to help explain each header (e.g. Export-Package: org.acme.logging; version=1.0).

134.2.1.1 Export-Package: org.acme.logging; version=1.0

The Export-Package header declares the exported packages for a Scoped Subsystem. See Export-Package.

134.2.1.2 Import-Package: org.osgi.util.tracker; version="[1.4, 2.0)"

The Import-Package header declares the imported packages for a Scoped Subsystem. See Import-Package.

134.2.1.3 Preferred-Provider: com.acme.logging

The Preferred-Provider header declares a list bundles and Subsystems which are the providers of capabilities that are preferred when wiring the requirements of a Scoped Subsystem. See Preferred-Provider Header.

134.2.1.4 Provide-Capability: com.acme.dict; from=nl; to=de; version:Version=1.2

The Provide-Capability header declares the capabilities exported for a Scoped Subsystem. See [3] Resource and Wiring.

134.2.1.5 Require-Bundle: com.acme.chess; bundle-version="[1.0,2.0)"

The Require-Bundle header declares the required bundles for a Scoped Subsystem. See Require-Bundle.

134.2.1.6 Require-Capability: osgi.ee; filter:="(osgi.ee=*)"

The Require-Capability header declares the required capabilities for a Scoped Subsystem. See [3] Resource and Wiring.

134.2.1.7 Subsystem-Category: osgi, test, nursery

The Subsystem-Category header identifies the categories of the subsystem as a comma-delimited list.

134.2.1.8 Subsystem-ContactAddress: 2400 Oswego Road, Austin, TX 74563

The Subsystem-ContactAddress header identifies the contact address where problems with the subsystem may be reported; for example, an email address.

134.2.1.9 Subsystem-Content: com.acme.logging

The Subsystem-Content header lists requirements for resources that are considered to be the contents of this Subsystem. See Subsystem-Content Header.

134.2.1.10 Subsystem-Copyright: OSGi (c) 2014

The Subsystem-Copyright header identifies the subsystem's copyright information.

134.2.1.11 Subsystem-Description: The ACME Account Admin Application

The Subsystem-Description header defines a human-readable description for this Subsystem, which can potentially be localized.

134.2.1.12 Subsystem-DocURL: http://www.example.com/Firewall/doc

The Subsystem-DocURL header identifies the subsystem's documentation URL, from which further information about the subsystem may be obtained.

134.2.1.13 Subsystem-ExportService: org.acme.billing.Account; filter:="(user=bob)"

The Subsystem-ExportService header specifies the exported services for a Scoped Subsystem. See Subsystem-ExportService.

134.2.1.14 Subsystem-Icon: /icons/acme-logo.png; size=64

The optional Subsystem-Icon header provides a list of URLs to icons representing this subsystem in different sizes. The following attribute is permitted:

  • size - (integer) Specifies the size of the icon in pixels horizontal. It is recommended to always include a 64x64 icon.

The URLs are interpreted as relative to the subsystem archive. That is, if a URL with a scheme is provided, then this is taken as an absolute URL. Otherwise, the path points to an entry in the subsystem archive file.

134.2.1.15 Subsystem-ImportService: org.acme.billing.Account; filter:="(type=premium)"

The Subsystem-ImportService header specifies the imported services for a Scoped Subsystem. See Subsystem-ImportService.

134.2.1.16 Subsystem-License: http://www.opensource.org/licenses/jabberpl.php

The Subsystem-License header provides an optional machine readable form of license information. The purpose of this header is to automate some of the license processing required by many organizations like for example license acceptance before a subsystem is used. The header is structured to provide the use of unique license naming to merge acceptance requests, as well as links to human readable information about the included licenses. This header is purely informational for management agents and must not be processed by the Subsystems implementation.

The syntax for this header is as follows:

Subsystem-License ::= '<<EXTERNAL>>' | 
                      ( license ( ',' license ) * )
license        ::= name ( ';' license-attr ) *
license-attr   ::= description | link
description    ::= 'description' '=' string
link           ::= 'link' '=' <url>

This header has the following attributes:

  • name - Provides a globally unique name for this license, preferably world wide, but it should at least be unique with respect to the other clauses. The magic name <<EXTERNAL>> is used to indicate that this artifact does not contain any license information but that licensing information is provided in some other way. This is also the default contents of this header.

    Clients of this subsystem can assume that licenses with the same name refer to the same license. This can for example be used to minimize the click through licenses. This name should be the canonical URL of the license, it must not be localized by the translator. This URL does not have to exist but must not be used for later versions of the license. It is recommended to use URLs from [9] Open Source initiative. Other licenses should use the following structure, but this is not mandated:

  http://<domain-name>/licenses/
            <license-name>-<version>.<extension>
  • description - (optional) Provide the description of the license. This is a short description that is usable in a list box on a UI to select more information about the license.

  • link - (optional) Provide a URL to a page that defines or explains the license. If this link is absent, the name field is used for this purpose. The URL is relative to the root of the bundle. That is, it is possible to refer to a file inside the bundle.

If the Subsystem-License statement is absent, then this does not mean that the subsystem is not licensed. Licensing could be handled outside the subsystem and the <<EXTERNAL>> form should be assumed. This header is informational and may not have any legal bearing. Consult a lawyer before using this header to automate licensing processing.

134.2.1.17 Subsystem-Localization: OSGI-INF/l10n/subsystem

The Subsystem-Localization header identifies the default base name of the localization properties files contained in the subsystem archive. The default value is OSGI-INF/l10n/subsystem. Translations are therefore, by default, OSGI-INF/l10n/subsystem_de.properties , OSGI-INF/l10n/subsystem_nl.properties, and so on. The location is relative to the root of the subsystem archive. See Subsystem-Localization Header

134.2.1.18 Subsystem-ManifestVersion: 1

The Subsystem-ManifestVersion header defines that the Subsystem follows the rules of a Subsystems Specification. It is 1 (the default) for this version of the specification. Future versions of the Subsystems Specification can define higher numbers for this header.

134.2.1.19 Subsystem-Name: Account Application

The Subsystem-Name header defines a short, human-readable name for this Subsystem which may be localized. This should be a short, human-readable name that can contain spaces.

134.2.1.20 Subsystem-SymbolicName: com.acme.subsystem.logging

The Subsystem-SymbolicName header specifies a non-localizable name for this Subsystem. The Subsystem symbolic name together with a version identify a Subsystem Definition though a Subsystem can be installed multiple times in a framework. The Subsystem symbolic name should be based on the reverse domain name convention. See Subsystem-SymbolicName Header.

134.2.1.21 Subsystem-Type: osgi.subsystem.application

The Subsystem-Type header specifies the type for this Subsystem. Three types of Subsystems must be supported: osgi.subsystem.application, osgi.subsystem.composite and osgi.subsystem.feature. See Subsystem Identifiers and Type for details about the three different types of Subsystems. See Subsystem-Type Header for more information about the values for the Subsystem-Type header.

134.2.1.22 Subsystem-Vendor: OSGi Alliance

The Subsystem-Vendor header contains a human-readable description of the subsystem vendor.

134.2.1.23 Subsystem-Version: 1.0

The Subsystem-Version header specifies the version of this Subsystem. See Subsystem-Version Header.

134.2.2 Subsystem Identifiers and Type

A Subsystem is identified by a number of names that vary in their Scope:

  • Subsystem identifier - A long that is a Subsystems implementation assigned unique identifier for the full lifetime of an installed Subsystem, even if the framework or the Subsystem's implementation is restarted. Its purpose is to distinguish Subsystems installed in a framework. Subsystem identifiers are assigned in ascending order to Subsystems when they are installed. The getSubsystemId() method returns a Subsystem's identifier.

  • Subsystem location - A name assigned by a management agent to a Subsystem during the installation. This string is normally interpreted as a URL to the Subsystem Archive but this is not mandatory. Within a particular framework, a Subsystem location must be unique. A location string uniquely identifies a Subsystem. The getLocation() method returns a Subsystem's location.

  • Subsystem Symbolic Name and Subsystem Version - A name and version assigned by the developer. The combination of a Subsystem symbolic name and Subsystem version is intended to provide a globally unique identifier for a Subsystem Archive or Subsystem definition. The getSymbolicName() method returns the assigned Subsystem name. The getVersion() method returns the assigned version. Though this pair is intended to be unique, it is developer assigned and there is no verification at runtime that the pair uniquely identifies a Subsystem Archive. It is possible to install a Subsystem multiple times as long as the multiple Subsystem symbolic name and version pairs are isolated from each other by Subsystem sharing policies.

134.2.3 Subsystem-SymbolicName Header

The Subsystem-SymbolicName header specifies the symbolic name of the Subsystem. The Subsystem-SymbolicName header may also specify arbitrary matching attributes. Subsystem-SymbolicName is an optional header; the default value is derived as described in Deriving the Subsystem Identity.

The Subsystem-SymbolicName header must conform to the following syntax:

Subsystem-SymbolicName ::= symbolic-name(';' parameter )*

No directives are defined by this specification for the Subsystem-SymbolicName header. The header allows the use of arbitrary attributes that can be required by the Subsystem-Content header.

134.2.4 Subsystem-Version Header

The Subsystem-Version header is optional and must conform to the following syntax:

Subsystem-Version ::= version

If the Subsystem-Version header is not specified then the default value is derived as described in Deriving the Subsystem Identity.

134.2.5 Subsystem-Type Header

The Subsystem-Type header specifies the type of the Subsystem. Three types of Subsystems are defined by this specification:

  • osgi.subsystem.application

  • osgi.subsystem.composite

  • osgi.subsystem.feature

See Subsystem Types for details about the three different types of Subsystems. Subsystem-Type is an optional header; the default value is osgi.subsystem.application.

The following directive must be recognized for the Subsystem-Type header:

  • provision-policy - (rejectDependencies|acceptDependencies) Directive used to declare if the Subsystem is willing to accept dependencies as constituents. A constituent is the term used to refer to a resource that belongs to one or more Subsystems. It can belong to a Subsystem as a result of being listed as content or, as described here, can have been provisioned into the Subsystem as a dependency. The default policy is rejectDependencies. See Accepting Dependencies for installing and tracking dependencies. The value acceptDependencies must not be used for Feature Subsystems. If a Feature Subsystem attempts to use the acceptDependencies policy then the Subsystem installation must fail. If the provision-policy directive is declared and has any other value besides acceptDependencies or rejectDependencies then the Subsystem installation must fail.

134.2.6 Deriving the Subsystem Identity

If the Subsystem-SymbolicName and Subsystem-Version are not specified, then the following rules are defined for deriving the values of the Subsystem's symbolic name and version. If not otherwise specified, the default value of the version is 0.0.0.

When installing a Subsystem, the following URI syntax must be used as the location string in order to specify default values.

subsystem-uri ::= 'subsystem://' url? '?' params?
params        ::= param ( '&' param )*
param         ::= key '=' value
key           ::= unreserved | escaped
value         ::= unreserved | escaped
url           ::= <see [6] RFC 1738 Uniform Resource Locators> 
escaped       ::= <see [7] Uniform Resource Identifiers (URI): Generic Syntax>
unreserved    ::= <see [7] Uniform Resource Identifiers (URI): Generic Syntax>

The query parameters represent Subsystem Manifest header names and values. Implementations must support the Subsystem-SymbolicName and Subsystem-Version parameters. Implementations can support additional parameters but must fail the installation if any unsupported parameters are included.

As an example, the following Subsystem URI has an embedded URL of:

http://www.foo.com/sub#system.esa

It includes a default symbolic name of com.acme.foo and default version of 1.0.0.

subsystem://http%3A%2F%2Fwww.foo.com%2Fsub%2523system.esa? «
    Subsystem-SymbolicName=com.acme.foo&Subsystem-Version=1.0.0

When installing a Subsystem containing other Subsystem Archives with no symbolic name or version, values will be derived from the Subsystem Archive file or resource name. The syntax is as follows:

subsystem-archive ::= symbolic-name ( '@'version ) '.esa'

If the symbolic name is not provided in the manifest and cannot be computed by any other means then the Subsystem must fail to install.

134.2.7 Subsystem Identity Capability

The Subsystem's symbolic name, version, type and the arbitrary matching attributes specified on the Subsystem-SymbolicName header compose the osgi.identity capability for a Subsystem resource. The osgi.identity capability is provided by a Subsystem resource when contained within a Repository service, see Repository Service Specification. For example:

Subsystem-SymbolicName: org.acme.billing;category=banking
Subsystem-Version:      1.0.0
Subsystem-Type:         osgi.subsystem.composite

The above headers are used to declare a Subsystem of type osgi.subsystem.composite with the symbolic name of org.acme.billing, version of 1.0.0 and arbitrary matching attribute category of banking. This information will also be reflected in the osgi.identity capability of the Subsystem's Resource (org.osgi.resource.Resource). The following osgi.identity capability would be generated for a Subsystem resource from the above headers using the Provide-Capability header syntax. For example:

osgi.identity;
osgi.identity=org.acme.billing;
 version:Version=1.0.0;
 type=osgi.subsystem.composite;
 category=banking

This allows for requirements to be used to search a repository for Subsystems. The following requirement could be used to search for all Subsystems of type osgi.subsystem.composite using the Require-Capability header syntax. For example:

osgi.identity; filter:="(type=osgi.subsystem.composite)"

134.2.8 Subsystem-Localization Header

For consistency and ease of comprehension, the design for localizing subsystem manifest headers follows the approach used by bundles.

134.2.8.1 Localization Properties

A localization entry contains key/value entries for localized information. All headers in a subsystem's manifest can be localized. However, the subsystems implementation must always use the non-localized versions of headers that have subsystem semantics. Note that the use of localization on certain such headers, such as Subsystem-SymbolicName, may cause errors as a value with a % sign will not be valid.

A localization key can be specified as the value of a subsystem's manifest header using the following syntax:

header-value ::= ’%’text
text ::= < any value which is both a valid manifest header value and a valid
    property key name >

For example, consider the following subsystem manifest entries:

Subsystem-Name: %acme subsystem
Subsystem-Description: %acme description
Subsystem-SymbolicName: acme.Subsystem
Acme-Defined-Header: %acme special header

User-defined headers can also be localized. Spaces in the localization keys are explicitly allowed.

The previous example manifest entries could be localized by the following entries in the manifest localization entry OSGI-INF/l10n/subsystem.properties.

# subsystem.properties
acme\ subsystem=The ACME Subsystem
acme\ description=The ACME Subsystem provides all of the ACME \ services
acme\ special\ header=user-defined Acme Data

The above manifest entries could also have French localizations in the manifest localization entry:

OSGI-INF/l10n/subsystem_fr_FR.properties.

134.2.8.2 Locating Localization Entries

The Subsystems implementation must search for localization entries by appending suffixes to the localization base name according to a specified locale and finally appending the .properties suffix. If a translation is not found, the locale must be made more generic by first removing the variant, then the country and finally the language until an entry is found that contains a valid translation. For example, looking up a translation for the locale en_GB_welsh will search in the following order:

OSGI-INF/l10n/subsystem_en_GB_welsh.properties
OSGI-INF/l10n/subsystem_en_GB.properties
OSGI-INF/l10n/subsystem_en.properties
OSGI-INF/l10n/subsystem.properties

134.3 Subsystem Region

A Region provides isolation for a group of one or more Subsystems. Each Subsystem installed must be a member of one and only one Region. A Region consists of one and only one Scoped Subsystem and optionally a set of Unscoped Subsystems. Every Region has one and only one Parent Region, with the exception of the Root Region which has no Parent Region. The Region parent child connections form the Region Tree, which by definition contains no cycles.

Each Region, except the Root Region, has a sharing policy associated with it which is defined by a Scoped Subsystem. A sharing policy consists of two parts:

  • Export Policy - Defines the set of capabilities provided by the constituents contained in the Region that are made available to the parent Region.

  • Import Policy - Defines the set of capabilities which are available in the parent Region that are made available to the child Region.

Figure 134.2 illustrates a set of Regions that contain capabilities and requirements for a capability. For the purposes of this illustration the Subsystems and resources have been omitted.

Figure 134.2 Regions and Import/Export

Regions and Import/Export

In this example some constituent of Region S1Region provide a capability S1X. The S1Region's sharing policy exports the capability S1X to its parent RootRegion. The RootRegion contains a constituent which has a requirement RootX. The export sharing policy of S1Region allows visibility to the capability S1X from the RootRegion which allows requirement RootX to be satisfied by the capability S1X. The S2Region also contains a constituent which has a requirement on S2X. The sharing policy of S2Region imports the capability X from its parent Region RootRegion. Since RootRegion has visibility to the capability S1X this allows S2Region to also have visibility to capability S1X through its import sharing policy which allows requirement S2X to be satisfied by the capability S1X.

Sharing policies of the Regions allow for a capability to be shared across an arbitrary number of Regions. For those familiar with the Region digraph, see [8] Equinox Region Digraph, the connections between Subsystem Regions is more restrictive than what the full Region digraph specification allows. A visibility path is the path over the sharing policies of the Region tree from a requirement to a capability that allows a requirement to get wired to a capability. Since all (non-Root) Regions have one and only one Parent Region the visibility paths over the sharing policies between a requirement and a capability is limited to 0 or 1. Figure 134.3 is another figure that illustrates a capability being shared across many different Regions.

Figure 134.3 Regions and Sharing Capabilities

Regions and Sharing Capabilities

In this example the capability S3X is exported by the S3Region sharing policy to its parent S1Region. S1Region also exports X to its parent RootRegion. Then S2Region imports X from its parent RootRegion and finally S4Region imports X from its parent S2Region. The visibility path from requirement S4X to capability S3X is the following: S4 S2 Root S1 S3.

Notice that in this example the S5Region also has a sharing policy that imports X from its parent S3Region. Child Regions are allowed to import any capability to which the Parent Region has visibility. This is true even if the Parent Region does not export the capability. Regions can selectively choose what capabilities they want to expose (or export) to their Parent Region. Child Regions also can selectively choose what capabilities they want to be exposed to (or import) from their Parent Region. A Parent Region has no control over what capabilities its children have visibility. Similarly a Parent Region has no control over what capabilities a Child Region is allowed to export to the Parent Region. In other words, a Parent Region must give a Child Region everything the Child Region asks for (if the Parent Region has access to it) and a Parent Region must accept everything a Child Region offers to the Parent Region.

134.4 Subsystem Relationships

Subsystems installed into a framework become part of the Subsystem graph. The Subsystem graph may be thought of as is directed acyclic graph with one and only one source vertex, which is the Root Subsystem. The edges have the child as the head and parent as the tail (parentchild). This is depicted in Figure 134.4.

Figure 134.4 Parent Child Relationship

Parent Child Relationship

A Subsystem installed into or included within one or more Subsystems is called a child Subsystem. A Subsystem which has one or more child Subsystem(s) installed or included in it is called a parent Subsystem. Note that a Subsystem may be both a parent and child Subsystem. The Subsystem graph has the following rules:

  • There is one and only one source vertex (i.e. a Subsystem with no parents), which is the Root Subsystem.

  • The Root Subsystem is considered a Scoped Subsystem of type application with a provision-policy of acceptDependencies.

  • The Root Subsystem has a symbolic name of org.osgi.service.subsystem.root, version 1.1, Subsystem identifier of 0, and a location of

    subsystem://?Subsystem-SymbolicName=org.osgi.service.subsystem.root& «
        Subsystem-Version=1.1
  • The Root Subsystem always exists when a Subsystems implementation is active, even if no other Subsystems are installed and all initial bundles installed into the framework along with the Subsystems implementation are considered content resources of the Root Subsystem.

  • All other (non-root) Subsystems must have one or more parent Subsystems. This implies that there are no orphan Subsystems (except the Root Subsystem) and the Subsystem graph is fully connected.

  • All parents of a Subsystem belong to the same Region.

  • An Unscoped Subsystem must belong to the same Region to which its parents belong.

  • A Scoped Subsystem (other than the Root Subsystem) must belong to a child Region of the Region to which the Subsystem's parents belong.

When a Subsystem is installed using a Subsystem service install(String) or install(String,InputStream) method the Subsystem resource becomes a constituent of the Subsystem which the install method was called on. The Subsystem resource is the Subsystem Archive and may be retrieved by calling the Subsystem service getConstituents() method. Figure 134.4 illustrates the Root Subsystem with initial bundles A, B, SI (Subsystems implementation, may be multiple bundles), and the system bundle (identifier 0).

Figure 134.5 Subsystem resources

Subsystem resources

In Figure 134.5 Bundles A, B and SI are considered constituents of the Root Subsystem. The system bundle is also considered to be a constituent of the Root Subsystem (bundle zero). A Subsystem service R is registered that represents the Root Subsystem. When Subsystems are installed using the Root Subsystem then these Subsystem resources become constituents of the Root Subsystem and the Subsystems become child Subsystems of the Root Subsystem. For example, Figure 134.6 illustrates the Root Subsystem with Scoped Subsystem S1 with constituent bundles C and D and Scoped Subsystem S2 with constituent bundles E and F:

Figure 134.6 Subsystems

Subsystems

The two Subsystems S1 and S2 have the same parent and Subsystems S1 and S2 are children of the Root Subsystem. Figure 134.7 shows a more complicated tree that has both Scoped and Unscoped Subsystems installed. This figure omits the constituent resources and Subsystem services:

Figure 134.7 Parent Child Relationship with Unscoped Subsystems

Parent Child Relationship with Unscoped Subsystems

134.4.1 Prevent Cycles and Recursion

It is possible to end up with cycles in the parent child relationships between Subsystems contained in the same Region. Figure 134.8 illustrates this.

Figure 134.8 Subsystems and cycles

Subsystems and cycles

In this example Subsystem S1 has been installed. The Scoped Subsystem S1 has included in its constituents the Unscoped Subsystems U1 and U2. Furthermore U1 has included the Unscoped Subsystem U2 as a constituent and U2 has included the Unscoped Subsystem U1 as a constituent. This causes Unscoped Subsystem U1 to have parents S1 and U2 and Unscoped Subsystem U2 to have parents S1 and U1. There is now a cycle between the Subsystems U1 and U2. Subsystems implementations must detect this cycle and fail the installation of such a degenerative Subsystem. The top level Subsystem being installed must fail the install operation by throwing a Subsystem Exception. In this case the install operation of the S1 Subsystem must fail with a Subsystem Exception being thrown.

Cycles may also exist in the definition of Scoped Subsystems which includes other child Subsystems. Figure 134.9 illustrates this.

Figure 134.9 Scoped Subsystems and cycles

Scoped Subsystems and cycles

In this example the Scoped Subsystem S1 includes as a child the Scoped Subsystem S2. The S2 Subsystem also includes as a child the Scoped Subsystem S1. Subsystems implementations must detect this and fail the installation of such a degenerative Subsystem. The top level Subsystem being installed must fail the install operation by throwing a Subsystem Exception. In this case the install operation of the first S1 Subsystem must fail by throwing a Subsystem Exception.

134.5 Determining Content

A Subsystem definition may declare different types of content resources. A Subsystems implementation may support additional types, but the following types must be supported:

  • osgi.bundle

  • osgi.fragment

  • osgi.subsystem.application

  • osgi.subsystem.feature

  • osgi.subsystem.composite

A Subsystems implementation is free to support additional content types as value-add, but an implementation is required to fail the installation of a Subsystem which declares content resource types which are not recognized by the implementation.

The individual content resources may be specified in the following ways:

  • The Subsystem-Content header, or

  • The entries of the Subsystem Local Repository, see Resource Repositories.

134.5.1 Subsystem-Content Header

The Subsystem-Content header contains a list of symbolic names, with optional attribute and directive assertions. Each element specifies a single resource that is to be a content resource of the Subsystem. See also Discovering Content Resources. The Subsystem-Content header must conform to the following syntax:

Subsystem-Content ::= resource ( ','resource )*
resource          ::= symbolic-name ( ';' parameter )*

The Subsystem-Content header may specify the following directives:

  • resolution - (mandatory| optional) A mandatory content resource prevents the Subsystem from successfully installing when the constituent cannot be found (or satisfied); an optional content resource allows a Subsystem to successfully install even if the content cannot be found (or satisfied). The default value is mandatory.

  • start-order - (Integer >= 1) Specifies the start order of the content resource in relation to other content resources of the Subsystem. See Start Order.

The Subsystem-Content header may specify the following architected matching attributes as well as any arbitrary matching attributes:

  • version - (Version) A version range used to select the version of the resource to use. This follows the OSGi version range scheme, including the default value of 0.0.0.

  • type - Indicates the type of the content. It is recommended that a reverse domain name convention is used unless those types and their processing is standardized by the OSGi Alliance, for example bundles. The default type is osgi.bundle. A Subsystems implementation may support additional types, but the following types must be supported:

    • osgi.bundle

    • osgi.fragment

    • osgi.subsystem.application

    • osgi.subsystem.composite

    • osgi.subsystem.feature

For example, the following header specifies three Subsystem constituents:

Subsystem-Content:
    org.acme.billing.impl;
        type=osgi.bundle;
        version=1.0,
    org.acme.billing.frag;
        type=osgi.fragment;
        version=1.0,
    org.acme.billing.credit.subsystem;
        type=osgi.subsystem.composite;
        version=1.0

The above header specifies three content resources of a Subsystem:

  • A bundle resource with the symbolic name org.acme.billing.impl at version 1.0 or greater

  • A fragment resource with the symbolic name org.acme.billing.frag at version 1.0 or greater

  • A child composite Subsystem resource with the symbolic name org.acme.billing.credit.subsystem at version 1.0 or greater

134.5.2 Subsystem-Content Requirements

Each element of the Subsystem-Content header is used to locate a resource that is to be used as content of the Subsystem. One way of describing the elements of the Subsystem-Content header is in terms of a Requirement using the osgi.identity namespace. The Requirement is defined in [3] Resource and Wiring. To illustrate, a single Subsystem-Content element:

org.acme.billing.impl; 
    type=osgi.bundle;
    version=1.0

This Subsystem-Content header can be converted into the following osgi.identity Requirement with the Require-Capability syntax for illustration:

osgi.identity;
    filter:="(&
        (osgi.identity=org.acme.billing.impl)
        (type=osgi.bundle)
        (version>=1.0)
    )"

All directives specified on the Subsystem-Content header, except start-order, should be included in the Requirement. All attributes should be included in the filter directive of the Requirement. Notice that the version attribute is a range and must be converted into a proper filter. The VersionRange.toFilter method can be used to do this conversion. All other matching attributes are treated as type String and use an equality operation in the filter. Here is an example of a more complex transformation to Requirement:

org.acme.billing.credit.subsystem;
    type=osgi.subsystem.composite;
    version="[1.0, 1.1)";
    category=banking;
    resolution:=optional;
    start-order:=1

The above Subsystem-Content element converts into the following osgi.identity Requirement:

osgi.identity; 
    filter:="(&
        (osgi.identity=org.acme.billing.impl)
        (type=osgi.subsystem.composite)
        (&(version>=1.0)(!(version>=1.1))
            (category=banking)
        )"
    resolution:=optional

134.5.3 Preferred-Provider Header

The Preferred-Provider header contains a list of symbolic names, with optional attributes assertions. Each element specifies a single bundle or Subsystem resource that is to be preferred when resolving the requirements of the Subsystem content resources. The Preferred-Provider header must conform to the following syntax:

Preferred-Provider ::= resource (',' resource )*
resource           ::= symbolic-name ( ';' attribute )*

The Preferred-Provider header may specify the following architected matching attributes:

  • version - (Version) A version range used to select the version of the bundle or Subsystem to use. This follows the OSGi version range scheme, including the default value of 0.0.0.

  • type - (String) Indicates the type of the provider. Valid types are:

    • osgi.bundle

    • osgi.subsystem.composite

    • osgi.subsystem.feature

    The default type is osgi.subsystem.composite. Specifying an unsupported type results in an installation failure.

Each element of the Preferred-Provider header is used to locate a resource that is to be used as a preferred provider of the Subsystem. The Preferred-Provider header elements are converted to Requirements using the osgi.identity namespace just like the Subsystem-Content header except the default type is osgi.subsystem.composite. See Subsystem-Content Requirements.

Because this header influences resolution, it is only valid for it to be used on a Scoped Subsystem. If a Subsystems implementation encounters this header on an Unscoped Subsystem, it must fail the installation of the Subsystem.

The Preferred-Provider header has the effect of influencing the import policy into the Region representing the Scoped Subsystem that specified the header. If there are multiple candidate capabilities for a requirement and one or more of those capabilities is from a bundle or Subsystem identified in the Preferred-Provider header, then the Region import policy must prefer the capabilities from the preferred bundle or Subsystem.

A resource may be considered as a preferred provider only if it is a constituent of either the Scoped Subsystem's or any ancestor's Region.

134.5.4 Resource Repositories

When a Subsystem is installed the Subsystems implementation is responsible for provisioning resources that are associated with the Subsystem. For example, the Subsystem's content resources as well as any resources that are needed to satisfy dependencies of a Subsystem's content resources. During the Subsystem install process the Subsystems implementation uses a defined set of repositories to find the required resources needed to install a Subsystem. This set of repositories includes the following:

  • Local Repository - Contains the resources included in the Subsystem Archive, see Local Repository.

  • System Repository - Contains the resources currently installed, see System Repository

  • Repository Services - The set of repositories registered as OSGi services, see Repository Services.

  • Content Repository - The set of resources that comprise the Subsystem content, see Content Repository

  • Preferred Repository - The set of resources that are considered preferred providers, see Preferred Repository.

134.5.4.1 Local Repository

The Root of the Subsystem Archive contains 0 or more resources. The Subsystems implementation must read all entries (except directory entries) in the Root of the Subsystem Archive and treat each entry as a potential resource. One way of describing the resource entries contained in the Root of the Subsystem Archive is in the terms of an Repository implementation. For the purpose of this specification these resources are referred to as the Subsystem's Local Repository. The Local Repositories must not be registered as an OSGi Repository service. Also, it is not required that the Subsystem implementation actually implement a Local Repository as a concrete implementation of the Repository service interface.

134.5.4.2 System Repository

The term System Repository is used to describe the set of resources that are constituents of one or more of the currently installed Subsystems. The System Repository must not be registered as an OSGi service. Also it is not required that System Repository be implemented as a concrete implementation of the Repository service. There is a single System Repository representing the resources installed in the OSGi framework.

134.5.4.3 Repository Services

The repositories which are registered as Repository services, see Repository Service Specification. These Repositories are used to discover Subsystem content resources and dependencies. A Subsystems implementation searches registered Repository services by service ranking order.

134.5.4.4 Content Repository

The set of content resources for a Subsystem is referred to as the Subsystem's Content Repository. Similar to the Local and System Repositories, the Content Repositories must not be registered as an OSGi service and it is not required that the Subsystems implementation actually implement a Content Repository as a concrete implementation of the Repository service. There are two types of resources that can exist in a Subsystem's Content Repository:

  • Installable Content - A content resource which must be installed and result in a distinct resource at runtime. That is, a distinct bundle or Subsystem installation.

  • Shared Content - A content resource which is already installed and is a constituent of one or more already installed Subsystems that belong to the same Region as the Subsystem that the Subsystem content repository is for. This resource must be reused, the Subsystems implementation must not install another instance of the resource.

Details on how the content resources are discovered for the Content Repository are discussed in Discovering Content Resources.

134.5.4.5 Preferred Repository

The set of resources which are considered preferred providers of capabilities required by a Subsystem is referred to as the Preferred Provider Repository for the Subsystem. The Preferred Provider Repository for a Subsystem must not be registered as an OSGi service and it is not required that the Subsystems implementation actually implement the Preferred Provider Repository as a concrete implementation of the Repository service.

The following steps must be followed to discover the resources of the preferred provider repository for a Subsystem:

  1. The Preferred-Provider header is parsed into a list of elements where each element specifies a single osgi.identity requirement, see Preferred-Provider Header.

  2. For each osgi.identity requirement a Requirement object is created and used to search Repositories for preferred provider resources.

  3. The System Repository is searched. For each capability found in the System Repository; if the resource providing the osgi.identity capability is a constituent contained in the parent Region of the Scoped Subsystem's Region then the providing Resource of the Capability is considered a preferred provider and the search stops; otherwise continue to the next step.

  4. The Subsystem's Local Repository is searched. If a capability is found then the providing resource is used as a preferred provider and the search stops; otherwise continue to the next step.

  5. The registered Repository services are searched. If a repository service finds a capability then the providing resource is used as a preferred provider and the search stops; otherwise the preferred provider is not found.

134.5.5 Discovering Content Resources

When a Subsystem is installed the Subsystems implementation must determine the set of resources that compose the content of the Subsystem. The content resources of a Subsystem may be specified in the following ways:

  • The values of the Subsystem-Content header must be used if it is present. See Subsystem-Content Header.

  • The content of the Subsystem's Local Repository, if the Subsystem-Content header is not present.

When a Deployment Manifest is not present, Pre-Calculated Deployment, the Subsystems implementation must use this information to discover the content resources for a Subsystem as described in the following sections.

134.5.5.1 Declared Subsystem-Content

If the Subsystem-Content manifest header is declared then the following steps must be followed to discover the Subsystem's contents:

  • The Subsystem-Content header is parsed into a list of elements where each element specifies a single osgi.identity requirement. For each osgi.identity requirement element a Requirement is created and used to search Repositories for content resources.

    • If the Subsystem is a Scoped Subsystem then continue to the next step; otherwise if the Subsystem is an Unscoped Subsystem then the System Repository must be searched in order to discover any currently installed resources that match the content Requirement. For each matching capability found it must be determined if the capability provider Resource is a constituent of a Subsystem which is in the same Region as the installing Subsystem; if so then the provider Resource must be used as an shared content resource. If no shared content resource is found then continue to the next step; otherwise the search stops.

    • The Subsystem's Local Repository is searched to find a matching Capability for the content Requirement. If a Capability is found then the providing Resource of the Capability is used as an installable content resource of the Subsystem. If no installable content resource is found then continue to the next step, otherwise the search stops.

    • The registered Repository services are searched to find a matching capability for the content Requirement. If a Repository finds a provider for the content requirement then the provider Resource of the capability is used as an installable content resource of the Subsystem. If no matching provider is found then the discovery of the content resource has failed.

134.5.5.2 Use Subsystem Local Repository

If the Subsystem-Content header is not declared then the list of content resources is defined as all the Resources within the Subsystem's Local Repository which provide an osgi.identity capability with the type attribute of:

  • osgi.bundle

  • osgi.fragment

  • osgi.subsystem.application

  • osgi.subsystem.composite

  • osgi.subsystem.feature

  • Any other type that is supported by the implementation.

If a resource is found to be an unsupported type then installation of the Subsystem must fail.

For Scoped Subsystems this list is used as is and each Resource is considered an installable content resource. For Unscoped Subsystems the System Repository must be searched in order to determine if there are any already installed contents resources which may be used as a shared content resources. If no shared content resource can be found then the resource is considered an installable content resource.

134.6 Determining Dependencies

When a Subsystem is installed the Subsystems implementation determines the set of resources that compose the content of the Subsystem. Content resources may have requirements on capabilities that are not provided by any of the content resources for the Subsystem. When a Subsystem is installed the Subsystems implementation must determine the set of additional resources that are required in order to allow the Subsystem's content resources to resolve. These additional resources are called dependencies. When a Subsystem is installed the set of dependencies contains two types of resources:

  • Installable Dependency - A resource which must be installed and result in a distinct resource at runtime. That is, a distinct bundle or Subsystem installation.

  • Preinstalled Dependency - A resource which is already installed and is a constituent of one or more already installed Subsystems and the required capabilities provided by the resource are accessible according to the sharing policies of the Subsystems. This resource must be reused, the Subsystems implementation must not install another instance of the resource.

When a Deployment Manifest is not present, see Pre-Calculated Deployment, the Subsystems implementation must determine the set of dependencies for the Subsystem. To determine the set of dependencies the Subsystems implementation should attempt to resolve the Subsystem content resources before installing the content resources. One possible way of resolving the content resources, before installing them, is to use a Resolver service, see [10] Resolver Service Specification. This specification illustrates the behavior of dependency resource discovery using terms defined by the Resolver service. A Subsystems implementation is not required to use the Resolver service to accomplish dependency resource discovery. Other mechanisms may be used to accomplish the same goal as long as the resolution results in a valid class space. Subsystems implementations need not guarantee to find a solution to every resolution problem, but if a valid solution is not found, then discovery of the dependencies must fail, resulting in an installation failure.

In order to use the Resolver service the Subsystems implementation has to provide a ResolveContext object that represents the currently installed Subsystems and their constituent resources. This resolve context must search Repositories in the following order when searching for capabilities to satisfy content dependencies within the ResolveContext.findProviders method. The Content Repository, Preferred Provider Repository, System Repository and Local Repository must all be searched and all the results presented to the Resolver with a corresponding preference. If a result was found in these repositories, searching the registered Repository services is optional, but if no result was found yet, the registered Repository services must be searched. The order of matching capabilities presented to the Resolver must coincide with the Repository search order.

  1. The Content Repository.

  2. The Preferred Provider Repository.

  3. The System Repository. For each matching capability found in the System Repository the Subsystems implementation must determine if the capability is accessible to the content resources of the installing Subsystem according to the sharing policy of the Subsystem. See Sharing Capabilities for more details on Subsystem types and their sharing policies.

  4. The Local Repository. This allows a Subsystem Archive to optionally include dependencies.

  5. The registered Repository services.

Any matching capabilities found in the steps after step 1 above are considered to be provided by potential dependencies for the Subsystem. The capabilities found in the System Repository are provided by already installed resources, referred to as potential pre-installed dependencies. The capabilities found which are provided by other potential dependencies must be installed in order to resolve the Subsystem content resources, referred to as installable dependencies.

The Resolver's job is to select one of the potential capabilities returned by the findProviders method as the capability to satisfy a Requirement. At the end of a resolve operation a result (Map<Resource, List<Wire>) is returned which contains the Resources that got resolved and a list containing the Wires for the resolved Resource. The Subsystems implementation uses this resolution result in order to determine which resolved Resources are content resources, pre-installed dependencies, or installable dependencies. The installable dependencies must be installed as described in Accepting Dependencies. The pre-installed dependencies must have their reference count incremented as described in Reference Count.

134.7 Accepting Dependencies

When a Subsystem is installed the Subsystems implementation must determine the set of installable dependencies as described in Determining Dependencies. The Subsystems implementation must also determine what Subsystem is willing to accept the installable dependency as a constituent, referred to as an accepted dependency constituent. A Subsystem declares that it is willing to accept dependencies as constituents by specifying the provision-policy directive with the acceptDependencies value on the Subsystem-Type header, see Subsystem-Type Header.

The acceptDependencies provision policy is useful for creating isolation layers that do not pollute parent Regions with dependencies. For example, an application container may be implemented as a Subsystem. Such a container Subsystem could be installed into something called a kernel Subsystem. Applications are installed as Subsystems into the container Subsystem. In this case the container Subsystem would likely use the acceptDependencies provision policy so that any applications installed into the container Subsystem do not end up polluting the kernel Subsystem with the application's dependencies.

A dependency becomes an accepted dependency constituent of the Subsystem with a provision policy of acceptDependencies and that lies on the longest path between the Root Subsystem and the Subsystem being installed, inclusively. Note that a Subsystem that has acceptDependencies provision policy will accept its own installable dependencies as constituents since it lies on the longest path between the Root Subsystem and itself, inclusively.

The following figure illustrates a simple example of accepting dependency constituents. A Scoped Subsystem S2 is being installed into another Scoped Subsystem S1 and S1 has a provision-policy of acceptDependencies. When S2 is being installed the Subsystems implementation discovers content resources A and B and installable dependencies C and D. This is depicted in Figure 134.10.

Figure 134.10 Provision Policy

Provision Policy

In the previous example the Subsystem with a provision-policy of acceptDependencies and that lies on the longest path between the Root Subsystem and the Subsystem being installed is S1. Therefore the installable dependencies C and D become accepted dependency constituents of S1.

Figure 134.11 illustrates the same example but with S2 also having a provision-policy of acceptDependencies

Figure 134.11 Provision Policy

Provision Policy

In this example the Subsystem with a provision-policy of acceptDependencies and that lies on the longest path between the Root Subsystem and the Subsystem being installed is S2 itself. Therefore the installable dependencies C and D become accepted dependency constituents of S2.

Figure 134.12 illustrates the same example but with S1 and S2 not defining the provision-policy (default is rejectDependencies). The Root Subsystem always has a provision-policy of acceptDependencies:

Figure 134.12 Subsystems and acceptDependencies

Subsystems and acceptDependencies

In this example the Subsystem with a provision policy of acceptDependencies and that lies on the longest path between the Root Subsystem and the Subsystem being installed is the Root Subsystem. Therefore the installable dependencies C and D become accepted dependency constituents of the Root Subsystem.

134.8 Sharing Capabilities

Scoped Subsystems define a sharing policy for the Region they are contained in. A sharing policy controls access to capabilities between parent child Region boundaries. For Subsystems, a sharing policy is composed of two parts: an import policy and an export policy:

  • Export Policy - Defines the set of capabilities provided by the constituents contained in the Region that are made available to the parent Region.

  • Import Policy - Defines the set of capabilities which are available in the parent Region that are made available to the child Region.

The import sharing policies of a Subsystem's ancestor parent chain may prevent a Subsystem from accessing the required capabilities provided by a dependency. Figure 134.13 illustrates this.

Figure 134.13 Sharing Capabilities

Sharing Capabilities

In this example the C and D provide capabilities that are required by A and B respectively. The import sharing policy of S2 allows the capabilities to be imported into S2, but the import sharing policy for S1 denies the import of one of the capabilities and allows the other. In order for A or B to access capabilities provided by C or D they must traverse both the import sharing policy of S2 and S1. Ultimately S1 sharing policy prevents the necessary access to the dependencies necessary to resolve S2. Such a situation must be detected during the discovery of the installable dependencies and result in a failure to install the dependencies. This must result in the failure to install the Subsystem that requires the dependency, in this case S2.

134.8.1 Preferred Provider

The sharing policy for a Scoped Subsystem may specify a set of preferred providers. If a capability is provided by a preferred provider then that capability must be used to resolve a Scoped Subsystem's import policy. Figure 134.13 illustrates this.

Figure 134.14 Preferred Provider

Preferred Provider

In this example constituent B of the Root Region provides the capability X (called RootX). Also constituent C of S2Region provides the capability S2X. The export sharing policy of S2 policy exports the capability S2X to its parent Region, the RootRegion. The S1Region contains a constituent A that has a requirement on S1X. The two capabilities, RootX and S2X, are available to satisfy the requirement S1X. The S1Region's import sharing policy imports capability X and has a preferred provider of S2. This means that the capability S2X must be used to satisfy the requirement S1X.

134.8.2 System Capabilities

The osgi.ee and osgi.native namespaces are used by the System Bundle to describe capabilities for the Java execution environment and the native environment. These capabilities must only be provided by the System Bundle. A Subsystems implementation must allow access to the osgi.ee and osgi.native capabilities provided by the System Bundle to every Subsystem installed. This includes scoped subsystems which may or may not already have an import sharing policy configured to import these namespaces from the System Bundle.

134.9 Region Context Bundle

The Region context bundle provides a perspective from a constituent of a Subsystem contained in the Region. When a Scoped Subsystem is installed the Subsystems implementation must generate the Region context bundle and install it as a constituent bundle of the Subsystem. The Region context bundle has the following characteristics:

  • Has a symbolic name of org.osgi.service.subsystem.region.context.<subsystem id>

  • Version 1.0.0

  • Has a location string of <subsystem location>/<subsystem id>

  • Must always be allowed to resolve and start (i.e. has no requirements, imports or bundle activator).

  • Has a start-level of 1 and is persistently started.

  • Is installed and started before the Subsystem service is registered.

This bundle is installed and must remain active as long as the Subsystem is installed. If the Region context bundle is stopped, updated or uninstalled then the Subsystem runtime should log an error and may ensure the context bundle is installed and restarted.

When the Subsystems implementation is active it must establish the Root Subsystem, see Subsystem Service. In establishing the Root Subsystem the Subsystems implementation must ensure that there is a Region context bundle available for the Root Region. This Root Region context bundle will have a symbolic name of org.osgi.service.subsystem.region.context.0.

Typically the Region's context bundle would be used to obtain a bundle context with the getBundleContext() method, which has a perspective as a constituent of the Region. This is useful in the following ways:

  • Implementing Subsystem aware extenders. Such extenders need to be able to register listeners and monitor the inside of a Region in order to react to the constituent bundles of a Region.

  • Monitoring of internal events.

134.10 Explicit and Implicit Resources

Depending on how a resource is installed the Subsystems implementation considers the resource to be either an explicit resource or implicit resource. An explicit resource is a resource whose installation was initiated by an agent outside of the Subsystems implementation. An implicit resource is a resource whose installation was initiated by the Subsystems implementation during the explicit installation of a Subsystem, including the content and dependencies of the explicitly installed Subsystem.

134.10.1 Explicit Resources

An explicit resource is a resource that was installed programmatically, by an agent outside of the Subsystems implementation, using some resource specific API. This specification defines two types of resources that can be installed explicitly:

  • Subsystem resource - A Subsystem resource may be installed explicitly by using the Subsystem service. Note that content and dependencies of an explicitly installed Subsystem are not considered to be explicit resources themselves since they were implicitly installed by the Subsystems implementation.

  • Bundle resource - A bundle resource may be installed explicitly by using a bundle context. This includes fragments.

134.10.1.1 Explicit Bundle Resources

When a bundle is installed explicitly with a bundle context, the Subsystems implementation must determine the Subsystem of which a bundle becomes a constituent. The following rules are followed when a bundle is installed explicitly with a bundle context:

  1. Determine the bundle performing the install. This is the bundle whose Bundle Context is performing the install operation.

  2. Determine the target Region. This is the Region to which the bundle performing the install operation belongs.

  3. If a bundle with the same symbolic name and version already exists in the target Region then the bundle installation must fail unless the same location string is used. If the same location is used then the existing bundle is returned. This may be accomplished by the use of a bundle collision hook.

  4. Determine the Subsystem(s) of which the bundle performing the install is a constituent. The bundle performing the install may be a shared resource. In that case the bundle performing the install is a constituent of two or more Subsystems.

  5. The newly installed bundle must become a constituent of all the Subsystems of which the bundle performing the install is a constituent.

134.10.1.2 Explicit Subsystem Resources

When a Subsystem is installed explicitly with a Subsystem service, the Subsystems implementation must determine what Subsystem(s) the Subsystem resource and its children will become a constituent of. The following rules are followed when a Subsystem is installed:

  1. Determine the target Subsystem. This is the Subsystem service which is performing the install operation or the Subsystem which includes another Subsystem as part of its content, see Determining Content.

  2. Determine the target Region. This is the Region to which the target Subsystem belongs.

  3. If no Subsystem resource with the same location exists then continue to the next step; otherwise do the following:

    • If the existing Subsystem is not a part of the target Region then fail the install operation by throwing a Subsystem Exception; otherwise continue to the next step.

    • If the existing Subsystem symbolic name, version and type is not the same as the Subsystem being installed then fail the install operation by throwing a Subsystem Exception; otherwise continue to the next step.

    • If the existing Subsystem is already a constituent of the target Subsystem then return the existing Subsystem from the install method; otherwise the existing Subsystem resource becomes a shared resource by increasing the reference count of the existing Subsystem by one, see Reference Count, and the existing Subsystem becomes a constituent of the target Subsystem; finally, the existing Subsystem is returned from the install method.

  4. If no Subsystem resource with the same symbolic-name and version already exists in the target Region then the Subsystem resource being installed becomes a constituent of the Subsystem target; otherwise do the following:

    • If the existing Subsystem type is not the same as the type of the Subsystem being installed then fail the install operation by throwing a Subsystem Exception; otherwise continue to the next sub-step.

    • If the existing Subsystem is already a constituent of the target Subsystem then return the existing Subsystem from the install method; otherwise the existing Subsystem resource becomes a shared resource by increasing the reference count of the existing Subsystem by one and the existing Subsystem becomes a constituent of the target Subsystem; finally, the existing Subsystem is returned from the install method.

134.10.2 Explicit Resource Example

A scenario is used to illustrate the rules for determining which Subsystem an explicitly installed resource is a constituent. Figure 134.15 illustrates the Root Subsystem with initial content bundles A, SI (Subsystems implementation) and the system bundle (id = 0) installed.

Figure 134.15 Explicit Resource Example

Explicit Resource Example

If bundle A uses its own Bundle Context to explicitly install bundle B then bundle B becomes a constituent of the Root Subsystem. If bundle A uses Subsystem R to install Scoped Subsystem S1 then the S1 resource becomes a constituent of the Root Subsystem and S1 Subsystem becomes a child of the Root Subsystem. S1 contains constituent bundles C and D. Also, if bundle B uses Subsystem R to install Scoped Subsystem S2 then the S2 resource becomes a constituent of the Root Subsystem and the S2 Subsystem becomes a child of the Root Subsystem. S2 contains constituent bundles E and F. Figure 134.16 illustrates this.

Figure 134.16 Subsystems and Resources

Subsystems and Resources

Then if bundle C uses its own Bundle Context to install bundle F (using a different location string from constituent bundle S2F) then the bundle becomes a constituent of S1. If bundle E uses Subsystem service S2 to install Unscoped Subsystem U1 (with constituents G and H) and installs Unscoped Subsystem U2 (with constituents H and J) then both Subsystem bundles U1 and U2 become constituents of S2. The S2 Subsystem also becomes the parent Subsystem for both U1 and U2 Subsystems, see Figure 134.17.

Figure 134.17 Subsystems and Resources

Subsystems and Resources

In this scenario bundle H is a shared constituent of both U1 and U2 Subsystems. If bundle H installs a bundle K with its bundle context then bundle K becomes a shared constituent of both U1 and U2 Subsystems. Also, if Subsystem service U1 is used to install Scoped Subsystem S3 and Subsystem service U2 is also used to install Subsystem S3 then S3 resource becomes a shared constituent of both Unscoped Subsystems U1 and U2. The following illustrates this:

Figure 134.18 Subsystems and Resources

Subsystems and Resources

Since the S3 Subsystem resource is a shared constituent of both Subsystems U1 and U2 the S3 Subsystem has two parents: U1 and U2. In this case S3 Subsystem has two parent Subsystems but the S3Region still must only have one parent of S2Region. This is enforced by the rule that requires all of the parents of a Subsystem to belong to the same Region. For Scoped Subsystems the Region which contains all of the Subsystem's parents is parent Region.

So far the examples have illustrated cases where the Root Subsystem has Scoped Subsystem children. It is also acceptable for an Unscoped Subsystem to be installed into the Root Region as the following figure illustrates:

Figure 134.19 Subsystems and Resources

Subsystems and Resources

134.11 Resource References

A Subsystems implementation must track the resources which are installed and determine which Subsystems reference a resource. The reference count indicates the number of installed Subsystems which reference an installed resource. The resource references and reference counts are used by the Subsystems implementation to determine if an installed resource is eligible for garbage collection and also plays a role in determining when a resource should be started and stopped, see Starting and Stopping Resources ; the term reference count is only used to illustrate these concepts. The reference count of a resource is not exposed in the API of Subsystems. The following types of resources are referenced by a Subsystem:

  • Content Resources - These are the content resources which were installed when the Subsystem was installed, that is the resources declared in the Subsystem-Content header or from the Local Repository when the Subsystem-Content header is not specified, see Determining Content. Content Resources are considered to be implicit resources.

  • Explicit Resources - These are constituent resources which are installed explicitly, see Explicit Resources.

  • Dependencies - These resources provide capabilities required to satisfy requirements for a Subsystem's content resources, see Determining Dependencies. Dependencies are considered to be implicit resources.

Accepted dependency constituents are not defined as being referenced by the Subsystem of which they are a constituent unless constituent resource is a dependency for that Subsystem. Parent Subsystems are also not defined as being referenced by a child Subsystem.

134.11.1 Reference Count

When a Subsystem is being installed the Subsystems implementation must determine what resources are referenced by the Subsystem being installed. Each resource that is referenced by the Subsystem being installed will have its reference count incremented by 1. A top-level Subsystem being installed may contain child Subsystems. Each resource that is referenced by the child Subsystem being installed will have its reference count incremented by 1.

When a Subsystem is being uninstalled the Subsystems implementation must determine what resources are referenced by the Subsystem being uninstalled. Each resource that is referenced by the Subsystem being uninstalled will have its reference count decremented by 1. A top-level Subsystem being uninstalled may contain child Subsystems. Each resource that is referenced by each child Subsystem being uninstalled will have its reference count decremented by 1.

When a reference count gets set to zero then the resource is eligible for garbage collection and will be uninstalled. A Subsystems implementation may perform the garbage collection immediately or postpone the garbage collection for later. If garbage collection is postponed then the Subsystems implementation must prevent any additional usage of capabilities provided by the resource which is to be uninstalled. The garbage collection must occur in a reasonable period of time.

Bundle resources (including fragments) and Subsystem resources may be uninstalled explicitly. For example, uninstalling a Subsystem resource through the Subsystem service, or by other means outside of the Subsystems API such as uninstalling a bundle using a Bundle object. Each of the following must occur when a resource is explicitly uninstalled:

  • If the resource being explicitly uninstalled was not itself installed explicitly then an error must be logged indicating that the explicitly uninstalled resource still has one or more Subsystems referencing it.

  • If the resource being explicitly uninstalled was itself installed explicitly and the reference count is greater than 1 then an error must be logged indicating that the explicitly uninstalled resource still has one or more Subsystems referencing it.

  • The resource being explicitly uninstalled has its reference count set to 0 and finally the resource is uninstalled.

134.12 Starting and Stopping Resources

A Subsystem can be started by calling the Subsystem start method or the Subsystems implementation can automatically start the Subsystem if the Subsystem is ready and the autostart setting of the Subsystem indicates that it must be started.

A Subsystem is ready if the Subsystem's parent is in the process of starting or is active. A started Subsystem may need to be automatically started again by the Subsystems implementation after a restart. The Subsystems implementation therefore maintains a persistent autostart setting for each Subsystem. This autostart setting can have the following values:

  • Stopped - The Subsystem should not be started.

  • Started - The Subsystem must be started once it is ready.

Subsystem resources which are installed as content resources, see Discovering Content Resources, of one or more Subsystems must have their autostart setting set to started.

When a Subsystem is started and stopped then the resources the Subsystem references may be started and stopped. See for details Starting and Stopping.

The Subsystems implementation must track the resources which are installed and be able to determine when a resource must be started and stopped. To describe this behavior the term active use count is used. A active use count indicates the number of active Subsystems which reference a resource. The active use count is used by the Subsystems implementation in order to determine when a resource is started and stopped. The term active use count is only used to illustrate the starting and stopping of resources. The active use count of a resource is not exposed in the API of Subsystems.

Resource starting and stopping only applies to resources for which it is valid to start and stop. For example, it is not valid to start or stop resources of type osgi.fragment and a Subsystems implementation must not attempt to start or stop such resources.

134.12.1 Start Order

A Subsystem's Subsystem-Content header, see Subsystem-Content Header, can use the optional start-order directive for each content resource it declares. The start-order directive specifies the start order of the content resource in relation to other content resources of the Subsystem. Content resources are started in ascending order and stopped in descending order according to the start-order directive values. Content resources with the same start-order value may be started and stopped in any order in relation to each other. There is no default value for start-order. If the start-order is not specified then a Subsystem implementation is free to start the resource in any order. For example, the following header specifies four Subsystem content resources:

Subsystem-SymbolicName: S1
Subsystem-Type: osgi.subsystem.composite
Subsystem-Content: 
    A;
        type=osgi.bundle;
        version=1.0;
        start-order:=3,
    B;
        type=osgi.bundle;
        version=1.0;
        start-order:=2,
    C;
        type=osgi.bundle;
        version=1.0;
        start-order:=1,
    D;
        type=osgi.bundle;
        version=1.0;
        start-order:=2

The above headers specify a Subsystem S1 with four content resources: A, B, C and D. The start-order directive is used to sort the content resources to determine the order to start or stop them when the Subsystem is started or stopped. The content resources are sorted from lowest to highest start-order. Content resources that have the same start-order value may be started and stopped in any order in relation to each other. In this example the content resources are sorted into the list [C], [B, D], [A]. C has the lowest start-order, therefore it is the first in the list. B and D have the same start-order and therefore can be started in any order in relation to each other. Finally A is last in the list because it has the highest start-order.

When the Subsystem S1 is started the content resource C must be started first, followed by the starting of B and D in any order, finally resource A is started last. When the Subsystem S1 is stopped the content resource A must be stopped first, followed by the stopping of B and D in any order, finally resource C is stopped last.

Resources that do not specify a start-order can be started and stopped in any order.

134.12.2 Active Use Count

When a Subsystem is being started the Subsystems implementation must increment the active use count of every resource which is referenced by the Subsystem being started, see Resource References. After incrementing the active use counts of the resources referenced by a Subsystem, the Subsystems implementation must determine which referenced resources need to be started. For each resource referenced by the Subsystem which is valid to be started; if the active use count is greater than zero and the resource is not currently active then the resource must be started. The collection of dependencies are started before the Subsystem's content resources. The start order for the individual resources contained in the collection of dependencies is not specified. See Start Order.

When a Subsystem is being stopped the Subsystems implementation must decrement the active use count of every resource which is referenced by the Subsystem being stopped. After decrementing the active use counts of the resources referenced by a Subsystem, the Subsystems implementation must determine which referenced resources need to be stopped. For each resource referenced by the Subsystem which is valid to be started; if the active use count equals zero and the resource is currently active then the resource must be stopped. The Subsystem content resources are stopped before the collection of dependencies. Start Order describes the stop order of the Subsystem's content resources. The stop order of the individual resources contained in the collection of dependencies is not specified.

When starting the resource types supported by this specification the following rules apply:

  • osgi.bundle - The bundle must be transiently started using the activation policy of the bundle, that is with the Bundle.START_ACTIVATION_POLICY.

  • osgi.fragment - fragments cannot be started, this is a no-op.

  • osgi.subsystem.application, osgi.subsystem.composite, osgi.subsystem.feature - The Subsystem must be transiently started if its autostart setting is set to started.

When stopping the resource types supported by this specification the following rules apply:

  • osgi.bundle - The bundle must be persistently stopped.

  • osgi.fragment - Fragments cannot be stopped, this is a no-op.

  • osgi.subsystem.application, osgi.subsystem.composite, osgi.subsystem.feature - The Subsystem must be transiently stopped. Its autostart setting must not be changed.

Note that for resources referenced by a stopped Subsystem; bundle resources are persistently stopped and Subsystem resources are transiently stopped. This is a safeguard to handle cases where a constituent bundle is eagerly started by some other agent outside of the Subsystems implementation. Persistently started bundles will get auto started by the framework according to the start-level of the bundle. This can cause a constituent bundle to be stopped even though the Subsystem it is a constituent of is not active. To avoid this situation the Subsystems implementation always clears the persistent autostart setting of the bundle resources.

Subsystem resources which are referenced by a Subsystem are started or stopped transiently. There is no API to transiently start or stop a Subsystem. The Subsystems implementation must perform the starting or stopping of a referenced Subsystem normally except the starting or stopping process does not change the autostart setting for the referenced Subsystem.

134.13 Subsystem Service

The Subsystem service represents an Subsystem Archive resource that is installed in an OSGi Framework. The installation of a Subsystem can only be performed by using the Subsystem service API or through implementation specific means. The Subsystem interface's methods and service properties can be divided into the following categories:

  • Information - Access to information about the Subsystem itself as well as other Subsystems that are installed.

  • Life Cycle - The possibility to install other Subsystems and start, stop, and uninstall Subsystems.

For each Subsystem installed, the Subsystems implementation must register an associated Subsystem object as a service. The Subsystem service is used for monitoring the state of the Subsystem, for controlling the life cycle of the installed Subsystem and for installing child Subsystems.

134.13.1 Root Subsystem

A Subsystems implementation must register the Root Subsystem service. When a Subsystems implementation is started for the first time it must establish the Root Subsystem. The following steps are required to establish the Root Subsystem.

  1. The Root Subsystem has a symbolic name org.osgi.service.subsystem.root, version 1.1 (the version of the Subsystems specification), a Subsystem id of 0 and a location of

    subsystem://?Subsystem-SymbolicName=org.osgi.service.subsystem.root& «
     Subsystem-Version=1.1
  2. The Root Subsystem has no parent Subsystem. More specifically the Root Subsystem is the only source vertex in the Subsystem graph.

  3. The Root Subsystem is considered a Scoped Subsystem of type application, with provision-policy of acceptDependencies. Since the Root Subsystem has no parent it does not import or export any capabilities.

  4. The Subsystem content is the set of bundles installed in the framework that do not belong to any other Subsystem.

  5. The root subsystem has a region context bundle as described in Region Context Bundle.

The Root Subsystem always exists when a Subsystems implementation is present and active, even if no other Subsystems are installed The Root Subsystem is used as the starting point for installing Subsystems as child Subsystems. The Root Subsystem cannot be stopped or uninstalled by calling the Subsystem service stop or uninstall methods. Any attempt to do so must result in a Subsystem Exception.

134.13.2 Subsystem Service Properties

The primary means of discovering and monitoring a Subsystem is the Subsystem service. A Subsystems implementation must register one Subsystem service for each Subsystem installed. The Subsystem service is used for monitoring and controlling the life-cycle of the installed Subsystem. Service properties on the Subsystem service carry most of the information required to monitor Subsystem life cycle operations and the current state of a Subsystem. The following table describes the service properties of a Subsystem:

Table 134.1 Subsystem Mandatory Service Properties

Key Name Type Description
subsystem.id Long

The Subsystem id of the Subsystem

subsystem.symbolicName String

The symbolic name of the Subsystem

subsystem.version Version

The version of the Subsystem

subsystem.type String

The type of Subsystem.

subsystem.state Subsystem.State

Contains the current state of the Subsystem


134.13.3 Subsystem States

The Subsystem service property subsystem.state contains the current state of the Subsystem (this is referred to as the subsystem state). All Subsystem states are defined by the Subsystem.State enum, for example, INSTALLED. The possible values of a subsystem.state are shown in the table below:

Table 134.2 Subsystem States

subsystem.state Description
INSTALLING

When a Subsystem is first installed the Subsystems implementation must register a Subsystem service with the initial subsystem.state of INSTALLING. The subsystem.state must remain in the INSTALLING state until all of the Subsystem constituents are installed successfully.

INSTALLED

When all contents of a Subsystem has been successfully provisioned then the subsystem.state is set to INSTALLED.

INSTALL_FAILED

Indicates that some failure occurred while attempting to install the Subsystem's contents.

RESOLVING

Starting a Subsystem triggers the resolution of a Subsystem if the subsystem.state is INSTALLED. A RESOLVING state indicates that a resolve process is occurring in an attempt to resolve all of the subsystem's content resources.

RESOLVED

Indicates that the Subsystem is resolved. A Subsystem is resolved if all of its content resources are resolved.

STARTING

Indicates that the Subsystem is in the process of being started. During this state the resources the Subsystem references which are eligible for starting are started, see Starting and Stopping Resources. Once all the eligible resources are successfully started then the subsystem.state is set to ACTIVE.

ACTIVE

The ACTIVE state indicates that all eligible resources referenced by the Subsystem were successfully started during the starting process.

STOPPING

Indicates that the Subsystem is in the process of being stopped. During this state the resources referenced by the Subsystem are stopped if appropriate.

UNINSTALLING

Indicates that the Subsystem is in the process of being uninstalled. During this state the resources referenced by the Subsystem are marked for garbage collection if they are eligible, see Resource References.

UNINSTALLED

When all of the resources referenced by the Subsystem which are eligible for garbage collection have been uninstalled then the subsystem.state is set to UNINSTALLED.


134.13.4 Subsystem Service Registrations

The Subsystems implementation must register one Subsystem service for each Subsystem installed. The Subsystems implementation must provide access to every Subsystem service from the Root Region. Every other Region must have access to the following Subsystem Services:

  • Subsystem service representing the Scoped Subsystem of the Region.

  • All Unscoped Subsystem services contained in the Region.

  • All Subsystems which are children of a Subsystem contained in the Region.

A Region is granted access to the Subsystem services listed above automatically by the Subsystems implementation regardless of the sharing policy defined by the Scoped Subsystem of that Region. Additional Subsystem services may be imported into a Region from its parent Region by the sharing policy defined by the Scoped Subsystem of that Region.

For example, a Root Subsystem and Root Region that has two Scoped Subsystem children, S1 and S2. All Subsystem services are registered by the Subsystems implementation and are visible in the Root Region. The S1 Subsystem service is also implicitly visible in the S1 Region because it represents the Scoped Subsystem S1 contained in that Region. Similarly the S2 Subsystem service is also implicitly visible from the S2 Region. This example is depicted in Figure 134.20.

Figure 134.20 Root, attached to Scoped Subsystems S1, S2

Root, attached to Scoped Subsystems S1, S2

Figure 134.21 defines a more complicated scenario where Subsystems and multiple children are involved.

Figure 134.21 Complex example Subsystem scoping

Complex example Subsystem scoping

All Subsystem services are visible in the Root Region. The S1 Subsystem service is also implicitly visible in the S1 Region because it represents the Scoped Subsystem S1 contained in that Region. The S1 Region also has visibility to the U1 and U2 Subsystem services because these Unscoped Subsystems are contained in the S1 Region. Similarly the S2 Subsystem service is also implicitly visible from the S2 Region. The S2 Region also has visibility to the U3 and U4 Subsystem services because these Unscoped Subsystems are contained in the S2 Region. The S2 Region also has visibility to the S3 Subsystem service because the S3 Subsystem is a child of a Subsystem contained in the S2 Region. Finally, the S3 Region has implicit visibility to the S3 Subsystem service and it has visibility to the U5 Subsystem service because the Unscoped Subsystem is contained in the S3 Region.

Note that a Scoped Subsystem's import sharing policy may grant its Region visibility to additional Subsystem services.

134.13.5 Subsystem Manifest Headers

The Subsystem service interface has the getSubsystemHeaders(Locale) method which returns the values of the Subsystem's manifest headers. The headers returned by this method includes the values specified in the Subsystem manifest file and the values derived by the Subsystems implementation. Certain manifest headers may be derived at install time by the Subsystems implementation if they were not specified in the Subsystem manifest file. When a Subsystem manifest value is derived then the derived value must be included in the headers returned by the method getSubsystemHeaders(Locale). The following Subsystem manifest headers may be derived by the Subsystems implementation:

  • Subsystem-SymbolicName

  • Subsystem-Version

  • Subsystem-Content

134.14 Subsystem Life Cycle

The Subsystems specification provides an API to control the life cycle operations of a Subsystem. For each Subsystem installed there is an associated Subsystem object (also registered as a Subsystem service). A Subsystem's life-cycle is controlled by operations performed on the Subsystem object. Operations performed on the Subsystem may also cause equivalent operations on the resources referenced by the Subsystem. For example starting a Subsystem will cause all of its content resources to start if appropriate.

For Scoped Subsystems the export and import sharing policies are initially disabled at runtime and get enabled at runtime by the Subsystems implementation depending on the state of the Scoped Subsystem which defines the sharing policy. When an import sharing policy is disabled at runtime, none of the installed resources contained in the Region associated with the Scoped Subsystem have visibility to capabilities available in the parent Region. Once an import policy is enabled at runtime the installed resources contained in the Region have visibility to capabilities available in the parent Region according to what the import sharing policy specifies. When an export sharing policy is disabled at runtime, none of the capabilities provided by installed resources contained in the Region associated with the Scoped Subsystem are visible in the parent Region. Once an export policy is enabled at runtime the capabilities provided by installed resources contained in the Region are visible in the parent Region according to what the export sharing policy specifies.

The subsystem.state is a reflection of the last action performed on the Subsystem through the Subsystem service. The use of any other API to change the state of a resource referenced by a Subsystem directly does not result in a change of the subsystem.state (i.e. calling stop on a bundle). For example, uninstalling a Subsystem content resource which is a bundle does not cause the Subsystem to be uninstalled, but it does result in an error being logged.

All references to changing the state of this Subsystem include both changing the state of the Subsystem object as well as the state property of the Subsystem service.

The following figure illustrates the life cycle of a Subsystem:

Figure 134.22 State diagram Subsystems

State diagram Subsystems

134.14.1 Installing

A Subsystem's install process is initiated using one of the Subsystem service's install methods. The Subsystems implementation must assign a unique Subsystem identifier that is higher than any previous installed Subsystem identifier. Previously installed Subsystem identifiers include Subsystems which were uninstalled in a previous session of the framework. The installation of a Subsystem must be:

  • Persistent - The Subsystem must remain installed across framework and Java VM invocations until the Subsystem is explicitly uninstalled.

  • Atomic - The install method must completely install the Subsystem or, if installation fails, the Subsystems implementation must leave the framework in the same state as it was before the method was called.

Once a Subsystem has been installed, a Subsystem object is created and all remaining life cycle operations for the installed Subsystem must be performed upon this object. The returned Subsystem object can be used to start, stop, and uninstall the Subsystem as well as install child Subsystems.

When a Subsystem is being installed the Subsystems implementation must perform the following operations synchronously before returning from the install method:

  1. Determine the symbolic name, version, and type for the Subsystem being installed as defined in Subsystems. If the Subsystem name, version or type are invalid then the install fails and a Subsystem Exception is thrown.

  2. Determine the Subsystems for which the Subsystem being installed will become a constituent of by following the steps in Explicit and Implicit Resources.

  3. Determine the Subsystem identifier. Subsystem identifiers are unique and assigned by the Subsystems implementation.

  4. If the Subsystem is a Scoped Subsystem then create the new Region for the Subsystem and install and start the Region context bundle. See Region Context Bundle for the Region context bundle.

  5. Register a Subsystem service with the initial subsystem.state service property set to INSTALLING. This Subsystem service represents the Subsystem resource. See Subsystem Service Properties and Subsystem Service Registrations for more details.

  6. Determine the Subsystem content resources. See Determining Content for details on how the Subsystem contents are determined. If the contents cannot be discovered successfully and the content is not optional then an installation failure occurs and a Subsystem Exception is thrown. Otherwise continue to the next step.

  7. Determine the Subsystem dependencies. See Determining Dependencies for details on determining the Subsystem's dependencies. If the dependencies cannot be determined successfully then an installation failure occurs and a Subsystem Exception is thrown. Otherwise continue to the next step.

  8. Install the dependencies. The Subsystems implementation must prevent resolution of dependency wires to the capabilities provided by the installed dependencies until the Subsystem has successfully entered INSTALLED state. See Explicit and Implicit Resources for details on where dependencies are installed and see Resource References for how they are tracked. If any dependency fails to install then an installation failure occurs and a Subsystem Exception is thrown. Otherwise continue to the next step.

  9. Install content resources. The content resources must be disabled from resolving until the Subsystem has successfully entered INSTALLED state. If any content resource fails to install then and installation failure occurs and a Subsystem Exception is thrown. Otherwise continue to the next step.

  10. If the Subsystem is scoped, enable the import sharing policy for the Region. See Sharing Capabilities.

  11. Enable resolution for all of the Subsystem content and any dependencies installed. Set the subsystem.state to INSTALLED and return the installed Subsystem object.

The state INSTALL_FAILED is used to inform about an installation failure. All installation failures use the following steps:

  1. When a Subsystem fails to install it enters the INSTALL_FAILED state.

  2. Immediately transition the Subsystem to the UNINSTALLING state.

  3. All content and dependencies which may have been installed by the Subsystem installing process must be uninstalled.

  4. Transition the Subsystem to the UNINSTALLED state.

  5. Unregister the Subsystem service.

  6. If the Subsystem is scoped then, uninstall the Region context bundle.

  7. Throw a Subsystem Exception indicating an install failure.

134.14.2 Resolving

A Subsystem's resolve process is initiated by performing a start operation on a Subsystem whose subsystem.state is currently set to INSTALLED. There is no explicit operation for initiating the resolve process of a Subsystem. The Subsystems implementation is free to initiate the resolve process for a Subsystem for any reason. For example, the Subsystems implementation may choose to try to resolve all currently installed Subsystems when the start operation is performed on a single Subsystem.

134.14.3 Starting

A Subsystem can be started by calling the Subsystem start() method or the Subsystems implementation can automatically start the Subsystem if the Subsystem is ready and the autostart setting of the Subsystem indicates that it must be started. When a Subsystem is being started the Subsystems implementation must perform the following operations synchronously before returning from the start() method:

  1. If the subsystem.state is INSTALL_FAILED, UNINSTALLED, or UNINSTALLING, then an Illegal State Exception is thrown.

  2. Set the Subsystems autostart setting to started.

  3. If the subsystem.state is ACTIVE then the start method returns immediately.

  4. If the Subsystem is not ready to be started then the start method returns immediately.

  5. If this subsystem.state is RESOLVING, STARTING or STOPPING, then the start method must wait for starting or stopping to complete before continuing. If this does not occur in a reasonable time, a Subsystem Exception is thrown to indicate the Subsystem was unable to be started.

  6. If the subsystem.state is RESOLVED then continue to the next step; otherwise if the subsystem.state is INSTALLED then the subsystem.state is set to RESOLVING and an attempt is made to resolve all of the Subsystem's content resources. If all contents are resolved then set the subsystem.state to RESOLVED, enable the export sharing policy and continue to the next step; otherwise a starting failure occurs and a Subsystem Exception is thrown.

  7. Set the subsystem.state to STARTING.

  8. Start all resources referenced by the Subsystem according to Starting and Stopping Resources. If all of the resources start successfully then continue to the next step; otherwise a start failure occurs.

  9. Set the subsystem.state to ACTIVE and return.

All start failures use the following steps:

  1. If the subsystem state is STARTING then change the state to STOPPING.

  2. Stop all resources that were started as part of this operation.

  3. Change the state to INSTALLED or RESOLVED depending on if the Subsystem was resolved.

  4. Throw a Subsystem Exception indicating the cause of the start failure.

134.14.4 Stopping

A Subsystem's stop process is initiated using the Subsystem service's stop() method. When a Subsystem is being stopped the Subsystems implementation must perform the following operations synchronously before returning from the stop() method:

  1. If the subsystem.state is UNINSTALLED, INSTALL_FAILED, or UNINSTALLING, then an Illegal State Exception is thrown.

  2. Set the Subsystems autostart setting to stopped.

  3. If the subsystem.state is RESOLVED or INSTALLED then the stop() method returns immediately.

  4. If this subsystem.state is STARTING or STOPPING, then the stop method must wait for starting or stopping to complete before continuing. If this does not occur in a reasonable time, a Subsystem Exception is thrown to indicate the Subsystem was unable to be stopped.

  5. Set the subsystem.state to STOPPING.

  6. Stop all resources referenced by the Subsystem according to Starting and Stopping Resources. If any error occurs while stopping a resource the Subsystems implementation must continue to stop the remaining resources that are eligible to stop.

  7. Set the subsystem.state to RESOLVED.

With regard to error handling while stopping resources referenced by the Subsystem, errors subsequent to the first should be logged. Once the stop process has completed, a Subsystem Exception must be thrown with the initial error as the specified cause.

134.14.5 Uninstalling

A Subsystem's uninstall process is initiated using the Subsystem service's uninstall() method. To whatever extent possible, the Subsystems implementation must determine the resources referenced by the Subsystem which are eligible for garbage collection, Reference Count. This method must always uninstall the Subsystem from the persistent storage of the Subsystems implementation.

Once this method returns, the state of the platform must be the same as if the Subsystem had never been installed, unless some bundle resource which was uninstalled has exported package which are being used by other bundles still installed in the platform. All old exports must remain available for existing bundles and future resolves until the uninstalled bundle is refreshed or the framework is restarted.

When a Subsystem is being uninstalled the Subsystems implementation must perform the following operations before returning from the uninstall() method:

  1. If the subsystem.state is UNINSTALLED then this method returns immediately.

  2. If the subsystem.state is STARTING, STOPPING or ACTIVE then the Subsystem is stopped according to Stopping. Otherwise continue to the next step.

  3. If the subsystem.state is INSTALLING and the installing process is interruptible, fail the install process; otherwise, wait until the installation is complete.

  4. If the subsystem.state is in the INSTALL_FAILED state then skip to step 6.

  5. Set the subsystem.state to INSTALLED.

  6. Set the subsystem.state to UNINSTALLING.

  7. Determine the resources referenced by the Subsystem which are eligible for garbage collection according to Reference Count. If a Subsystems implementation does garbage collection synchronously and any error occurs while uninstalling a resource the Subsystems implementation must continue to uninstall the remaining resources that are eligible to garbage collect.

  8. Set the subsystem.state to UNINSTALLED.

  9. Unregister the Subsystem service.

  10. If the Subsystem is a Scoped Subsystem then uninstall the Region context bundle. At this point the Region no longer exists.

With regard to error handling while synchronously uninstalling resources eligible for garbage collection, errors subsequent to the first should be logged. Once the uninstall process has completed, a Subsystem Exception must be thrown with the initial error as the specified cause.

134.15 Pre-Calculated Deployment

A pre-calculated deployment in the form of a deployment manifest can be included as part of a Subsystem Archive or provided by a deployer at installation time. Manifests provided at install time override those included within an archive, and those within an archive override calculated ones. The deployment manifest defines the precise deployment of the Subsystem. Providing a deployment manifest means a Subsystem can be deployed and the exact resources that are installed are known ahead of time. This allows test teams to test specific deployments and these same deployments can then be used in production. The deployment manifest is a locking down of the variability in a Subsystem manifest (or the equivalent if the Subsystem definition is calculated during deployment based on the Subsystem Archive). The deployment manifest follows the same syntax rules as the Subsystem manifest but uses different headers for deployment-specific information. A deployment manifest describes the following:

  • The exact versions for content resources

  • Any dependencies required to resolve the Subsystem's content that are not satisfied by the target runtime

  • Sharing policy for requirements and capabilities shared into or out of the Subsystem.

Because a Deployment Manifest's dependencies bridge between the requirements of the Subsystem and the capabilities of the target runtime, it is not guaranteed to be portable. If available, the Subsystem service implementation must first attempt to use the Deployment Manifest to deploy the Subsystem. If the Deployment Manifest is found not to work, for example, the chosen resources do not resolve for the target runtime, then the Subsystem's implementation must fail the installation of the Subsystem.

134.15.1 Deployment Headers

A Subsystem can carry descriptive information about its deployment in the Deployment Manifest file contained in its Subsystem Archive under the name OSGI-INF/DEPLOYMENT.MF. This specification defines Deployment Manifest headers such as Deployed-Content, which Subsystem deployers (typically tools) use to supply deployment information about a Subsystem. A Subsystems implementation must:

  • Process the main section of the manifest. Individual section of the manifest are ignored.

  • Ignore unknown manifest headers. The Subsystem deployer can define additional manifest headers as needed.

  • Ignore unknown attributes and directives.

All specified manifest headers are listed in the following sections, and include example values. All headers are optional, unless specifically indicated.

134.15.1.1 Deployment-ManifestVersion: 1

The Deployment-ManifestVersion header defines that the deployment manifest follows the rules of a Subsystems Specification. It is 1 (the default) for this version of the specification. Future versions of the Subsystems Specification can define higher numbers for this header.

134.15.1.2 Subsystem-SymbolicName: com.acme.subsystem.logging

The Subsystem-SymbolicName header specifies a non-localizable name for the Subsystem that the deployment manifest is for. The Subsystem symbolic name together with a version must identify a unique Subsystem though it can be installed multiple times in a framework. See Validating Subsystem Identity.

134.15.1.3 Subsystem-Version: 1.0

The Subsystem-Version header specifies the version of this Subsystem that the deployment manifest is for. See Validating Subsystem Identity.

134.15.1.4 Deployed-Content: com.acme.logging;type=osgi.bundle;deployed-version=1.0.0

The Deployed-Content header lists requirements for the exact resources that are considered to be the contents of this Subsystem. This header identifies the exact versions of the resources listed in the Subsystem-Content header. See Deployed-Content.

134.15.1.5 Provision-Resource: com.acme.logging;type=osgi.bundle;deployed-version=1.0.0

The Provision-Resource header lists requirements for the exact resources to be installed in order to satisfy requirements from the Deployed-Content resources that are not satisfied by the capabilities of the target runtime. See Provision-Resource.

134.15.1.6 Import-Package: com.acme.api;version="[1.0,1.1)"

The Import-Package header lists package requirements for capabilities that are to be imported into a Scoped Subsystem. See Import-Package.

134.15.1.7 Export-Package: com.acme.api;version=1.0.1

The Export-Package header lists package capabilities that are to be exported out of a Scoped Subsystem. See Export-Package.

134.15.1.8 Require-Bundle: com.acme.logging; bundle-version="[1.0,1.1)"

The Require-Bundle header lists bundle requirements for bundle capabilities that are to be imported into a Scoped Subsystem. See Require-Bundle.

134.15.1.9 Provide-Capability: com.acme.dict; from=nl; to=de; version:Version=1.2

The Provide-Capability header declares the capabilities exported for a Scoped Subsystem. See [3] Resource and Wiring.

134.15.1.10 Require-Capability: osgi.ee; filter:="(osgi.ee=*)"

The Require-Capability header declares the required capabilities for a Scoped Subsystem. See [3] Resource and Wiring.

134.15.1.11 Subsystem-ImportService: com.acme.service.Logging

The Subsystem-ImportService header lists service requirements for service capabilities that are to be imported into a Scoped Subsystem. See Services.

134.15.1.12 Subsystem-ExportService: com.acme.service.Logging

The Subsystem-ExportService header lists service requirements that are matched against service capabilities provided by the Deployed-Content resources. Any matching capabilities are exported out of the Scoped Subsystem.

134.15.2 Validating Subsystem Identity

The Subsystem to which the deployment manifest applies is identified by the Subsystem's symbolic name and version headers. These headers are identical to those specific in the Subsystem manifest. A Subsystem runtime must validate that the headers specified in the deployment manifest match those of the Subsystem manifest, taking into account Subsystem manifest defaulting rules. This allows the two manifests to be managed by teams separately during development or testing whilst ensuring no mistakes have been made when they are brought together for deployment. If the headers do not match, then the runtime must not use the deployment manifest and must fail the installation.

134.15.3 Deployed-Content

The Deployed-Content header lists the exact constituents to be installed for the Subsystem. For each mandatory entry in the Subsystem-Content header, there must be a corresponding Deployed-Content entry. If a content resources is identified as optional and there is a corresponding entry in the deployment manifest, then it must be deployed. If there is no corresponding entry in the deployment manifest then no resource must be deployed for it. The Deployed-Content entry identifies the exact version of the constituent whereas the Subsystem-Content entry may specify a version range. Each Deployed-Content entry is identified by symbolic name, version and type (an osgi identity).

Deployed-Content:
    com.acme.logging;
        deployed-version=1.0,
    com.acme.persistence;
        deployed-version=1.1;
        type=osgi.subsystem.composite 

Each entry must uniquely identify the resource to be provisioned as a constituent of the Subsystem.

The following mandatory matching attributes must be applied to each entry:

  • deployed-version - The exact version of the resource to be deployed. Deployed version is a specific version, not a version range, hence the use of a new attribute name. There is no default value for this attribute.

The following architected matching attribute as well as any arbitrary matching attributes can be applied to each entry:

type - The type of the constituent. It is recommended that a reverse domain name convention is used unless those types and their processing is standardized by the OSGi Alliance (e.g. bundles). The default value is osgi.bundle. A Subsystems implementation may support additional types, but the following types must be supported:

  • osgi.bundle

  • osgi.fragment

  • osgi.subsystem.application

  • osgi.subsystem.composite

  • osgi.subsystem.feature

The value of this directive must match the type directive for the corresponding entry in the Subsystem-Content header, including taking into account defaulting. If the type does not match, then the installation must fail.

The following directive can be applied to each entry:

  • start-order - The precedence the constituent should have during the start sequence. Resources with lower start-order values are started before resources with higher values. Resources with the same start-order value may be started sequentially or in parallel. The value of this directive must match the start-order directive for the corresponding entry in the Subsystem-Content header, including taking into account defaulting.

134.15.4 Provision-Resource

The Provision-Resource header lists the resources to be provisioned in support of the Subsystem's dependencies. The exact location in the Subsystem hierarchy where the resources are installed is determined by the provision-policy of the Subsystem or its parents.

The Provision-Resource header must result in a transitively complete deployment. For example, if a resource added to Provision-Resource brings in additional unsatisfied requirements, further resources must be added to satisfy these, until there are no unresolved requirements remaining.

Provision resource has one required matching attribute:

  • deployed-version - The exact version of the resource to be deployed. Deployed version is a specific version, not a version range, hence the use of a new attribute name. There is no default value for this attribute.

The following architected matching attributes as well as any arbitrary matching attributes can be applied to each entry:

type - The type of the resource. It is recommended that a reverse domain name convention is used unless those types and their processing is standardized by the OSGi Alliance (e.g. bundles). The default type is osgi.bundle. A Subsystems implementation may support additional types, but the following types must be supported:

  • osgi.bundle

  • osgi.fragment

  • osgi.subsystem.application

  • osgi.subsystem.composite

  • osgi.subsystem.feature

The list of the Provision-Resource entries is determined by resolving the Subsystem's requirements. The way in which the Subsystem's requirements are resolved is dependent on the Subsystem's sharing policy.

For a Scoped Subsystem the provision resources header must identify a set of resources necessary to satisfy the requirements into the Subsystem that are not satisfied by the target deployment environment. These requirements may be for packages, services, or other types of requirements, and are those identified in the deployment manifest using headers such as Import-Package and Subsystem-ImportService.

For an Unscoped Subsystem any mandatory requirements that are not satisfied by capabilities provided by the target environment may be satisfied by other constituents or a resource added to the Provision-Resource header. The resolution process for Unscoped Subsystems has no propensity to resolve to capabilities provided by the Subsystem's constituents and so a resource listed in Provision-Resource may provide capabilities that are also provided by a constituent resource.

134.15.5 Import-Package

Scoped Subsystems describe the exact packages they import in their Deployment Manifests. They do this using the bundle Import-Package header. Any packages that match the Import-Package statement must be allowed into the Scoped Subsystem by its associated Region's sharing policy.

Unscoped Subsystems have a sharing policy that shares all packages and therefore their deployment manifests do not use this header to describe the sharing of individual packages. If this header is present and the Subsystem is unscoped, then the runtime must fail the installation of the Subsystem.

134.15.6 Export-Package

Scoped Subsystems describe the exact packages they export in their deployment manifests. They do this using the bundle Export-Package header. Any packages that match the Export-Package statement must be made available outside the Subsystem by its associated Region's sharing policy.

Unscoped Subsystems have a sharing policy that shares all packages and therefore their deployment manifests do not use this header to describe the sharing of individual packages. If this header is present and the Subsystem is unscoped, then the runtime must fail the installation of the Subsystem.

134.15.7 Require-Bundle

Scoped Subsystems can have Require-Bundle requirements satisfied by bundles outside the Subsystem. These bundle requirements are described using the bundle Require-Bundle header. Any bundles that match the Require-Bundle statement must be allowed into the Scoped Subsystem by its associated Region's sharing policy. If a bundle matches the Require-Bundle requirement then it becomes available as a candidate for wiring any Require-Bundle requirements inside the Subsystem. However, any packages the matching bundle provides are not made available to satisfy Import-Package requirements by the Region's sharing policy. If the packages are also required then they must be listed in the deployment manifest's Import-Package header.

Unscoped Subsystems have a sharing policy that shares all bundles and therefore their deployment manifests do not use this header to describe the sharing of specific bundles. If this header is present and the Subsystem is unscoped, then the runtime must fail the installation of the Subsystem.

134.15.8 Services

Scoped Subsystems can import and export services using the Subsystem-ImportService and Subsystem-ExportService headers respectively. These two headers must conform to the following syntax:

Subsystem-ImportService ::= service( ',' service )*
Subsystem-ExportService ::= service ( ',' service )*
service                 ::= qname ( ';' parameter )*

Both headers support the following directive:

  • filter - A filter expression that is used to match against the service properties of services registered using the specified qname of the service's object class. The filter directive is optional. If no filter directive is defined then all services registered using the specified qname match the service statement.

134.15.9 Subsystem-ImportService

Scoped Subsystems describe the services they import in their deployment manifests. They do this using the Subsystem-ImportService header. Subsystem-ImportService header defines a list of OSGi service filters that are matched against the services visible inside the Scoped Subsystem's parent Region. Each service visible in the Subsystem's parent Region that matches one or more Subsystem-ImportService statements must be allowed into the Scoped Subsystem by its associated Region's sharing policy. The following example imports services registered under the com.acme.logging.Log interface with a service property threshold=error.

Subsystem-ImportService: com.acme.logging.Log;filter:="(threshold=error)"

Unscoped Subsystems have a sharing policy that shares all services and therefore their deployment manifests do not use this header to describe the sharing of specific services. If this header is present and the Subsystem is unscoped, then the runtime must fail the installation of the Subsystem.

134.15.10 Subsystem-ExportService

Scoped Subsystems describe the services they export in their deployment manifests. They do this using the Subsystem-ExportService header. The Subsystem-ExportService header defines a list of OSGi service filters that are matched against the services visible inside the Scoped Subsystem's Region. Each service visible in the Scoped Subsystem's Region that matches one or more Subsystem-ExportService statements must be allowed by its associated Region's sharing policy into the Scoped Subsystem's parent Region. The following example exports services registered under the com.acme.logging.Log interface with a service property threshold=error.

Subsystem-ExportService: com.acme.logging.Log;filter:="(threshold=error)"

Unscoped Subsystems have a sharing policy that shares all services and therefore their Deployment Manifests do not use this header to describe the sharing of specific services. If this header is present and the Subsystem is unscoped, then the runtime must fail the installation of the Subsystem.

134.16 Subsystem Types

Subsystem types simplify the configuration of sharing policies. The type of Subsystem is specified using the Subsystem-Type header. Each type has its own default sharing policy, for example, to forbid the sharing of capabilities out, or to share all capabilities in. This specification defines three Subsystem types:

  • osgi.subsystem.application

  • osgi.subsystem.composite

  • osgi.subsystem.feature

Other, non-standard, types are permitted. The specifics of each standard type are describe below.

134.16.1 Application

An application is a Scoped Subsystem with a sharing policy associated with what is often considered to be an application. An application does not share (export) any capabilities to other bundles or Subsystems. It also does not explicitly import any capabilities. Any required capabilities that are not satisfied by the application's constituents are automatically shared in (imported) from the parent Subsystem.

A Subsystem is identified as an application by specifying a Subsystem type value of osgi.subsystem.application in the Subsystem manifest.

Subsystem-Type: osgi.subsystem.application

134.16.2 Application Deployment

Application Subsystems are not configured using additional requirement or capability headers, such as Import-Package. Applications do not export any capabilities. If an application Subsystem contains any capability exports then the Subsystem runtime should log an error and must fail.

Any imported capabilities are derived from the application Subsystem content. An application Subsystem implicitly imports any capabilities required to satisfy requirements from the Subsystem contents that are not satisfied by the capabilities of the Subsystem content.

Unsatisfied mandatory requirements result in a subsystem installation failure. Unsatisfied optional requirements do not. However, implementations must ensure any unsatisfied optional requirements are added to the sharing policy.

134.16.2.1 Package Imports

Application resolution is required to prefer packages provided by content bundles over those provided outside the application. For this reason, the application Subsystem sharing policy only imports packages corresponding to Import-Package statements from the content bundles that are not satisfied when resolving the application contents in isolation. This is equivalent to first resolving the Subsystem-Content requirements to determine the Deployed-Content and then based on this set of resources, determining which Import-Package requirements remain unsatisfied.

A deployment manifest for an application Subsystem would list these package imports using the Import-Package header.

134.16.2.2 Service Imports

Application resolution is required to prefer services provided by content bundles over those provided outside the application. For this reason, the application Subsystem sharing policy only imports services required by the Subsystem's content bundles that are not also provided by the content bundles. This specification provides a means of declaratively identifying the services a bundle provides or requires using the Provide-Capability and Require-Capability headers with the osgi.service namespace. See osgi.service Namespace

An example of a bundle providing the service and declaring it using the Provide-Capability header is as follows:

Provide-Capability: osgi.service;
 objectClass:List<String>="com.foo.MyService";
 uses:="com.foo"

Note that declaring a provided service in this manner only affects resolution. It does not affect service visibility at runtime. In other words, a subsystem that imports service com.acme.Foo will see all of the corresponding service registrations that its parent sees regardless of whether or not the provider declared this service in the Provide-Capability header.

An example of a bundle requiring a service and declaring the requirement using the Require-Capability header is as follows:

Require-Capability: osgi.service;
 filter:="(objectClass=com.foo.MyService)";
 effective:="active"

These headers can be hand-written (e.g., to declare programmatic use of an OSGi service) or generated by a tool (e.g., BND) based on a declarative component model configuration (e.g., Declarative Services or Blueprint). A Subsystems implementation must assume these headers, if present, declare all of the service dependencies. Implementations must therefore not search the bundle for additional dependencies from other sources.

A deployment manifest for an application Subsystem would list these service imports using the Subsystem-ImportService header.

134.16.2.3 Bundle Requirements

Application resolution is required to prefer bundle capabilities provided by content bundles over those provided outside the application. For this reason, the application Subsystem sharing policy only requires bundle capabilities corresponding to Require-Bundle statements from the content bundles that are not satisfied when resolving the application contents in isolation. This is equivalent to first resolving the Subsystem-Content requirements to determine the Deployed-Content and then based on this set of resources, determining which Require-Bundle requirements remain unsatisfied.

A Deployment Manifest for an application Subsystem would list these bundle requirements using the Require-Bundle header.

134.16.2.4 Generic Requirements

Application resolution is required to prefer generic capabilities provided by content bundles over those provided outside the application. For this reason, the application Subsystem sharing policy only generic requirements corresponding to Require-Capability statements from the content bundles that are not satisfied by Provide-Capability statements of the content bundles when resolving the application contents in isolation. This is equivalent to first resolving the Subsystem-Content requirements to determine the Deployed-Content and then based on this set of resources, determining which Require-Capability statements remain unsatisfied.

An deployment manifest for an application Subsystem would list these generic requirements using the Require-Capability header.

134.16.2.5 Dependencies

Application Subsystems' implicit requirements are determined as described in the Application Deployment section in Determining Dependencies. Any mandatory requirements from constituents that are not satisfied by capabilities provided by the target environment or other constituents must be satisfied by additional dependencies. The Subsystem runtime is responsible for provisioning these based on the Subsystem's provision policy or those of its scoped parents. If the application Subsystem has an associated deployment manifest, then these resources are described in the Provision-Resource header.

134.16.3 Composite

A composite is a Scoped Subsystem with a sharing policy that by default does not share anything with its parent and therefore all sharing is fully explicit. Capabilities, such as packages and services, may be explicitly imported into or exported out of the composite.

A Subsystem is identified as an composite by specifying a Subsystem type value of osgi.subsystem.composite in the Subsystem manifest.

Subsystem-Type: osgi.subsystem.composite

134.16.3.1 Subsystem Content

The Subsystem-Content header allows version ranges for content resources. For composite Subsystems, this value must be a fixed version range (e.g. [1.0, 1.0]) for resources of type osgi.bundle, osgi.fragment, osgi.subsystem.application, osgi.subsystem.composite, and osgi.subsystem.feature. This is due to the fact that there is an inextricable link between the versions on the explicit import and export statements made on a composite and the chosen versions of the content bundles. Allowing variability in the content versions for these types of resources risks introducing incompatibilities with sharing policy for the composite. If a composite Subsystem does not use strict version ranges then the composite Subsystem must fail to install.

134.16.3.2 Package Imports

A composite Subsystem explicitly states the packages it imports using the Import-Package header. If the composite includes a deployment manifest then the Import-Package header is used to describe these and they must be identical (logically, not syntactically) to the Import-Package headers in the composite's Subsystem manifest. If the imports are not the same then the Subsystem runtime should log an error and must fail the installation.

134.16.3.3 Package Exports

A composite Subsystem explicitly states the packages it exports using the Export-Package header. If the composite includes a deployment manifest then the Export-Package header is used to describe these and they must be identical (logically, not syntactically) to the Export-Package headers in the composite's Subsystem manifest. If the exports are not the same then the Subsystem runtime should log an error and must fail the installation.

134.16.3.4 Service Imports

A composite Subsystem explicitly states the services it imports using the Subsystem-ImportService header (see Subsystem-ImportService ). For example:

Subsystem-ImportService: com.acme.logging.Log

If the composite includes a deployment manifest then the Subsystem-ImportService header is used to describe these and they must be identical (logically, not syntactically) to the Subsystem-ImportService headers in the composite's Subsystem manifest. If the imports are not the same then the Subsystem runtime should log an error and must fail the installation.

134.16.3.5 Service Exports

A composite Subsystem explicitly states the services it exports using the Subsystem-ExportService header (see Subsystem-ExportService ). For example:

Subsystem-ServiceExport: com.acme.logging.Log

If the composite includes a deployment manifest then the Subsystem-ExportService header is used to describe these and they must be identical (logically, not syntactically) to the Subsystem-ExportService headers in the composite's Subsystem manifest. If the exports are not the same then the Subsystem runtime should log an error and must fail the installation.

134.16.3.6 Bundle Requirements

A composite Subsystem explicitly states the bundles it requires using the Require-Bundle header.

If the composite includes a deployment manifest then the Require-Bundle header is used to describe these and the requirements must be identical (logically, not syntactically) to the Require-Bundle requirements in the composite's Subsystem manifest. If the requirements are not the same then the Subsystem runtime should log an error and must fail the installation.

134.16.3.7 Generic Requirements

A composite Subsystem explicitly states the generic capabilities it requires using the Require-Capability header.

If the composite includes a deployment manifest then the Require-Capability header is used to describe these and they must be identical (logically, not syntactically) to the Require-Capability headers in the composite's Subsystem manifest. If the capability requirements are not the same then the Subsystem runtime should log an error and must fail the installation.

134.16.3.8 Generic Capabilities

A composite Subsystem explicitly states the generic capabilities it provides using the Provide-Capability header.

If the composite includes a deployment manifest then the Provide-Capability header is used to describe these and they must be identical (logically, not syntactically) to the Provide-Capability headers in the composite's Subsystem manifest. If the capabilities are not the same then the Subsystem runtime should log an error and must fail the installation.

134.16.3.9 Dependencies

A composite Subsystem's explicit requirements are stated in the Subsystem manifest. Any mandatory requirements that are not satisfied by capabilities provided by the target environment must be satisfied by additional dependencies. The Subsystem runtime is responsible for provisioning these based on the Subsystem's provision policy or the provision policy of its scoped parents. If the composite Subsystem has an associated deployment manifest, then these resources are described in the Provision-Resource header.

134.16.4 Feature

A feature is an Unscoped Subsystem and therefore provides no isolation of its own. A feature does however always exist in the context of one and only one Region which can restrict the capabilities a feature can see and the extent to which a feature's capabilities are shared.

A Subsystem is identified as a feature by specifying a Subsystem type value of osgi.subsystem.feature in the Subsystem manifest.

Subsystem-Type: osgi.subsystem.feature

134.16.4.1 Explicit Requirements and Capabilities

A feature Subsystem implicitly imports and exports all requirements and capabilities. If the feature Subsystem include any headers designed to modify the sharing policy of a Subsystem, such as Import-Package or Subsystem-ImportService, then the Subsystem runtime should log an error and must fail the installation of the Subsystem.

134.16.4.2 Dependencies

Feature Subsystems implicitly import all capabilities. A Subsystem runtime is responsible for provisioning any dependencies necessary for the Subsystem's constituents to resolve. The calculation of the dependencies can also take into account capabilities provided by the target runtime. The dependencies can include resources that provide capabilities equivalent to those provided by one or more of the constituent resources where the dependency's capability is a considered a better match in the context of some resolution. The Subsystem runtime is responsible for provisioning the dependencies based on the Subsystem's provision policy or the provision policy of its scoped parents. If the feature Subsystem has an associated deployment manifest, then these dependencies are described in the Provision-Resource header.

134.17 Weaving Hooks

Subsystems implementations must ensure that dynamic package imports added by weaving hooks are available to subsystems whose classes have been woven by updating the sharing policies.

Dynamic package imports added by weaving hooks are observed by registering a WovenClassListener service and receiving notifications via the WovenClassListener.modified(WovenClass) method. The sharing policy must be updated while the woven class is in the TRANSFORMED state so that it takes effect before the bundle wiring is updated during the transition to DEFINED; otherwise, the class would fail to load.

The bundle containing the woven class can be obtained by calling the WovenClass.getBundleWiring().getBundle() method. A bundle might be a constituent of multiple subsystems, but never more than one scoped subsystem. The rest are features, which have no sharing policies to update. It's possible the bundle will not be a constituent of a scoped subsystem. The scoped subsystem, if any, containing the bundle as a constituent is retrieved.

It's possible for a class load request to occur on a bundle in an unresolved subsystem because the framework is free to resolve bundles whenever it desires. A resolved bundle can potentially receive a class load request. For example, a BundleEventListener registered with the system bundle context could receive the RESOLVED event and, for whatever reason, load a class. Also, a resolved bundle in an unresolved feature might get wired to another bundle. If this is the case, the subsystem must be resolved in order to guarantee the dynamic imports will not effect the resolution and, therefore, potentially create a wiring inconsistent with the deployment manifest. Just as the framework is free to resolve bundles at anytime and for whatever reason, Subsystems implementations are free to resolve subsystems.

The sharing policy is only updated if the dynamic import cannot be completely satisfied from within the subsystem. Note that all dynamic imports with a wildcard must always be added to the sharing policy.

134.18 Stopping and Uninstalling Subsystems Implementation

When the Subsystems implementation is stopped all of the installed Subsystems must be persistently stored and present when the Subsystems implementation becomes active again. This includes any bundles that got installed as part of a Subsystem installation. The Subsystems implementation is not required to do any additional cleanup when the Subsystems implementation is stopped or uninstalled. All bundles that got installed as a result of installing a Subsystem may still be installed after stopping or uninstalling the Subsystems implementation bundle. If it is important to clean up the bundles associated with a Subsystem installation then the Subsystem should be uninstalled before uninstalling the Subsystems implementation.

134.19 Capabilities

Implementations of the Subsystem Service specification must provide the following capabilities.

  • A capability in the osgi.implementation namespace declaring the implemented specification to be osgi.subsystem. This capability must also declare a uses constraint for the org.osgi.service.subsystem package. For example:

    Provide-Capability: osgi.implementation;
        osgi.implementation="osgi.subsystem";
        version:Version="1.1";
        uses:="org.osgi.service.subsystem"

    This capability must follow the rules defined for the osgi.implementation Namespace.

  • A capability in the osgi.service namespace representing the Subsystem service. This capability must also declare a uses constraint for the org.osgi.service.subsystem package. For example:

    Provide-Capability: osgi.service;
        objectClass:List<String>="org.osgi.service.subsystem.Subsystem";
        uses:="org.osgi.service.subsystem"

    This capability must follow the rules defined for the osgi.service Namespace.

134.20 Security

134.20.1 Subsystem Permission

The Subsystem Permission is a permission used to grant the right to manage Subsystems with the option to restrict this right to a subset of Subsystems, called targets. For example, an operator can give a bundle the right to only manage Subsystems with a symbolic-name prefix of com.acme.:

...SubsystemPermission("(name=com.acme.*)",
...)

The actions of Subsystem Permission are fine-grained. They allow a deployer to assign only the permissions that are necessary for a bundle. For example, a bundle may be granted only the permission to start and stop all Subsystems:

...SubsystemPermission["*", EXECUTE]

Code that needs to check Subsystem Permission must always use the constructor that takes a Subsystem as a parameter: SubsystemPermission(Subsystem, String) with a single action.

For example, the implementation of Subsystem.start method must check that the caller has access to execute the Subsystem:

public class SubsystemImpl implements Subsystem{
    public void start() {
        securityManager.checkPermission(new SubsystemPermission(this,"execute"));
    }
}

The Subsystem Permission takes a Filter as its name argument. Filter based permissions are described in [1] Filter Based Permissions. Subsystem Archives are not signed and therefore the signer key is not supported. The keys have the following meaning for the Subsystem Permission:

  • id - The Subsystem ID of a Subsystem. For example (id=23)

  • location - The location of a Subsystem. For example (location=https://www.acme.com/download/*)

  • name - The symbolic name of a Subsystem. For example (name=com.acme.*)

The name parameter of the permission can also be a single wildcard character ('*' \u002a). In that case all Subsystems must match.

134.20.2 Actions

The action parameter of Subsystem Permission will specify the subset of privileged Subsystem management operations that are allowed. The actions that are architected are listed below. Future versions of the specification can add additional actions. The given set should therefore not be assumed to be a closed set.

Table 134.3 Actions

Action Used in
CONTEXT

Subsystem.getBundleContext

METADATA

Subsystem.getSubsystemHeaders

Subsystem.getLocation

LIFECYCLE

Subsystem.install

Subsystem.uninstall

EXECUTE

Subsystem.start

Subsystem.stop


134.20.3 Required Permissions

A Subsystems implementation must check the caller for the appropriate Subsystem Permission before initiating a Subsystem management operation (e.g. install, start, stop, uninstall). Once the Subsystem Permission is checked against the caller the Subsystems implementation will proceed with the actual Subsystem operation. This operation will require a number of other permissions to complete. For example, the Admin Permission will be needed to install, start, stop, and uninstall resources of type osgi.bundle for a Subsystem. The Subsystems implementation must isolate the caller from such permission checks by use of a proper doPrivileged block.

134.21 org.osgi.service.subsystem

Version 1.1

Subsystem Service Package Version 1.1.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.subsystem; version="[1.1,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.subsystem; version="[1.1,1.2)"

134.21.1 Summary

  • Subsystem - A subsystem is a collection of resources constituting a logical, possibly isolated, unit of functionality.

  • Subsystem.State - An enumeration of the possible states of a subsystem.

  • SubsystemConstants - Defines the constants used by Subsystem service property, manifest header, attribute and directive keys.

  • SubsystemException - A Subsystem exception used to indicate a problem.

  • SubsystemPermission - A bundle's authority to perform specific privileged administrative operations on or to get sensitive information about a subsystem.

134.21.2 public interface Subsystem

A subsystem is a collection of resources constituting a logical, possibly isolated, unit of functionality.

A subsystem may be scoped or unscoped. Scoped subsystems are isolated by implicit or explicit sharing policies. Unscoped subsystems are not isolated and, therefore, have no sharing policy. There are three standard types of subsystems.

  • Application - An implicitly scoped subsystem. Nothing is exported, and imports are computed based on any unsatisfied content requirements.

  • Composite - An explicitly scoped subsystem. The sharing policy is defined by metadata within the subsystem archive.

  • Feature - An unscoped subsystem.

Conceptually, a subsystem may be thought of as existing in an isolated region along with zero or more other subsystems. Each region has one and only one scoped subsystem, which dictates the sharing policy. The region may, however, have many unscoped subsystems. It is, therefore, possible to have shared constituents across multiple subsystems within a region. Associated with each region is a bundle whose context may be retrieved from any subsystem within that region. This context may be used to monitor activity occurring within the region.

A subsystem may have children and, unless it's the root subsystem, must have at least one parent. Subsystems become children of the subsystem in which they are installed. Unscoped subsystems have more than one parent if they are installed in more than one subsystem within the same region. The subsystem graph may be thought of as an acyclic digraph with one and only one source vertex, which is the root subsystem. The edges have the child as the head and parent as the tail.

A subsystem has several identifiers.

  • Location - An identifier specified by the client as part of installation. It is guaranteed to be unique within the same framework.

  • ID - An identifier generated by the implementation as part of installation. It is guaranteed to be unique within the same framework.

  • Symbolic Name/Version - The combination of symbolic name and version is guaranteed to be unique within the same region. Although type is not formally part of the identity, two subsystems with the same symbolic names and versions but different types are not considered to be equal.

A subsystem has a well-defined life cycle. Which stage a subsystem is in may be obtained from the subsystem's state and is dependent on which life cycle operation is currently active or was last invoked.

A subsystem archive is a ZIP file having an .esa extension and containing metadata describing the subsystem. The form of the metadata may be a subsystem or deployment manifest, as well as any content resource files. The manifests are optional and will be computed if not present. The subsystem manifest headers may be retrieved in raw or localized forms. There are five standard types of resources that may be included in a subsystem.

Resources contained by a subsystem are called constituents. There are several ways a resource may become a constituent of a subsystem:

  • A resource is listed as part of the subsystem's content.

  • A subsystem resource is a child of the subsystem.

  • The subsystem has a provision policy of accept dependencies.

  • A bundle resource is installed using the region bundle context.

  • A bundle resource is installed using the bundle context of another resource contained by the subsystem.

In addition to invoking one of the install methods, a subsystem instance may be obtained through the service registry. Each installed subsystem has a corresponding service registration. A subsystem service has the following properties.

  • ID - The ID of the subsystem.

  • Symbolic Name - The symbolic name of the subsystem.

  • Version - The version of the subsystem.

  • Type - The type of the subsystem.

  • State - The state of the subsystem.

Because a subsystem must be used to install other subsystems, a root subsystem is provided as a starting point. The root subsystem may only be obtained as a service and has the following characteristics.

Thread-safe

Consumers of this API must not implement this type

134.21.2.1 public BundleContext getBundleContext()

Returns the bundle context of the region within which this subsystem resides.

The bundle context offers the same perspective of any resource contained by a subsystem within the region. It may be used, for example, to monitor events internal to the region as well as external events visible to the region. All subsystems within the same region have the same bundle context. If this subsystem is in a state where the bundle context would be invalid, null is returned.

The bundle context of the region within which this subsystem resides or null if this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

SecurityException– If the caller does not have the appropriate SubsystemPermission[this,CONTEXT], and the runtime supports permissions.

134.21.2.2 public Collection<Subsystem> getChildren()

Returns the child subsystems of this subsystem.

The child subsystems of this subsystem. The returned collection is an unmodifiable snapshot of all subsystems that are installed in this subsystem. The collection will be empty if no subsystems are installed in this subsystem.

IllegalStateException– If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

134.21.2.3 public Collection<Resource> getConstituents()

Returns the constituent resources of this subsystem.

The constituent resources of this subsystem. The returned collection is an unmodifiable snapshot of the constituent resources of this subsystem. If this subsystem has no constituents, the collection will be empty.

IllegalStateException– If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

134.21.2.4 public Map<String, String> getDeploymentHeaders()

Returns the headers for this subsystem's deployment manifest.

Each key in the map is a header name and the value of the key is the corresponding header value. Because header names are case-insensitive, the methods of the map must treat the keys in a case-insensitive manner. If the header name is not found, null is returned. Both original and derived headers will be included in the map.

This method must continue to return the headers while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The headers for this subsystem's deployment manifest. The returned map is unmodifiable.

SecurityException– If the caller does not have the appropriate SubsystemPermission[this,METADATA], and the runtime supports permissions.

1.1

134.21.2.5 public String getLocation()

Returns the location identifier of this subsystem.

The location identifier is the location that was passed to the install method of the parent subsystem. It is unique within the framework.

This method must continue to return this subsystem's headers while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The location identifier of this subsystem.

SecurityException– If the caller does not have the appropriate SubsystemPermission[this,METADATA], and the runtime supports permissions.

134.21.2.6 public Collection<Subsystem> getParents()

Returns the parent subsystems of this subsystem.

The parent subsystems of this subsystem. The returned collection is an unmodifiable snapshot of all subsystems in which this subsystem is installed. The collection will be empty for the root subsystem; otherwise, it must contain at least one parent. Scoped subsystems always have only one parent. Unscoped subsystems may have multiple parents.

IllegalStateException– If this subsystem's state is in INSTALL_FAILED, UNINSTALLED.

134.21.2.7 public Subsystem.State getState()

Returns the current state of this subsystem.

This method must continue to return this subsystem's state while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The current state of this subsystem.

134.21.2.8 public Map<String, String> getSubsystemHeaders(Locale locale)

The locale for which translations are desired. The header values are translated according to the specified locale. If the specified locale is null or not supported, the raw values are returned. If the translation for a particular header is not found, the raw value is returned.

Returns the headers for this subsystem's subsystem manifest.

Each key in the map is a header name and the value of the key is the corresponding header value. Because header names are case-insensitive, the methods of the map must treat the keys in a case-insensitive manner. If the header name is not found, null is returned. Both original and derived headers will be included in the map.

This method must continue to return the headers while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The headers for this subsystem's subsystem manifest. The returned map is unmodifiable.

SecurityException– If the caller does not have the appropriate SubsystemPermission[this,METADATA], and the runtime supports permissions.

134.21.2.9 public long getSubsystemId()

Returns the identifier of this subsystem.

The identifier is a monotonically increasing, non-negative integer automatically generated at installation time and guaranteed to be unique within the framework. The identifier of the root subsystem is zero.

This method must continue to return this subsystem's identifier while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The identifier of this subsystem.

134.21.2.10 public String getSymbolicName()

Returns the symbolic name of this subsystem.

The subsystem symbolic name conforms to the same grammar rules as the bundle symbolic name and is derived from one of the following, in order.

  • The value of the Subsystem-SymbolicName header, if specified.

  • The subsystem URI if passed as the location along with the content to the install method.

  • Optionally generated in an implementation specific way.

The combination of subsystem symbolic name and version is unique within a region. The symbolic name of the root subsystem is org.osgi.service.subsystem.root.

This method must continue to return this subsystem's symbolic name while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The symbolic name of this subsystem.

134.21.2.11 public String getType()

Returns the type of this subsystem.

This method must continue to return this subsystem's type while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The type of this subsystem.

134.21.2.12 public Version getVersion()

Returns the version of this subsystem.

The subsystem version conforms to the same grammar rules as the bundle version and is derived from one of the following, in order.

  • The value of the Subsystem-Version header, if specified.

  • The subsystem URI if passed as the location along with the content to the install method.

  • Defaults to 0.0.0.

The combination of subsystem symbolic name and version is unique within a region. The version of the root subsystem matches this specification's version.

This method must continue to return this subsystem's version while this subsystem is in the INSTALL_FAILED or UNINSTALLED states.

The version of this subsystem.

134.21.2.13 public Subsystem install(String location)

The location identifier of the subsystem to install.

Installs a subsystem from the specified location identifier.

This method performs the same function as calling install(String, InputStream) with the specified location identifier and null as the content.

The installed subsystem.

IllegalStateException– If this subsystem's state is in INSTALLING, INSTALL_FAILED, UNINSTALLING, UNINSTALLED.

SubsystemException– If the installation failed.

SecurityException– If the caller does not have the appropriate SubsystemPermission[installed subsystem,LIFECYCLE], and the runtime supports permissions.

install(String, InputStream)

134.21.2.14 public Subsystem install(String location, InputStream content)

The location identifier of the subsystem to be installed.

The input stream from which this subsystem will be read or null to indicate the input stream must be created from the specified location identifier. The input stream will always be closed when this method completes, even if an exception is thrown.

Installs a subsystem from the specified content.

The specified location will be used as an identifier of the subsystem. Every installed subsystem is uniquely identified by its location, which is typically in the form of a URI. If the specified location conforms to the subsystem-uri grammar, the required symbolic name and optional version information will be used as default values.

If the specified content is null, a new input stream must be created from which to read the subsystem by interpreting, in an implementation dependent manner, the specified location.

A subsystem installation must be persistent. That is, an installed subsystem must remain installed across Framework and VM restarts.

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

The following steps are required to install a subsystem.

  1. If an installed subsystem with the specified location identifier already exists, return the installed subsystem.

  2. Read the specified content in order to determine the symbolic name, version, and type of the installing subsystem. If an error occurs while reading the content, an installation failure results.

  3. If an installed subsystem with the same symbolic name and version already exists within this subsystem's region, complete the installation with one of the following.

    • If the installing and installed subsystems' types are not equal, an installation failure results.

    • If the installing and installed subsystems' types are equal, and the installed subsystem is already a child of this subsystem, return the installed subsystem.

    • If the installing and installed subsystems' types are equal, and the installed subsystem is not already a child of this subsystem, add the installed subsystem as a child of this subsystem, increment the installed subsystem's reference count by one, and return the installed subsystem.

  4. Create a new subsystem based on the specified location and content.

  5. If the subsystem is scoped, install and start a new region context bundle.

  6. Change the state to INSTALLING and register a new subsystem service.

  7. Discover the subsystem's content resources. If any mandatory resource is missing, an installation failure results.

  8. Discover the dependencies required by the content resources. If any mandatory dependency is missing, an installation failure results.

  9. Using a framework ResolverHook, disable runtime resolution for the resources.

  10. For each resource, increment the reference count by one. If the reference count is one, install the resource. If an error occurs while installing a resource, an install failure results with that error as the cause.

  11. If the subsystem is scoped, enable the import sharing policy.

  12. Enable runtime resolution for the resources.

  13. Change the state of the subsystem to INSTALLED.

  14. Return the new subsystem.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption. An interrupted thread should result in a SubsystemException with an InterruptedException as the cause and be treated as an installation failure.

All installation failure flows include the following, in order.

  1. Change the state to INSTALL_FAILED.

  2. Change the state to UNINSTALLING.

  3. All content and dependencies which may have been installed by the installing process must be uninstalled.

  4. Change the state to UNINSTALLED.

  5. Unregister the subsystem service.

  6. If the subsystem is a scoped subsystem then, uninstall the region context bundle.

  7. Throw a SubsystemException with the cause of the installation failure.

The installed subsystem.

IllegalStateException– If this subsystem's state is in INSTALLING, INSTALL_FAILED, UNINSTALLING, UNINSTALLED.

SubsystemException– If the installation failed.

SecurityException– If the caller does not have the appropriate SubsystemPermission[installed subsystem,LIFECYCLE], and the runtime supports permissions.

134.21.2.15 public Subsystem install(String location, InputStream content, InputStream deploymentManifest)

The location identifier of the subsystem to be installed.

The input stream from which this subsystem will be read or null to indicate the input stream must be created from the specified location identifier. The input stream will always be closed when this method completes, even if an exception is thrown.

The deployment manifest to use in lieu of the one in the archive, if any, or a computed one.

Installs a subsystem from the specified content according to the specified deployment manifest.

This method installs a subsystem using the provided deployment manifest instead of the one in the archive, if any, or a computed one. If the deployment manifest is null, the behavior is exactly the same as in the install(String, InputStream) method. Implementations must support deployment manifest input streams in the format described by section 134.2 of the Subsystem Service Specification. If the deployment manifest does not conform to the subsystem manifest (see 134.15.2), the installation fails.

The installed subsystem.

IllegalStateException– If this subsystem's state is in INSTALLING, INSTALL_FAILED, UNINSTALLING, UNINSTALLED.

SubsystemException– If the installation failed.

SecurityException– If the caller does not have the appropriate SubsystemPermission[installed subsystem,LIFECYCLE], and the runtime supports permissions.

1.1

134.21.2.16 public void start()

Starts this subsystem.

The following table shows which actions are associated with each state. An action of Wait means this method will block until a state transition occurs, upon which the new state will be evaluated in order to determine how to proceed. If a state transition does not occur in a reasonable time while waiting then no action is taken and a SubsystemException is thrown to indicate the subsystem was unable to be started. An action of Return means this method returns immediately without taking any other action.

State Action
INSTALLING Wait
INSTALLED Resolve, Start
INSTALL_FAILED IllegalStateException
RESOLVING Wait
RESOLVED Start
STARTING Wait
ACTIVE Return
STOPPING Wait
UNINSTALLING IllegalStateException
UNINSTALLED IllegalStateException

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

A subsystem must be persistently started. That is, a started subsystem must be restarted across Framework and VM restarts, even if a start failure occurs.

The following steps are required to start this subsystem.

  1. Set the subsystem autostart setting to started.

  2. If this subsystem is in the RESOLVED state, proceed to step 7.

  3. Change the state to RESOLVING.

  4. Resolve the content resources. A resolution failure results in a start failure with a state of INSTALLED.

  5. Change the state to RESOLVED.

  6. If this subsystem is scoped, enable the export sharing policy.

  7. Change the state to STARTING.

  8. For each eligible resource, increment the active use count by one. If the active use count is one, start the resource. All dependencies must be started before any content resource, and content resources must be started according to the specified start order. If an error occurs while starting a resource, a start failure results with that error as the cause.

  9. Change the state to ACTIVE.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption. An interrupted thread should be treated as a start failure with an InterruptedException as the cause.

All start failure flows include the following, in order.

  1. If the subsystem state is STARTING then change the state to STOPPING and stop all resources that were started as part of this operation.

  2. Change the state to either INSTALLED or RESOLVED.

  3. Throw a SubsystemException with the specified cause.

SubsystemException– If this subsystem fails to start.

IllegalStateException– If this subsystem's state is in INSTALL_FAILED, UNINSTALLING, or UNINSTALLED, or if the state of at least one of this subsystem's parents is not in STARTING, ACTIVE.

SecurityException– If the caller does not have the appropriate SubsystemPermission[this,EXECUTE], and the runtime supports permissions.

134.21.2.17 public void stop()

Stops this subsystem.

The following table shows which actions are associated with each state. An action of Wait means this method will block until a state transition occurs, upon which the new state will be evaluated in order to determine how to proceed. If a state transition does not occur in a reasonable time while waiting then no action is taken and a SubsystemException is thrown to indicate the subsystem was unable to be stopped. An action of Return means this method returns immediately without taking any other action.

State Action
INSTALLING Wait
INSTALLED Return
INSTALL_FAILED IllegalStateException
RESOLVING Wait
RESOLVED Return
STARTING Wait
ACTIVE Stop
STOPPING Wait
UNINSTALLING IllegalStateException
UNINSTALLED IllegalStateException

A subsystem must be persistently stopped. That is, a stopped subsystem must remain stopped across Framework and VM restarts.

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

The following steps are required to stop this subsystem.

  1. Set the subsystem autostart setting to stopped.

  2. Change the state to STOPPING.

  3. For each eligible resource, decrement the active use count by one. If the active use count is zero, stop the resource. All content resources must be stopped before any dependencies, and content resources must be stopped in reverse start order.

  4. Change the state to RESOLVED.

With regard to error handling, once this subsystem has transitioned to the STOPPING state, every part of each step above must be attempted. Errors subsequent to the first should be logged. Once the stop process has completed, a SubsystemException must be thrown with the initial error as the specified cause.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption, in which case a SubsystemException with an InterruptedException as the cause should be thrown. If an interruption occurs while waiting, this method should terminate immediately. Once the transition to the STOPPING state has occurred, however, this method must not terminate due to an interruption until the stop process has completed.

SubsystemException– If this subsystem fails to stop cleanly.

IllegalStateException– If this subsystem's state is in INSTALL_FAILED, UNINSTALLING, or UNINSTALLED.

SecurityException– If the caller does not have the appropriate SubsystemPermission[this,EXECUTE], and the runtime supports permissions.

134.21.2.18 public void uninstall()

Uninstalls this subsystem.

The following table shows which actions are associated with each state. An action of Wait means this method will block until a state transition occurs, upon which the new state will be evaluated in order to determine how to proceed. If a state transition does not occur in a reasonable time while waiting then no action is taken and a SubsystemException is thrown to indicate the subsystem was unable to be uninstalled. An action of Return means this method returns immediately without taking any other action.

State Action
INSTALLING Wait
INSTALLED Uninstall
INSTALL_FAILED Wait
RESOLVING Wait
RESOLVED Uninstall
STARTING Wait
ACTIVE Stop, Uninstall
STOPPING Wait
UNINSTALLING Wait
UNINSTALLED Return

All references to changing the state of this subsystem include both changing the state of the subsystem object as well as the state property of the subsystem service registration.

The following steps are required to uninstall this subsystem after being stopped if necessary.

  1. Change the state to INSTALLED.

  2. Change the state to UNINSTALLING.

  3. For each referenced resource, decrement the reference count by one. If the reference count is zero, uninstall the resource. All content resources must be uninstalled before any dependencies.

  4. Change the state to UNINSTALLED.

  5. Unregister the subsystem service.

  6. If the subsystem is scoped, uninstall the region context bundle.

With regard to error handling, once this subsystem has transitioned to the UNINSTALLING state, every part of each step above must be attempted. Errors subsequent to the first should be logged. Once the uninstall process has completed, a SubsystemException must be thrown with the specified cause.

Implementations should be sensitive to the potential for long running operations and periodically check the current thread for interruption, in which case a SubsystemException with an InterruptedException as the cause should be thrown. If an interruption occurs while waiting, this method should terminate immediately. Once the transition to the UNINSTALLING state has occurred, however, this method must not terminate due to an interruption until the uninstall process has completed.

SubsystemException– If this subsystem fails to uninstall cleanly.

SecurityException– If the caller does not have the appropriate SubsystemPermission[this,LIFECYCLE], and the runtime supports permissions.

134.21.3 enum Subsystem.State

An enumeration of the possible states of a subsystem.

These states are a reflection of what constituent resources are permitted to do and not an aggregation of constituent resource states.

134.21.3.1 INSTALLING

The subsystem is in the process of installing.

A subsystem is in the INSTALLING state when the install method of its parent is active, and attempts are being made to install its content resources. If the install method completes without exception, then the subsystem has successfully installed and must move to the INSTALLED state. Otherwise, the subsystem has failed to install and must move to the INSTALL_FAILED state.

134.21.3.2 INSTALLED

The subsystem is installed but not yet resolved.

A subsystem is in the INSTALLED state when it has been installed in a parent subsystem but is not or cannot be resolved. This state is visible if the dependencies of the subsystem's content resources cannot be resolved.

134.21.3.3 INSTALL_FAILED

The subsystem failed to install.

A subsystem is in the INSTALL_FAILED state when an unrecoverable error occurred during installation. The subsystem is in an unusable state but references to the subsystem object may still be available and used for introspection.

134.21.3.4 RESOLVING

The subsystem is in the process of resolving.

A subsystem is in the RESOLVING state when attempts are being made to resolve its content resources. If the resolve process completes without exception, then the subsystem has successfully resolved and must move to the RESOLVED state. Otherwise, the subsystem has failed to resolve and must move to the INSTALLED state.

134.21.3.5 RESOLVED

The subsystem is resolved and able to be started.

A subsystem is in the RESOLVED state when all of its content resources are resolved. Note that the subsystem is not active yet.

134.21.3.6 STARTING

The subsystem is in the process of starting.

A subsystem is in the STARTING state when its start method is active, and attempts are being made to start its content and dependencies. If the start method completes without exception, then the subsystem has successfully started and must move to the ACTIVE state. Otherwise, the subsystem has failed to start and must move to the RESOLVED state.

134.21.3.7 ACTIVE

The subsystem is now running.

A subsystem is in the ACTIVE state when its content and dependencies have been successfully started.

134.21.3.8 STOPPING

The subsystem is in the process of stopping.

A subsystem is in the STOPPING state when its stop method is active, and attempts are being made to stop its content and dependencies. When the stop method completes, the subsystem is stopped and must move to the RESOLVED state.

134.21.3.9 UNINSTALLING

The subsystem is in the process of uninstalling.

A subsystem is in the UNINSTALLING state when its uninstall method is active, and attempts are being made to uninstall its constituent and dependencies. When the uninstall method completes, the subsystem is uninstalled and must move to the UNINSTALLED state.

134.21.3.10 UNINSTALLED

The subsystem is uninstalled and may not be used.

The UNINSTALLED state is only visible after a subsystem's constituent and dependencies are uninstalled. The subsystem is in an unusable state but references to the subsystem object may still be available and used for introspection.

134.21.3.11 public static Subsystem.State valueOf(String name)

134.21.3.12 public static Subsystem.State[] values()

134.21.4 public class SubsystemConstants

Defines the constants used by Subsystem service property, manifest header, attribute and directive keys.

The values associated with these keys are of type String, unless otherwise indicated.

Immutable

134.21.4.1 public static final String DEPLOYED_CONTENT = "Deployed-Content"

Manifest header identifying the resources to be deployed.

134.21.4.2 public static final String DEPLOYED_VERSION_ATTRIBUTE = "deployed-version"

Manifest header attribute identifying the deployed version.

134.21.4.3 public static final String DEPLOYMENT_MANIFESTVERSION = "Deployment-ManifestVersion"

Manifest header identifying the deployment manifest version. If not present, the default value is 1.

134.21.4.4 public static final String PREFERRED_PROVIDER = "Preferred-Provider"

Manifest header used to express a preference for particular resources to satisfy implicit package dependencies.

134.21.4.5 public static final String PROVISION_POLICY_ACCEPT_DEPENDENCIES = "acceptDependencies"

A value for the provision-policy directive indicating the subsystem accepts dependency resources. The root subsystem has this provision policy.

134.21.4.6 public static final String PROVISION_POLICY_DIRECTIVE = "provision-policy"

Manifest header directive identifying the provision policy. The default value is rejectDependencies

PROVISION_POLICY_ACCEPT_DEPENDENCIES, PROVISION_POLICY_REJECT_DEPENDENCIES

134.21.4.7 public static final String PROVISION_POLICY_REJECT_DEPENDENCIES = "rejectDependencies"

A value for the provision-policy directive indicating the subsystem does not accept dependency resources. This is the default value.

134.21.4.8 public static final String PROVISION_RESOURCE = "Provision-Resource"

Manifest header identifying the resources to be deployed to satisfy the dependencies of a subsystem.

134.21.4.9 public static final String ROOT_SUBSYSTEM_SYMBOLICNAME = "org.osgi.service.subsystem.root"

The symbolic name of the root subsystem.

134.21.4.10 public static final String START_ORDER_DIRECTIVE = "start-order"

Manifest header directive identifying the start order of subsystem contents. There is no default value. Specified values are of type String and must represent an integer.

134.21.4.11 public static final String SUBSYSTEM_CATEGORY = "Subsystem-Category"

Manifest header identifying the categories of a subsystem as a comma-delimited list.

1.1

134.21.4.12 public static final String SUBSYSTEM_CONTACTADDRESS = "Subsystem-ContactAddress"

Manifest header identifying the contact address where problems with a subsystem may be reported; for example, an email address.

1.1

134.21.4.13 public static final String SUBSYSTEM_CONTENT = "Subsystem-Content"

Manifest header identifying the list of subsystem contents identified by a symbolic name and version.

134.21.4.14 public static final String SUBSYSTEM_COPYRIGHT = "Subsystem-Copyright"

Manifest header identifying a subsystem's copyright information.

1.1

134.21.4.15 public static final String SUBSYSTEM_DESCRIPTION = "Subsystem-Description"

Manifest header identifying the human readable description.

134.21.4.16 public static final String SUBSYSTEM_DOCURL = "Subsystem-DocURL"

Manifest header identifying a subsystem's documentation URL, from which further information about the subsystem may be obtained.

1.1

134.21.4.17 public static final String SUBSYSTEM_EXPORTSERVICE = "Subsystem-ExportService"

Manifest header identifying services offered for export.

134.21.4.18 public static final String SUBSYSTEM_ICON = "Subsystem-Icon"

Manifest header identifying the icon URL for the subsystem.

1.1

134.21.4.19 public static final String SUBSYSTEM_ID_PROPERTY = "subsystem.id"

The name of the service property for the subsystem ID. The value of this property must be of type Long.

134.21.4.20 public static final String SUBSYSTEM_IMPORTSERVICE = "Subsystem-ImportService"

Manifest header identifying services required for import.

134.21.4.21 public static final String SUBSYSTEM_LICENSE = "Subsystem-License"

Manifest header identifying a subsystem's license.

1.1

134.21.4.22 public static final String SUBSYSTEM_LOCALIZATION = "Subsystem-Localization"

Manifest header identifying the base name of a subsystem's localization entries.

1.1

134.21.4.23 public static final String SUBSYSTEM_LOCALIZATION_DEFAULT_BASENAME = "OSGI-INF/l10n/subsystem"

Default value for the Subsystem-Localization manifest header.

1.1

134.21.4.24 public static final String SUBSYSTEM_MANIFESTVERSION = "Subsystem-ManifestVersion"

Manifest header identifying the subsystem manifest version. If not present, the default value is 1.

134.21.4.25 public static final String SUBSYSTEM_NAME = "Subsystem-Name"

Manifest header identifying the human readable subsystem name.

134.21.4.26 public static final String SUBSYSTEM_STATE_PROPERTY = "subsystem.state"

The name of the service property for the subsystem state. The value of this property must be of type Subsystem.State.

134.21.4.27 public static final String SUBSYSTEM_SYMBOLICNAME = "Subsystem-SymbolicName"

Manifest header value identifying the symbolic name for the subsystem. Must be present.

134.21.4.28 public static final String SUBSYSTEM_SYMBOLICNAME_PROPERTY = "subsystem.symbolicName"

The name of the service property for the subsystem symbolic name.

134.21.4.29 public static final String SUBSYSTEM_TYPE = "Subsystem-Type"

Manifest header identifying the subsystem type.

SUBSYSTEM_TYPE_APPLICATION, SUBSYSTEM_TYPE_COMPOSITE, SUBSYSTEM_TYPE_FEATURE

134.21.4.30 public static final String SUBSYSTEM_TYPE_APPLICATION = "osgi.subsystem.application"

The resource type value identifying an application subsystem.

This value is used for the osgi.identity capability attribute type, the SUBSYSTEM_TYPE manifest header and the SUBSYSTEM_TYPE_PROPERTY service property.

134.21.4.31 public static final String SUBSYSTEM_TYPE_COMPOSITE = "osgi.subsystem.composite"

The resource type value identifying an composite subsystem.

This value is used for the osgi.identity capability attribute type, the SUBSYSTEM_TYPE manifest header and the SUBSYSTEM_TYPE_PROPERTY service property.

134.21.4.32 public static final String SUBSYSTEM_TYPE_FEATURE = "osgi.subsystem.feature"

The resource type value identifying an feature subsystem.

This value is used for the osgi.identity capability attribute type, the SUBSYSTEM_TYPE manifest header and the SUBSYSTEM_TYPE_PROPERTY service property.

134.21.4.33 public static final String SUBSYSTEM_TYPE_PROPERTY = "subsystem.type"

The name of the service property for the subsystem type.

SUBSYSTEM_TYPE_APPLICATION, SUBSYSTEM_TYPE_COMPOSITE, SUBSYSTEM_TYPE_FEATURE

134.21.4.34 public static final String SUBSYSTEM_VENDOR = "Subsystem-Vendor"

Manifest header identifying a subsystem's vendor.

1.1

134.21.4.35 public static final String SUBSYSTEM_VERSION = "Subsystem-Version"

Manifest header value identifying the version of the subsystem. If not present, the default value is 0.0.0.

134.21.4.36 public static final String SUBSYSTEM_VERSION_PROPERTY = "subsystem.version"

The name of the service property for the subsystem version. The value of this property must be of type Version.

134.21.5 public class SubsystemException
extends RuntimeException

A Subsystem exception used to indicate a problem.

134.21.5.1 public SubsystemException()

Construct a Subsystem exception with no message.

134.21.5.2 public SubsystemException(String message)

The message to include in the exception.

Construct a Subsystem exception specifying a message.

134.21.5.3 public SubsystemException(Throwable cause)

The cause of the exception.

Construct a Subsystem exception specifying a cause.

134.21.5.4 public SubsystemException(String message, Throwable cause)

The message to include in the exception.

The cause of the exception.

Construct a Subsystem exception specifying a message and a cause.

134.21.6 public final class SubsystemPermission
extends BasicPermission

A bundle's authority to perform specific privileged administrative operations on or to get sensitive information about a subsystem. The actions for this permission are:

 Action    Methods
 context   Subsystem.getBundleContext
 execute   Subsystem.start
           Subsystem.stop
 lifecycle Subsystem.install
           Subsystem.uninstall
 metadata  Subsystem.getSubsystemHeaders
           Subsystem.getLocation

The name of this permission is a filter expression. The filter gives access to the following attributes:

  • location - The location of a subsystem.

  • id - The subsystem ID of the designated subsystem.

  • name - The symbolic name of a subsystem.

Filter attribute names are processed in a case sensitive manner.

Thread-safe

134.21.6.1 public static final String CONTEXT = "context"

The action string context.

134.21.6.2 public static final String EXECUTE = "execute"

The action string execute.

134.21.6.3 public static final String LIFECYCLE = "lifecycle"

The action string lifecycle.

134.21.6.4 public static final String METADATA = "metadata"

The action string metadata.

134.21.6.5 public SubsystemPermission(String filter, String actions)

A filter expression that can use, location, id, and name keys. Filter attribute names are processed in a case sensitive manner. A special value of "*" can be used to match all subsystems.

execute, lifecycle, metadata, or context.

Create a new SubsystemPermission. This constructor must only be used to create a permission that is going to be checked.

Examples:

 (name=com.acme.*)(location=http://www.acme.com/subsystems/*))
 (id>=1)

IllegalArgumentException– If the filter has an invalid syntax.

134.21.6.6 public SubsystemPermission(Subsystem subsystem, String actions)

A subsystem.

execute, lifecycle, metadata, or context.

Creates a new requested SubsystemPermission object to be used by the code that must perform checkPermission. SubsystemPermission objects created with this constructor cannot be added to an SubsystemPermission permission collection.

134.21.6.7 public boolean equals(Object obj)

The object being compared for equality with this object.

Determines the equality of two SubsystemPermission objects.

true if obj is equivalent to this SubsystemPermission; false otherwise.

134.21.6.8 public String getActions()

Returns the canonical string representation of the SubsystemPermission actions.

Always returns present SubsystemPermission actions in the following order: execute, lifecycle, metadata, context.

Canonical string representation of the SubsystemPermission actions.

134.21.6.9 public int hashCode()

Returns the hash code value for this object.

Hash code value for this object.

134.21.6.10 public boolean implies(Permission p)

The requested permission.

Determines if the specified permission is implied by this object. This method throws an exception if the specified permission was not constructed with a subsystem.

This method returns true if the specified permission is a SubsystemPermission AND

  • this object's filter matches the specified permission's subsystem ID, subsystem symbolic name, and subsystem location OR

  • this object's filter is "*"

AND this object's actions include all of the specified permission's actions.

Special case: if the specified permission was constructed with "*" filter, then this method returns true if this object's filter is "*" and this object's actions include all of the specified permission's actions

true if the specified permission is implied by this object; false otherwise.

134.21.6.11 public PermissionCollection newPermissionCollection()

Returns a new PermissionCollection object suitable for storing SubsystemPermissions.

A new PermissionCollection object.

134.22 References

[1]Filter Based PermissionsOSGi Core, Chapter 2, Filter Based Permissions

[2]Core Service HooksOSGi Core, Chapter 55 Service Hook Service Specification

[3]Resource and WiringOSGi Core, Chapter 6 Resource API Specification

[4]Zip File FormatThe Zip file format as defined by the java.util.zip package.

[6]RFC 1738 Uniform Resource Locatorshttp://www.ietf.org/rfc/rfc1738.txt

[7]Uniform Resource Identifiers (URI): Generic Syntaxhttp://www.ietf.org/rfc/rfc2396.txt

[9]Open Source initiativehttp://www.opensource.org/

[10]Resolver Service SpecificationOSGi Core, Chapter 58 Resolver Service Specification