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.

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:

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).

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

  http://<domain-name>/licenses/
            <license-name>-<version>.<extension>

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

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.

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.

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

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:

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.

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)"

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

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

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

# 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

OSGI-INF/l10n/subsystem_fr_FR.properties.

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

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

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

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.

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:

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

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:

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

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:

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.

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:

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:

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.

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

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

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.

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:

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

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

Then if bundle C uses its own Bundle Context to install bundle F (using a different location string from constituent bundle S2→F) 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

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

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

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:

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.

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:

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

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.

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.

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.

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:

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:

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:

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

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

Figure 134.21 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.

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:

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:

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:

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

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.

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:

All start failures use the following steps:

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:

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.

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:

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.

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:

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

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.

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:

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:

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:

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:

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:

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.

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.

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.

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.

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:

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.

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.

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

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.

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

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

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

Subsystem-ImportService: com.acme.logging.Log

Subsystem-ServiceExport: com.acme.logging.Log

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

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:

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

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.

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.