134 Subsystem Service Specification - OSGi Enterprise 7
OSGi Enterprise Release 7
Prev
Next
134
Subsystem Service Specification
Version 1.1
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
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.
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.
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:
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 ::= '<>' |
( license ( ',' license ) * )
license ::= name ( ';' license-attr ) *
license-attr ::= description | link
description ::= 'description' '=' string
link ::= 'link' '='
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
<>
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:
-.
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
<>
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 ::= [6]
RFC 1738 Uniform Resource Locators
escaped ::= [7]
Uniform Resource Identifiers (URI): Generic Syntax
unreserved ::= [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:
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
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
In this example some constituent of Region
S1Region
provide a capability
S1
. The
S1Region
's
sharing policy exports the capability
S1
to its parent
RootRegion
. The
RootRegion
contains a
constituent which has a requirement
Root
. The export sharing policy of
S1Region
allows visibility to the capability
S1
from the
RootRegion
which allows requirement
Root
to be satisfied by the capability
S1
. The
S2Region
also contains a constituent which has a requirement
on
S2
. The
sharing policy of
S2Region
imports the capability
from its parent Region
RootRegion
. Since
RootRegion
has visibility to the capability
S1
this allows
S2Region
to also have visibility to capability
S1
through its
import sharing policy which allows requirement
S2
to be satisfied by the capability
S1
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
In this example the capability
S3
is exported by the
S3Region
sharing policy to its parent
S1Region
S1Region
also exports
to its parent
RootRegion
. Then
S2Region
imports
from its parent
RootRegion
and finally
S4Region
imports
from its parent
S2Region
. The
visibility path from requirement
S4
to capability
S3
is the
following:
S4
S2
Root
S1
S3
Notice that in this example the
S5Region
also has a
sharing policy that imports
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 (parent
child). This is depicted
in
Figure
134
.4
Figure
134
.4 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
SI
(Subsystems implementation, may be multiple bundles), and
the system bundle (identifier 0).
Figure
134
.5 Subsystem resources
In
Figure
134
.5
Bundles
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
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
and
and Scoped Subsystem
S2
with constituent bundles
and
Figure
134
.6 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
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
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.
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:
The Preferred-Provider header is parsed into a list of
elements where each element specifies a single
osgi.identity
requirement, see
Preferred-Provider Header
For each
osgi.identity
requirement a
Requirement
object is created and used to search
Repositories for preferred provider resources.
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.
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.
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.
The Content Repository.
The Preferred Provider Repository.
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.
The Local Repository. This allows a Subsystem Archive to
optionally include dependencies.
The registered Repository services.
Any matching capabilities found in the steps after step
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
) 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
and
and installable dependencies
and
. This is depicted in
Figure
134
.10
Figure
134
.10 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
and
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
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
and
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
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
and
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
In this example the
and
provide
capabilities that are required by
and
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
or
to
access capabilities provided by
or
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
In this example constituent
of the Root Region
provides the capability
(called
Root
). Also constituent
of
S2Region
provides the capability
S2
. The export sharing policy of
S2
policy exports the capability
S2
to its parent Region, the
RootRegion
. The
S1Region
contains a
constituent A that has a requirement on
S1
. The two capabilities,
Root
and
S2
, are
available to satisfy the requirement
S1
. The
S1Region
's
import sharing policy imports capability
and has a
preferred provider of
S2
. This means that the capability
S2
must be
used to satisfy the requirement
S1
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.id>
Version 1.0.0
Has a location string of
location>/
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:
Determine the bundle performing the install. This is the
bundle whose Bundle Context is performing the install
operation.
Determine the target Region. This is the Region to which the
bundle performing the install operation belongs.
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.
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.
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:
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
Determine the target Region. This is the Region to which the
target Subsystem belongs.
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.
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
SI
(Subsystems implementation) and
the system bundle (id = 0) installed.
Figure
134
.15 Explicit Resource Example
If bundle
uses its own Bundle Context to explicitly
install bundle
then bundle
becomes a
constituent of the Root Subsystem. If bundle
uses
Subsystem
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
and
. Also, if bundle
uses Subsystem
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
and
Figure
134
.16
illustrates this.
Figure
134
.16 Subsystems and Resources
Then if bundle
uses its own Bundle Context to
install bundle
(using a different location string from
constituent bundle
S2
) then the bundle becomes a
constituent of
S1
. If bundle
uses Subsystem
service
S2
to install Unscoped Subsystem
U1
(with constituents
and
) and installs
Unscoped Subsystem
U2
(with constituents
and
) 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
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:
and
. 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]
has the lowest start-order, therefore
it is the first in the list.
and
have the
same
start-order
and therefore can be started in any order
in relation to each other. Finally
is last in the list
because it has the highest start-order.
When the Subsystem
S1
is started the content resource
must be started first, followed by the starting of
and
in any order, finally resource
is started last. When the Subsystem
S1
is
stopped the content resource A must be stopped first, followed by the
stopping of
and
in any order, finally
resource
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.
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
The Root Subsystem has no parent Subsystem. More specifically
the Root Subsystem is the only source vertex in the Subsystem
graph.
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.
The Subsystem content is the set of bundles installed in the
framework that do not belong to any other Subsystem.
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
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.
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
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:
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.
Determine the Subsystems for which the Subsystem being
installed will become a constituent of by following the steps in
Explicit and Implicit Resources
Determine the Subsystem identifier. Subsystem identifiers are
unique and assigned by the Subsystems implementation.
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.
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.
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.
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.
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.
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.
If the Subsystem is scoped, enable the import sharing policy
for the Region. See
Sharing Capabilities
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:
When a Subsystem fails to install it enters the
INSTALL_FAILED
state.
Immediately transition the Subsystem to the
UNINSTALLING
state.
All content and dependencies which may have been installed by
the Subsystem installing process must be uninstalled.
Transition the Subsystem to the
UNINSTALLED
state.
Unregister the Subsystem service.
If the Subsystem is scoped then, uninstall the Region context
bundle.
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:
If the
subsystem.state
is
INSTALL_FAILED
UNINSTALLED
, or
UNINSTALLING
, then an Illegal State Exception is
thrown.
Set the Subsystems
autostart setting
to
started
If the
subsystem.state
is
ACTIVE
then the start method returns
immediately.
If the Subsystem is not
ready
to be
started then the start method returns immediately.
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.
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.
Set the
subsystem.state
to
STARTING
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.
Set the
subsystem.state
to
ACTIVE
and return.
All start failures use the following steps:
If the subsystem state is
STARTING
then change the state to
STOPPING
Stop all resources that were started as part of this
operation.
Change the state to
INSTALLED
or
RESOLVED
depending on if the Subsystem was
resolved.
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:
If the
subsystem.state
is
UNINSTALLED
INSTALL_FAILED
, or
UNINSTALLING
, then an Illegal State Exception is
thrown.
Set the Subsystems
autostart setting
to
stopped
If the
subsystem.state
is
RESOLVED
or
INSTALLED
then the
stop()
method returns immediately.
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.
Set the
subsystem.state
to
STOPPING
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.
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:
If the
subsystem.state
is
UNINSTALLED
then this method returns immediately.
If the
subsystem.state
is
STARTING
STOPPING
or
ACTIVE
then the Subsystem is stopped according to
Stopping
. Otherwise continue to the next
step.
If the
subsystem.state
is
INSTALLING
and the installing process is interruptible,
fail the install process; otherwise, wait until the installation is
complete.
If the
subsystem.state
is in the
INSTALL_FAILED
state then skip to step
Set the
subsystem.state
to
INSTALLED
Set the
subsystem.state
to
UNINSTALLING
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.
Set the
subsystem.state
to
UNINSTALLED
Unregister the Subsystem service.
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="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="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.
Bundle - A bundle that is not a
fragment.
Fragment - A fragment bundle.
Application
Subsystem
- An application subsystem.
Composite Subsystem
A composite subsystem.
Feature Subsystem
- A
feature 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.
The ID is
The symbolic name is
org.osgi.service.subsystem.root
The version matches this specification's version.
It has no parents.
All existing bundles, including the system and subsystem implementation
bundles, are constituents.
The type is
osgi.subsystem.application
with no imports.
The provision policy is
acceptDependencies
Concurrency
Thread-safe
Provider Type
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.
Returns
The bundle context of the region within which this subsystem
resides or
null
if this subsystem's state is in
INSTALL_FAILED
UNINSTALLED
Throws
SecurityException
– If the caller does not have the appropriate
SubsystemPermission
[this,CONTEXT], and the runtime
supports permissions.
134.21.2.2
public Collection getChildren()
Returns the child subsystems of this subsystem.
Returns
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.
Throws
IllegalStateException
– If this subsystem's state is in
INSTALL_FAILED
UNINSTALLED
134.21.2.3
public Collection getConstituents()
Returns the constituent resources of this subsystem.
Returns
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.
Throws
IllegalStateException
– If this subsystem's state is in
INSTALL_FAILED
UNINSTALLED
134.21.2.4
public Map 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.
Returns
The headers for this subsystem's deployment manifest. The
returned map is unmodifiable.
Throws
SecurityException
– If the caller does not have the appropriate
SubsystemPermission
[this,METADATA], and the runtime
supports permissions.
Since
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.
Returns
The location identifier of this subsystem.
Throws
SecurityException
– If the caller does not have the appropriate
SubsystemPermission
[this,METADATA], and the runtime
supports permissions.
134.21.2.6
public Collection getParents()
Returns the parent subsystems of this subsystem.
Returns
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.
Throws
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.
Returns
The current state of this subsystem.
134.21.2.8
public Map getSubsystemHeaders(Locale 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.
Returns
The headers for this subsystem's subsystem manifest. The returned
map is unmodifiable.
Throws
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.
Returns
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.
Returns
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.
Returns
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.
Returns
The version of this subsystem.
134.21.2.13
public Subsystem install(String location)
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.
Returns
The installed subsystem.
Throws
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.
See Also
install(String, InputStream)
134.21.2.14
public Subsystem install(String location, InputStream content)
location
The location identifier of the subsystem to be installed.
content
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.
If an installed subsystem with the specified location identifier
already exists, return the installed subsystem.
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.
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.
Create a new subsystem based on the specified location and content.
If the subsystem is scoped, install and start a new region context
bundle.
Change the state to
INSTALLING
and register
a new subsystem service.
Discover the subsystem's content resources. If any mandatory resource
is missing, an installation failure results.
Discover the dependencies required by the content resources. If any
mandatory dependency is missing, an installation failure results.
Using a framework
ResolverHook
, disable runtime resolution
for the resources.
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.
If the subsystem is scoped, enable the import sharing policy.
Enable runtime resolution for the resources.
Change the state of the subsystem to
INSTALLED
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.
Change the state to
INSTALL_FAILED
Change the state to
UNINSTALLING
All content and dependencies which may have been installed by the
installing process must be uninstalled.
Change the state to
UNINSTALLED
Unregister the subsystem service.
If the subsystem is a scoped subsystem then, uninstall the region
context bundle.
Throw a
SubsystemException
with the cause of the installation
failure.
Returns
The installed subsystem.
Throws
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)
location
The location identifier of the subsystem to be installed.
content
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.
deploymentManifest
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.
Returns
The installed subsystem.
Throws
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.
Since
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.
Set the subsystem
autostart setting
to
started
If this subsystem is in the
RESOLVED
state,
proceed to step 7.
Change the state to
RESOLVING
Resolve the content resources. A resolution failure results in a
start failure with a state of
INSTALLED
Change the state to
RESOLVED
If this subsystem is scoped, enable the export sharing policy.
Change the state to
STARTING
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.
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.
If the subsystem state is
STARTING
then change
the state to
STOPPING
and stop all resources that
were started as part of this operation.
Change the state to either
INSTALLED
or
RESOLVED
Throw a SubsystemException with the specified cause.
Throws
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.
Set the subsystem
autostart setting
to
stopped
Change the state to
STOPPING
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
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.
Throws
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.
Change the state to
INSTALLED
Change the state to
UNINSTALLING
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.
Change the state to
UNINSTALLED
Unregister the subsystem service.
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.
Throws
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.
Concurrency
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
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
See Also
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.
Since
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.
Since
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.
Since
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.
Since
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.
Since
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.
Since
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.
Since
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.
Since
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
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.
See Also
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
See Also
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.
Since
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)
message
The message to include in the exception.
Construct a Subsystem exception specifying a message.
134.21.5.3
public SubsystemException(Throwable cause)
cause
The cause of the exception.
Construct a Subsystem exception specifying a cause.
134.21.5.4
public SubsystemException(String message, Throwable cause)
message
The message to include in the exception.
cause
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.
Concurrency
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)
filter
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.
actions
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)
Throws
IllegalArgumentException
– If the filter has an invalid syntax.
134.21.6.6
public SubsystemPermission(Subsystem subsystem, String actions)
subsystem
A subsystem.
actions
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)
obj
The object being compared for equality with this object.
Determines the equality of two
SubsystemPermission
objects.
Returns
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
Returns
Canonical string representation of the
SubsystemPermission
actions.
134.21.6.9
public int hashCode()
Returns the hash code value for this object.
Returns
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
Returns
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
SubsystemPermission
s.
Returns
A new
PermissionCollection
object.
134.22
References
[1]
Filter Based
Permissions
OSGi Core, Chapter 2, Filter Based
Permissions
[2]
Core Service Hooks
OSGi Core, Chapter 55
Service Hook Service Specification
[3]
Resource and Wiring
OSGi
Core, Chapter 6 Resource API Specification
[4]
Zip File Format
The Zip
file format as defined by the java.util.zip package.
[5]
IANA
application/vnd.osgi.subsystem
[6]
RFC 1738 Uniform Resource
Locators
[7]
Uniform Resource Identifiers
(URI): Generic
Syntax
[8]
Equinox Region
Digraph
[9]
Open Source
initiative
[10]
Resolver Service
Specification
OSGi Core, Chapter 58 Resolver Service
Specification
Prev
Next
OSGi Specification License, Version 2.0
License Grant
No Warranties and Limitation of Liability
Covenant Not to Assert
General
Trademarks
Feedback
Introduction
1.1
Overview of Services
1.1.1
Dependency Injection Models
1.1.2
Distributed Services
1.1.3
Web Applications and HTTP Servlets
1.1.4
Asynchronous Processing and Event models
1.1.5
Management and Configuration services
1.1.6
Naming and Directory services
1.1.7
Database Access
1.1.8
Transaction Support
1.1.9
Miscellaneous Supporting Services
1.2
Application and Provisioning Support
1.3
Reader Level
1.4
Version Information
1.4.1
OSGi Core Release 7
1.4.2
Component Versions
1.4.3
Note
1.5
References
1.6
Changes
100
Remote Services
100.1
The Fallacies
100.2
Remote Service Properties
100.2.1
Registering a Service for Export
100.2.2
Getting an Imported Service
100.2.3
On Demand Import
100.3
Intents
100.3.1
Basic Remote Services: osgi.basic
100.3.2
Asynchronous Remote Services: osgi.async
100.3.3
Confidential Remote Services: osgi.confidential
100.3.4
Private Remote Services: osgi.private
100.4
General Usage
100.4.1
Call by Value
100.4.2
Data Fencing
100.4.3
Remote Services Life Cycle
100.4.4
Runtime
100.4.5
Exceptions
100.5
Configuration Types
100.5.1
Configuration Type Properties
100.5.2
Dependencies
100.6
Security
100.6.1
Limiting Exports and Imports
100.7
References
100.8
Changes
101
Log Service Specification
101.1
Introduction
101.1.1
Entities
101.2
The Logger Interface
101.3
Obtaining a Logger
101.4
Logger Configuration
101.4.1
Configuration Admin Integration
101.4.2
Effective Log Level
101.5
Log Stream Provider
101.6
Log Reader Service
101.7
Log Entry Interface
101.8
Mapping of Events
101.8.1
Bundle Events Mapping
101.8.2
Service Events Mapping
101.8.3
Framework Events Mapping
101.8.4
Log Events
101.9
Log Service
101.10
Capabilities
101.11
Security
101.12
org.osgi.service.log
101.12.1
Summary
101.12.2
public interface FormatterLogger extends Logger
101.12.3
public interface LogEntry
101.12.4
public interface Logger
101.12.5
public interface LoggerConsumer
101.12.6
public interface LoggerFactory
101.12.7
enum LogLevel
101.12.8
public interface LogListener extends EventListener
101.12.9
public interface LogReaderService
101.12.10
public interface LogService extends LoggerFactory
101.13
org.osgi.service.log.admin
101.13.1
Summary
101.13.2
public interface LoggerAdmin
101.13.3
public interface LoggerContext
101.14
org.osgi.service.log.stream
101.14.1
Summary
101.14.2
public interface LogStreamProvider
101.14.3
enum LogStreamProvider.Options
101.15
References
101.16
Changes
102
Http Service Specification
102.1
Introduction
102.1.1
Entities
102.2
Registering Servlets
102.3
Registering Resources
102.4
Mapping HTTP Requests to Servlet and Resource Registrations
102.5
The Default Http Context Object
102.6
Multipurpose Internet Mail Extension (MIME) Types
102.7
Authentication
102.8
Security
102.8.1
Accessing Resources with the Default Http Context
102.8.2
Accessing Other Types of Resources
102.8.3
Servlet and HttpContext objects
102.9
Configuration Properties
102.10
org.osgi.service.http
102.10.1
Summary
102.10.2
public interface HttpContext
102.10.3
public interface HttpService
102.10.4
public class NamespaceException extends Exception
102.11
References
104
Configuration Admin Service Specification
104.1
Introduction
104.1.1
Essentials
104.1.2
Entities
104.1.3
Synopsis
104.2
Configuration Targets
104.3
The Persistent Identity
104.3.1
PID Syntax
104.3.2
Targeted PIDs
104.3.3
Extenders and Targeted PIDs
104.4
The Configuration Object
104.4.1
Location Binding
104.4.2
Dynamic Binding
104.4.3
Configuration Properties
104.4.4
Property Propagation
104.4.5
Automatic Properties
104.4.6
Equality
104.5
Managed Service
104.5.1
Singletons
104.5.2
Networks
104.5.3
Configuring Managed Services
104.5.4
Race Conditions
104.5.5
Examples of Managed Service
104.5.6
Deletion
104.6
Managed Service Factory
104.6.1
When to Use a Managed Service Factory
104.6.2
Registration
104.6.3
Deletion
104.6.4
Managed Service Factory Example
104.6.5
Multiple Consoles Example
104.7
Configuration Admin Service
104.7.1
Creating a Managed Service Configuration Object
104.7.2
Creating a Managed Service Factory Configuration Object
104.7.3
Accessing Existing Configurations
104.7.4
Updating a Configuration
104.7.5
Using Multi-Locations
104.7.6
Regions
104.7.7
Deletion
104.7.8
Updating a Bundle's Own Configuration
104.7.9
Configuration Attributes
104.8
Configuration Events
104.8.1
Event Admin Service and Configuration Change Events
104.9
Configuration Plugin
104.9.1
Limiting The Targets
104.9.2
Example of Property Expansion
104.9.3
Configuration Data Modifications
104.9.4
Forcing a Callback
104.9.5
Calling Order
104.9.6
Manual Invocation
104.10
Meta Typing
104.11
Coordinator Support
104.12
Capabilities
104.12.1
osgi.implementation Capability
104.12.2
osgi.service Capability
104.13
Security
104.13.1
Configuration Permission
104.13.2
Permissions Summary
104.13.3
Configuration and Permission Administration
104.14
org.osgi.service.cm
104.14.1
Summary
104.14.2
Permissions
104.14.3
public interface Configuration
104.14.4
enum Configuration.ConfigurationAttribute
104.14.5
public interface ConfigurationAdmin
104.14.6
public final class ConfigurationConstants
104.14.7
public class ConfigurationEvent
104.14.8
public class ConfigurationException extends Exception
104.14.9
public interface ConfigurationListener
104.14.10
public final class ConfigurationPermission extends BasicPermission
104.14.11
public interface ConfigurationPlugin
104.14.12
public interface ManagedService
104.14.13
public interface ManagedServiceFactory
104.14.14
public class ReadOnlyConfigurationException extends RuntimeException
104.14.15
public interface SynchronousConfigurationListener extends ConfigurationListener
104.15
org.osgi.service.cm.annotations
104.15.1
Summary
104.15.2
@RequireConfigurationAdmin
104.16
Changes
105
Metatype Service Specification
105.1
Introduction
105.1.1
Essentials
105.1.2
Entities
105.1.3
Operation
105.2
Attributes Model
105.3
Object Class Definition
105.4
Attribute Definition
105.5
Meta Type Service
105.6
Meta Type Provider Service
105.7
Using the Meta Type Resources
105.7.1
XML Schema of a Meta Type Resource
105.7.2
Designate Element
105.7.3
Example Metadata File
105.7.4
Object Element
105.8
Meta Type Resource XML Schema
105.9
Meta Type Annotations
105.9.1
ObjectClassDefinition Annotation
105.9.2
AttributeDefinition Annotation
105.9.3
Designate Annotation
105.10
Limitations
105.11
Related Standards
105.12
Capabilities
105.13
Security Considerations
105.14
org.osgi.service.metatype
105.14.1
Summary
105.14.2
public interface AttributeDefinition
105.14.3
public interface MetaTypeInformation extends MetaTypeProvider
105.14.4
public interface MetaTypeProvider
105.14.5
public interface MetaTypeService
105.14.6
public interface ObjectClassDefinition
105.15
org.osgi.service.metatype.annotations
105.15.1
Summary
105.15.2
@AttributeDefinition
105.15.3
enum AttributeType
105.15.4
@Designate
105.15.5
@Icon
105.15.6
@ObjectClassDefinition
105.15.7
@Option
105.15.8
@RequireMetaTypeExtender
105.15.9
@RequireMetaTypeImplementation
105.16
References
105.17
Changes
107
User Admin Service Specification
107.1
Introduction
107.1.1
Essentials
107.1.2
Entities
107.1.3
Operation
107.2
Authentication
107.2.1
Repository
107.2.2
Basic Authentication
107.2.3
Certificates
107.3
Authorization
107.3.1
The Authorization Object
107.3.2
Authorization Example
107.4
Repository Maintenance
107.5
User Admin Events
107.5.1
Event Admin and User Admin Change Events
107.6
Security
107.6.1
User Admin Permission
107.7
Relation to JAAS
107.7.1
JDK 1.3 Dependencies
107.7.2
Existing OSGi Mechanism
107.7.3
Future Road Map
107.8
org.osgi.service.useradmin
107.8.1
Summary
107.8.2
public interface Authorization
107.8.3
public interface Group extends User
107.8.4
public interface Role
107.8.5
public interface User extends Role
107.8.6
public interface UserAdmin
107.8.7
public class UserAdminEvent
107.8.8
public interface UserAdminListener
107.8.9
public final class UserAdminPermission extends BasicPermission
107.9
References
110
Initial Provisioning Specification
110.1
Introduction
110.1.1
Essentials
110.1.2
Entities
110.2
Procedure
110.2.1
InitialProvisioning-Entries Manifest Header
110.3
Special Configurations
110.3.1
Branded OSGi framework Server
110.3.2
Non-connected OSGi framework
110.4
The Provisioning Service
110.5
Management Agent Environment
110.6
Mapping To File Scheme
110.6.1
Example With File Scheme
110.7
Mapping To HTTP(S) Scheme
110.7.1
HTTPS Certificates
110.7.2
Certificate Encoding
110.7.3
URL Encoding
110.8
Mapping To RSH Scheme
110.8.1
Shared Secret
110.8.2
Request Coding
110.8.3
Response Coding
110.8.4
RSH URL
110.8.5
Extensions to the Provisioning Service Dictionary
110.8.6
RSH Transport
110.9
Exception Handling
110.10
Security
110.10.1
Concerns
110.10.2
OSGi framework Long-Term Security
110.10.3
Permissions
110.11
org.osgi.service.provisioning
110.11.1
Summary
110.11.2
public interface ProvisioningService
110.12
References
112
Declarative Services Specification
112.1
Introduction
112.1.1
Essentials
112.1.2
Entities
112.1.3
Synopsis
112.1.4
Readers
112.2
Components
112.2.1
Declaring a Component
112.2.2
Immediate Component
112.2.3
Delayed Component
112.2.4
Factory Component
112.3
References to Services
112.3.1
Accessing Services
112.3.2
Method Injection
112.3.3
Field Injection
112.3.4
Constructor Injection
112.3.5
Reference Cardinality
112.3.6
Reference Scope
112.3.7
Reference Policy
112.3.8
Reference Policy Option
112.3.9
Reference Field Option
112.3.10
Selecting Target Services
112.3.11
Circular References
112.3.12
Logger Support
112.4
Component Description
112.4.1
Annotations
112.4.2
Service Component Header
112.4.3
XML Document
112.4.4
Component Element
112.4.5
Implementation Element
112.4.6
Property and Properties Elements
112.4.7
Service Element
112.4.8
Reference Element
112.4.9
Factory Property and Factory Properties Elements
112.5
Component Life Cycle
112.5.1
Enabled
112.5.2
Satisfied
112.5.3
Immediate Component
112.5.4
Delayed Component
112.5.5
Factory Component
112.5.6
Activation
112.5.7
Bound Services
112.5.8
Component Context
112.5.9
Activation Objects
112.5.10
Binding Services
112.5.11
Activate Method
112.5.12
Bound Service Replacement
112.5.13
Updated
112.5.14
Modification
112.5.15
Modified Method
112.5.16
Deactivation
112.5.17
Deactivate Method
112.5.18
Unbinding
112.5.19
Life Cycle Example
112.6
Component Properties
112.6.1
Service Properties
112.6.2
Reference Properties
112.7
Deployment
112.7.1
Configuration Changes
112.8
Annotations
112.8.1
Component Annotations
112.8.2
Component Property Types
112.8.3
Ordering of Generated Component Properties
112.9
Service Component Runtime
112.9.1
Relationship to OSGi Framework
112.9.2
Starting and Stopping SCR
112.9.3
Logging Messages
112.9.4
Locating Component Methods and Fields
112.9.5
Bundle Activator Interaction
112.9.6
Introspection
112.9.7
Capabilities
112.10
Security
112.10.1
Service Permissions
112.10.2
Required Admin Permission
112.10.3
Using hasPermission
112.10.4
Configuration Multi-Locations and Regions
112.11
Component Description Schema
112.12
org.osgi.service.component
112.12.1
Summary
112.12.2
public interface ComponentConstants
112.12.3
public interface ComponentContext
112.12.4
public class ComponentException extends RuntimeException
112.12.5
public interface ComponentFactory
112.12.6
public interface ComponentInstance
112.12.7
public interface ComponentServiceObjects
112.13
org.osgi.service.component.annotations
112.13.1
Summary
112.13.2
@Activate
112.13.3
enum CollectionType
112.13.4
@Component
112.13.5
@ComponentPropertyType
112.13.6
enum ConfigurationPolicy
112.13.7
@Deactivate
112.13.8
enum FieldOption
112.13.9
@Modified
112.13.10
@Reference
112.13.11
enum ReferenceCardinality
112.13.12
enum ReferencePolicy
112.13.13
enum ReferencePolicyOption
112.13.14
enum ReferenceScope
112.13.15
@RequireServiceComponentRuntime
112.13.16
enum ServiceScope
112.14
org.osgi.service.component.runtime
112.14.1
Summary
112.14.2
public interface ServiceComponentRuntime
112.15
org.osgi.service.component.runtime.dto
112.15.1
Summary
112.15.2
public class ComponentConfigurationDTO extends DTO
112.15.3
public class ComponentDescriptionDTO extends DTO
112.15.4
public class ReferenceDTO extends DTO
112.15.5
public class SatisfiedReferenceDTO extends DTO
112.15.6
public class UnsatisfiedReferenceDTO extends DTO
112.16
org.osgi.service.component.propertytypes
112.16.1
Summary
112.16.2
@ExportedService
112.16.3
@ServiceDescription
112.16.4
@ServiceRanking
112.16.5
@ServiceVendor
112.17
References
112.18
Changes
113
Event Admin Service Specification
113.1
Introduction
113.1.1
Essentials
113.1.2
Entities
113.1.3
Synopsis
113.1.4
What To Read
113.2
Event Admin Architecture
113.3
The Event
113.3.1
Topics
113.3.2
Properties
113.3.3
High Performance
113.4
Event Handler
113.4.1
Ordering
113.5
Event Publisher
113.6
Specific Events
113.6.1
General Conventions
113.6.2
OSGi Events
113.6.3
Framework Event
113.6.4
Bundle Event
113.6.5
Service Event
113.6.6
Other Event Sources
113.7
Event Admin Service
113.7.1
Synchronous Event Delivery
113.7.2
Asynchronous Event Delivery
113.7.3
Order of Event Delivery
113.8
Reliability
113.8.1
Exceptions in callbacks
113.8.2
Dealing with Stalled Handlers
113.9
Interoperability with Native Applications
113.10
Capabilities
113.10.1
osgi.implementation Capability
113.10.2
osgi.service Capability
113.11
Security
113.11.1
Topic Permission
113.11.2
Required Permissions
113.11.3
Security Context During Event Callbacks
113.12
org.osgi.service.event
113.12.1
Summary
113.12.2
public class Event
113.12.3
public interface EventAdmin
113.12.4
public interface EventConstants
113.12.5
public interface EventHandler
113.12.6
public class EventProperties implements Map
113.12.7
public final class TopicPermission extends Permission
113.13
org.osgi.service.event.annotations
113.13.1
Summary
113.13.2
@RequireEventAdmin
113.14
org.osgi.service.event.propertytypes
113.14.1
Summary
113.14.2
@EventDelivery
113.14.3
@EventFilter
113.14.4
@EventTopics
113.15
Changes
122
Remote Service Admin Service Specification
122.1
Introduction
122.1.1
Essentials
122.1.2
Entities
122.1.3
Synopsis
122.2
Actors
122.3
Topology Managers
122.3.1
Multiple Topology Managers
122.3.2
Example Use Cases
122.4
Endpoint Description
122.4.1
Validity
122.4.2
Mutability
122.4.3
Endpoint Id
122.4.4
Framework UUID
122.4.5
Resource Containment
122.5
Remote Service Admin
122.5.1
Exporting
122.5.2
Importing
122.5.3
Updates
122.5.4
Reflection
122.5.5
Registration Life Cycle
122.5.6
Invalid Registrations
122.5.7
Proxying
122.6
Discovery
122.6.1
Scope and Filters
122.6.2
Endpoint Event Listener Interface
122.6.3
Endpoint Listener Interface
122.6.4
Endpoint Event Listener and Endpoint Listener
Implementations
122.6.5
Endpoint Description Providers
122.6.6
On Demand
122.7
Events
122.7.1
Event Admin Mapping
122.8
Endpoint Description Extender Format
122.8.1
XML Schema
122.9
Capability Namespaces
122.9.1
Local Discovery Extender
122.9.2
Discovery Provider Capability
122.9.3
Distribution Provider Capability
122.9.4
Topology Manager Capability
122.9.5
Service Capability
122.10
Advice to implementations
122.10.1
Notifying listeners
122.10.2
Receiving Endpoint lifecycle notifications
122.11
Security
122.11.1
Import and Export Registrations
122.11.2
Endpoint Permission
122.12
org.osgi.service.remoteserviceadmin
122.12.1
Summary
122.12.2
public class EndpointDescription
122.12.3
public class EndpointEvent
122.12.4
public interface EndpointEventListener
122.12.5
public interface EndpointListener
122.12.6
public final class EndpointPermission extends Permission
122.12.7
public interface ExportReference
122.12.8
public interface ExportRegistration
122.12.9
public interface ImportReference
122.12.10
public interface ImportRegistration
122.12.11
public class RemoteConstants
122.12.12
public interface RemoteServiceAdmin
122.12.13
public class RemoteServiceAdminEvent
122.12.14
public interface RemoteServiceAdminListener
122.13
org.osgi.service.remoteserviceadmin.namespace
122.13.1
Summary
122.13.2
public final class DiscoveryNamespace extends Namespace
122.13.3
public final class DistributionNamespace extends Namespace
122.13.4
public final class TopologyNamespace extends Namespace
122.14
References
123
JTA Transaction Services Specification
123.1
Introduction
123.1.1
Essentials
123.1.2
Entities
123.1.3
Dependencies
123.1.4
Synopsis
123.2
JTA Overview
123.2.1
Global and Local Transactions
123.2.2
Durable Resource
123.2.3
Volatile Resource
123.2.4
Threading
123.3
Application
123.3.1
No Enlistment
123.3.2
Application Bundle Enlistment
123.3.3
Container Managed Enlistment
123.4
Resource Managers
123.5
The JTA Provider
123.5.1
User Transaction
123.5.2
Transaction Manager
123.5.3
Transaction Synchronization Service
123.6
Life Cycle
123.6.1
JTA Provider
123.6.2
Application Bundles
123.6.3
Error Handling
123.7
Security
123.8
References
124
Management Model Specification for JMX™ Technology
124.1
Introduction
124.1.1
Essentials
124.1.2
Entities
124.1.3
Synopsis
124.2
JMX Overview
124.2.1
Connectors and Adapters
124.2.2
Object Name
124.2.3
MBeans
124.2.4
Open Types
124.3
OSGi JMX Management
124.3.1
Naming
124.3.2
Object Naming
124.3.3
The MBean Server
124.3.4
Registrations
124.4
MBeans
124.5
Item
124.6
Security
124.7
org.osgi.jmx
124.7.1
Summary
124.7.2
public class Item
124.7.3
public class JmxConstants
124.8
org.osgi.jmx.framework
124.8.1
Summary
124.8.2
public interface BundleStateMBean
124.8.3
public interface FrameworkMBean
124.8.4
public interface PackageStateMBean
124.8.5
public interface ServiceStateMBean
124.9
org.osgi.jmx.service.cm
124.9.1
Summary
124.9.2
public interface ConfigurationAdminMBean
124.10
org.osgi.jmx.service.permissionadmin
124.10.1
Summary
124.10.2
public interface PermissionAdminMBean
124.11
org.osgi.jmx.service.provisioning
124.11.1
Summary
124.11.2
public interface ProvisioningServiceMBean
124.12
org.osgi.jmx.service.useradmin
124.12.1
Summary
124.12.2
public interface UserAdminMBean
124.13
org.osgi.jmx.framework.wiring
124.13.1
Summary
124.13.2
public interface BundleWiringStateMBean
124.14
References
125
Data Service Specification for JDBC™ Technology
125.1
Introduction
125.1.1
Essentials
125.1.2
Entities
125.1.3
Dependencies
125.1.4
Synopsis
125.2
Database Driver
125.2.1
Life Cycle
125.2.2
Package Dependencies
125.3
Applications
125.3.1
Selecting the Data Source Factory Service
125.3.2
Using Database Drivers
125.3.3
Using JDBC in OSGi and Containers
125.4
Security
125.5
org.osgi.service.jdbc
125.5.1
Summary
125.5.2
public interface DataSourceFactory
125.6
References
126
JNDI Services Specification
126.1
Introduction
126.1.1
Essentials
126.1.2
Entities
126.1.3
Dependencies
126.1.4
Synopsis
126.2
JNDI Overview
126.2.1
Context and Dir Context
126.2.2
Initial Context
126.2.3
URL Context Factory
126.2.4
Object and Reference Conversion
126.2.5
Environment
126.2.6
Naming Manager Singletons
126.2.7
Built-In JNDI Providers
126.3
JNDI Context Manager Service
126.3.1
Environment and Bundles
126.3.2
Context Creation
126.3.3
Rebinding
126.3.4
Life Cycle and Dynamism
126.4
JNDI Provider Admin service
126.5
JNDI Providers
126.5.1
Initial Context Factory Builder Provider
126.5.2
Initial Context Factory Provider
126.5.3
Object Factory Builder Provider
126.5.4
Object Factory Provider
126.5.5
URL Context Provider
126.5.6
JRE Context Providers
126.6
OSGi URL Scheme
126.6.1
Service Proxies
126.6.2
Services and State
126.7
Traditional Client Model
126.7.1
New Initial Context
126.7.2
Static Conversion
126.7.3
Caller's Bundle Context
126.7.4
Life Cycle Mismatch
126.8
Security
126.8.1
JNDI Implementation
126.8.2
JNDI Clients
126.8.3
OSGi URL namespace
126.9
org.osgi.service.jndi
126.9.1
Summary
126.9.2
public class JNDIConstants
126.9.3
public interface JNDIContextManager
126.9.4
public interface JNDIProviderAdmin
126.10
References
127
JPA Service Specification
127.1
Introduction
127.1.1
Essentials
127.1.2
Entities
127.1.3
Dependencies
127.1.4
Synopsis
127.2
JPA Overview
127.2.1
Persistence
127.2.2
JPA Provider
127.2.3
Managed and Unmanaged
127.2.4
JDBC Access in JPA
127.3
Bundles with Persistence
127.3.1
Services
127.3.2
Persistence Bundle
127.3.3
Client Bundles
127.3.4
Custom Configured Entity Manager
127.4
Extending a Persistence Bundle
127.4.1
Class Space Consistency
127.4.2
Meta Persistence Header
127.4.3
Processing
127.4.4
Ready Phase
127.4.5
Service Registrations
127.4.6
Registering the Entity Manager Factory Builder Service
127.4.7
Registering the Entity Manager Factory
127.4.8
Stopping
127.4.9
Entity Manager Factory Life Cycle
127.5
JPA Provider
127.5.1
Managed Model
127.5.2
Database Access
127.5.3
Data Source Factory Service Matching
127.5.4
Rebinding
127.5.5
Enhancing Entity Classes
127.5.6
Class Loading
127.5.7
Validation
127.6
Static Access
127.6.1
Access
127.7
Capabilities
127.7.1
The Extender Capability
127.7.2
The JPA Contract Capability
127.7.3
Service capabilities
127.8
Security
127.8.1
Service Permissions
127.8.2
Required Admin Permission
127.9
org.osgi.service.jpa
127.9.1
Summary
127.9.2
public interface EntityManagerFactoryBuilder
127.10
org.osgi.service.jpa.annotations
127.10.1
Summary
127.10.2
@RequireJPAExtender
127.11
References
127.12
Changes
128
Web Applications Specification
128.1
Introduction
128.1.1
Essentials
128.1.2
Entities
128.1.3
Dependencies
128.1.4
Synopsis
128.2
Web Container
128.3
Web Application Bundle
128.3.1
WAB Definition
128.3.2
Starting the Web Application Bundle
128.3.3
Failure
128.3.4
Publishing the Servlet Context
128.3.5
Static Content
128.3.6
Dynamic Content
128.3.7
Content Serving Example
128.3.8
Stopping the Web Application Bundle
128.3.9
Uninstalling the Web Application Bundle
128.3.10
Stopping of the Web Extender
128.4
Web URL Handler
128.4.1
URL Scheme
128.4.2
URL Parsing
128.4.3
URL Parameters
128.4.4
WAB Modification
128.4.5
WAR Manifest Processing
128.4.6
Signed WAR files
128.5
Events
128.6
Interacting with the OSGi Environment
128.6.1
Bundle Context Access
128.6.2
Other Component Models
128.6.3
Resource Lookup
128.6.4
Resource Injection and Annotations
128.6.5
Java Server Pages Support
128.6.6
Compilation
128.7
Security
128.8
References
130
Coordinator Service Specification
130.1
Introduction
130.1.1
Essentials
130.1.2
Entities
130.2
Usage
130.2.1
Synopsis
130.2.2
Explicit Coordination
130.2.3
Multi Threading
130.2.4
Implicit Coordinations
130.2.5
Partial Ending
130.2.6
Locking
130.2.7
Failing
130.2.8
Time-out
130.2.9
Joining
130.2.10
Variables
130.2.11
Optimizing Example
130.2.12
Security Example
130.3
Coordinator Service
130.3.1
Coordination Creation
130.3.2
Adding Participants
130.3.3
Active
130.3.4
Explicit and Implicit Models
130.3.5
Termination
130.3.6
Ending
130.3.7
Failing, TIMEOUT, ORPHANED, and RELEASED
130.3.8
Nesting Implicit Coordinations
130.3.9
Time-outs
130.3.10
Released
130.3.11
Coordinator Convenience Methods
130.3.12
Administrative Access
130.3.13
Summary
130.4
Security
130.5
org.osgi.service.coordinator
130.5.1
Summary
130.5.2
public interface Coordination
130.5.3
public class CoordinationException extends RuntimeException
130.5.4
public final class CoordinationPermission extends BasicPermission
130.5.5
public interface Coordinator
130.5.6
public interface Participant
132
Repository Service Specification
132.1
Introduction
132.1.1
Essentials
132.1.2
Entities
132.1.3
Synopsis
132.2
Using a Repository
132.2.1
Combining Requirements
132.3
Repository
132.3.1
Repository Content
132.4
osgi.content Namespace
132.5
XML Repository Format
132.5.1
Repository Element
132.5.2
Referral Element
132.5.3
Resource Element
132.5.4
Capability Element
132.5.5
Requirement Element
132.5.6
Attribute Element
132.5.7
Directive Element
132.5.8
Sample XML File
132.6
XML Repository Schema
132.7
Capabilities
132.7.1
osgi.implementation Capability
132.7.2
osgi.service Capability
132.8
Security
132.8.1
External Access
132.8.2
Permissions
132.9
org.osgi.service.repository
132.9.1
Summary
132.9.2
public interface AndExpression extends RequirementExpression
132.9.3
public final class ContentNamespace extends Namespace
132.9.4
public interface ExpressionCombiner
132.9.5
public interface IdentityExpression extends RequirementExpression
132.9.6
public interface NotExpression extends RequirementExpression
132.9.7
public interface OrExpression extends RequirementExpression
132.9.8
public interface Repository
132.9.9
public interface RepositoryContent
132.9.10
public interface RequirementBuilder
132.9.11
public interface RequirementExpression
132.10
References
132.11
Changes
133
Service Loader Mediator Specification
133.1
Introduction
133.1.1
Essentials
133.1.2
Entities
133.1.3
Synopsis
133.2
Java Service Loader API
133.3
Consumers
133.3.1
Processing
133.3.2
Opting In
133.3.3
Restricting Visibility
133.3.4
Life Cycle Impedance Mismatch
133.3.5
Consumer Example
133.4
Service Provider Bundles
133.4.1
Advertising
133.4.2
Publishing the Service Providers
133.4.3
OSGi Services
133.4.4
Service Provider Example
133.5
Service Loader Mediator
133.5.1
Registering Services
133.5.2
OSGi Service Factory
133.5.3
Service Loader and Modularity
133.5.4
Processing Consumers
133.5.5
Visibility
133.5.6
Life Cycle
133.6
osgi.serviceloader Namespace
133.7
Use of the osgi.extender Namespace
133.8
Security
133.8.1
Mediator
133.8.2
Consumers
133.8.3
Service Providers
133.9
org.osgi.service.serviceloader
133.9.1
Summary
133.9.2
public final class ServiceLoaderNamespace extends Namespace
133.10
References
134
Subsystem Service Specification
134.1
Introduction
134.1.1
Essentials
134.1.2
Entities
134.1.3
Synopsis
134.2
Subsystems
134.2.1
Subsystem Manifest Headers
134.2.2
Subsystem Identifiers and Type
134.2.3
Subsystem-SymbolicName Header
134.2.4
Subsystem-Version Header
134.2.5
Subsystem-Type Header
134.2.6
Deriving the Subsystem Identity
134.2.7
Subsystem Identity Capability
134.2.8
Subsystem-Localization Header
134.3
Subsystem Region
134.4
Subsystem Relationships
134.4.1
Prevent Cycles and Recursion
134.5
Determining Content
134.5.1
Subsystem-Content Header
134.5.2
Subsystem-Content Requirements
134.5.3
Preferred-Provider Header
134.5.4
Resource Repositories
134.5.5
Discovering Content Resources
134.6
Determining Dependencies
134.7
Accepting Dependencies
134.8
Sharing Capabilities
134.8.1
Preferred Provider
134.8.2
System Capabilities
134.9
Region Context Bundle
134.10
Explicit and Implicit Resources
134.10.1
Explicit Resources
134.10.2
Explicit Resource Example
134.11
Resource References
134.11.1
Reference Count
134.12
Starting and Stopping Resources
134.12.1
Start Order
134.12.2
Active Use Count
134.13
Subsystem Service
134.13.1
Root Subsystem
134.13.2
Subsystem Service Properties
134.13.3
Subsystem States
134.13.4
Subsystem Service Registrations
134.13.5
Subsystem Manifest Headers
134.14
Subsystem Life Cycle
134.14.1
Installing
134.14.2
Resolving
134.14.3
Starting
134.14.4
Stopping
134.14.5
Uninstalling
134.15
Pre-Calculated Deployment
134.15.1
Deployment Headers
134.15.2
Validating Subsystem Identity
134.15.3
Deployed-Content
134.15.4
Provision-Resource
134.15.5
Import-Package
134.15.6
Export-Package
134.15.7
Require-Bundle
134.15.8
Services
134.15.9
Subsystem-ImportService
134.15.10
Subsystem-ExportService
134.16
Subsystem Types
134.16.1
Application
134.16.2
Application Deployment
134.16.3
Composite
134.16.4
Feature
134.17
Weaving Hooks
134.18
Stopping and Uninstalling Subsystems Implementation
134.19
Capabilities
134.20
Security
134.20.1
Subsystem Permission
134.20.2
Actions
134.20.3
Required Permissions
134.21
org.osgi.service.subsystem
134.21.1
Summary
134.21.2
public interface Subsystem
134.21.3
enum Subsystem.State
134.21.4
public class SubsystemConstants
134.21.5
public class SubsystemException extends RuntimeException
134.21.6
public final class SubsystemPermission extends BasicPermission
134.22
References
135
Common Namespaces Specification
135.1
Introduction
135.1.1
Versioning
135.2
osgi.extender Namespace
135.2.1
Extenders and Framework Hooks
135.3
osgi.contract Namespace
135.3.1
Versioning
135.4
osgi.service Namespace
135.4.1
Versioning
135.5
osgi.implementation Namespace
135.6
osgi.unresolvable Namespace
135.7
org.osgi.namespace.contract
135.7.1
Summary
135.7.2
public final class ContractNamespace extends Namespace
135.8
org.osgi.namespace.extender
135.8.1
Summary
135.8.2
public final class ExtenderNamespace extends Namespace
135.9
org.osgi.namespace.service
135.9.1
Summary
135.9.2
public final class ServiceNamespace extends Namespace
135.10
org.osgi.namespace.implementation
135.10.1
Summary
135.10.2
public final class ImplementationNamespace extends Namespace
135.11
org.osgi.namespace.unresolvable
135.11.1
Summary
135.11.2
public final class UnresolvableNamespace extends Namespace
135.12
References
135.13
Changes
137
REST Management Service Specification
137.1
Introduction
137.1.1
Essentials
137.1.2
Entities
137.1.3
Synopsis
137.2
Interacting with the REST Management Service
137.2.1
Resource Identifier Overview
137.2.2
Filtering Results
137.2.3
Content Type Matching
137.3
Resources
137.3.1
Framework Startlevel Resource
137.3.2
Bundles Resource
137.3.3
Bundles Representations Resource
137.3.4
Bundle Resource
137.3.5
Bundle State Resource
137.3.6
Bundle Header Resource
137.3.7
Bundle Startlevel Resource
137.3.8
Services Resource
137.3.9
Services Representations Resource
137.3.10
Service Resource
137.4
Representations
137.4.1
Bundle Representation
137.4.2
Bundles Representations
137.4.3
Bundle State Representation
137.4.4
Bundle Header Representation
137.4.5
Framework Startlevel Representation
137.4.6
Bundle Startlevel Representation
137.4.7
Service Representation
137.4.8
Services Representations
137.4.9
Bundle Exception Representation
137.5
Clients
137.5.1
Java Client
137.5.2
JavaScript Client
137.6
Extending the REST Management Service
137.6.1
Extensions Resource
137.6.2
Extensions Representation
137.7
XML Schema
137.8
Capabilities
137.8.1
osgi.implementation Capability
137.8.2
osgi.service Capability
137.9
Security
137.10
org.osgi.service.rest
137.10.1
Summary
137.10.2
public interface RestApiExtension
137.11
org.osgi.service.rest.client
137.11.1
Summary
137.11.2
public interface RestClient
137.11.3
public interface RestClientFactory
137.12
JavaScript Client API
137.12.1
Summary
137.12.2
interface OSGiRestClient
137.12.3
callback interface OSGiRestCallback
137.13
References
138
Asynchronous Service Specification
138.1
Introduction
138.1.1
Essentials
138.1.2
Entities
138.2
Usage
138.2.1
Synopsis
138.2.2
Making Async Invocations
138.2.3
Async Invocations of Void Methods
138.2.4
Fire and Forget Calls
138.2.5
Multi Threading
138.3
Async Service
138.3.1
Using the Async Service
138.3.2
Asynchronous Failures
138.3.3
Thread Safety and Instance Sharing
138.3.4
Service Object Lifecycle Management
138.4
The Async Mediator
138.4.1
Building the Mediator Object
138.4.2
Async Mediator Behaviors
138.4.3
Thread Safety and Instance Sharing
138.5
Fire and Forget Invocations
138.6
Delegating to Asynchronous Implementations
138.6.1
Obtaining a Promise from an Async Delegate
138.6.2
Delegating Fire and Forget Calls to an Async Delegate
138.6.3
Lifecycle for Service Objects When Delegating
138.7
Capabilities
138.8
Security
138.9
org.osgi.service.async
138.9.1
Summary
138.9.2
public interface Async
138.10
org.osgi.service.async.delegate
138.10.1
Summary
138.10.2
public interface AsyncDelegate
140
Http Whiteboard Specification
140.1
Introduction
140.1.1
Entities
140.2
The Servlet Context
140.2.1
String getMimeType(String)
140.2.2
String getRealPath(String)
140.2.3
URL getResource(String)
140.2.4
Set getResourcePaths(String)
140.2.5
Security Handling
140.2.6
Behavior of the Servlet Context
140.2.7
Relation to the Servlet Container
140.3
Common Whiteboard Properties
140.4
Registering Servlets
140.4.1
Multipart File Upload
140.4.2
Error Pages
140.4.3
Asynchronous Request Handling
140.4.4
Annotations
140.5
Registering Servlet Filters
140.5.1
Servlet Pre-Processors
140.6
Registering Resources
140.6.1
Overlapping Resource and Servlet Registrations
140.7
Registering Listeners
140.8
Life Cycle
140.8.1
Whiteboard Service Dynamics and Active Requests
140.9
The Http Service Runtime Service
140.10
Integration with Http Service Contexts
140.11
Configuration Properties
140.12
Capabilities
140.12.1
osgi.implementation Capability
140.12.2
osgi.contract Capability
140.12.3
osgi.service Capability
140.13
Security
140.13.1
Service Permissions
140.13.2
Introspection
140.13.3
Accessing Resources with the Default Servlet Context Helper
Implementation
140.13.4
Accessing Other Types of Resources
140.13.5
Calling Http Whiteboard Services
140.13.6
Multipart Upload
140.14
org.osgi.service.http.context
140.14.1
Summary
140.14.2
public abstract class ServletContextHelper
140.15
org.osgi.service.http.runtime
140.15.1
Summary
140.15.2
public interface HttpServiceRuntime
140.15.3
public final class HttpServiceRuntimeConstants
140.16
org.osgi.service.http.runtime.dto
140.16.1
Summary
140.16.2
public abstract class BaseServletDTO extends DTO
140.16.3
public final class DTOConstants
140.16.4
public class ErrorPageDTO extends BaseServletDTO
140.16.5
public class FailedErrorPageDTO extends ErrorPageDTO
140.16.6
public class FailedFilterDTO extends FilterDTO
140.16.7
public class FailedListenerDTO extends ListenerDTO
140.16.8
public class FailedPreprocessorDTO extends PreprocessorDTO
140.16.9
public class FailedResourceDTO extends ResourceDTO
140.16.10
public class FailedServletContextDTO extends ServletContextDTO
140.16.11
public class FailedServletDTO extends ServletDTO
140.16.12
public class FilterDTO extends DTO
140.16.13
public class ListenerDTO extends DTO
140.16.14
public class PreprocessorDTO extends DTO
140.16.15
public class RequestInfoDTO extends DTO
140.16.16
public class ResourceDTO extends DTO
140.16.17
public class RuntimeDTO extends DTO
140.16.18
public class ServletContextDTO extends DTO
140.16.19
public class ServletDTO extends BaseServletDTO
140.17
org.osgi.service.http.whiteboard
140.17.1
Summary
140.17.2
public final class HttpWhiteboardConstants
140.17.3
public interface Preprocessor extends Filter
140.18
org.osgi.service.http.whiteboard.annotations
140.18.1
Summary
140.18.2
@RequireHttpWhiteboard
140.19
org.osgi.service.http.whiteboard.propertytypes
140.19.1
Summary
140.19.2
@HttpWhiteboardContext
140.19.3
@HttpWhiteboardContextSelect
140.19.4
@HttpWhiteboardFilterAsyncSupported
140.19.5
@HttpWhiteboardFilterDispatcher
140.19.6
@HttpWhiteboardFilterName
140.19.7
@HttpWhiteboardFilterPattern
140.19.8
@HttpWhiteboardFilterRegex
140.19.9
@HttpWhiteboardFilterServlet
140.19.10
@HttpWhiteboardListener
140.19.11
@HttpWhiteboardResource
140.19.12
@HttpWhiteboardServletAsyncSupported
140.19.13
@HttpWhiteboardServletErrorPage
140.19.14
@HttpWhiteboardServletMultipart
140.19.15
@HttpWhiteboardServletName
140.19.16
@HttpWhiteboardServletPattern
140.19.17
@HttpWhiteboardTarget
140.20
References
140.21
Changes
147
Transaction Control Service Specification
147.1
Introduction
147.1.1
Essentials
147.1.2
Entities
147.2
Usage
147.2.1
Synopsis
147.2.2
Running Scoped Work
147.2.3
Accessing Scoped Resources
147.2.4
Exception Management
147.2.5
Multi Threading
147.3
Transaction Control Service
147.3.1
Scope Life Cycle
147.3.2
Scopes and Exception Management
147.3.3
Transaction Scope lifecycle
147.4
The TransactionContext
147.4.1
Transaction Lifecycle callbacks
147.4.2
Scoped variables
147.4.3
Transaction Key
147.4.4
The Transaction Status
147.4.5
Local Transaction scopes
147.4.6
XA Transaction scopes
147.5
Resource Providers
147.5.1
Generic Resource Providers
147.5.2
JDBC Resource Providers
147.5.3
JPA
147.5.4
Connection Pooling
147.6
Transaction Recovery
147.6.1
Enlisting a Recoverable Resource in a Transaction
147.6.2
Providing an XAResource for Recovery
147.6.3
Identifying implementations which support recovery
147.7
Capabilities
147.8
Security
147.9
org.osgi.service.transaction.control
147.9.1
Summary
147.9.2
public interface LocalResource
147.9.3
public interface ResourceProvider
147.9.4
public class ScopedWorkException extends RuntimeException
147.9.5
public abstract class TransactionBuilder implements TransactionStarter
147.9.6
public interface TransactionContext
147.9.7
public interface TransactionControl extends TransactionStarter
147.9.8
public class TransactionException extends RuntimeException
147.9.9
public class TransactionRolledBackException extends TransactionException
147.9.10
public interface TransactionStarter
147.9.11
enum TransactionStatus
147.10
org.osgi.service.transaction.control.jdbc
147.10.1
Summary
147.10.2
public interface JDBCConnectionProvider extends ResourceProvider
147.10.3
public interface JDBCConnectionProviderFactory
147.11
org.osgi.service.transaction.control.jpa
147.11.1
Summary
147.11.2
public interface JPAEntityManagerProvider extends ResourceProvider
147.11.3
public interface JPAEntityManagerProviderFactory
147.12
org.osgi.service.transaction.control.recovery
147.12.1
Summary
147.12.2
public interface RecoverableXAResource
148
Cluster Information Specification
148.1
Introduction
148.1.1
Essentials
148.1.2
Entities
148.2
OSGi frameworks in a cluster
148.3
Node Status Service
148.4
Framework Node Status Service
148.5
Application-specific Node Status metadata
148.6
Security
148.6.1
Cluster Tag Permission
148.6.2
Required Permissions
148.6.3
Remote service visibility in a cluster
148.7
org.osgi.service.clusterinfo
148.7.1
Summary
148.7.2
public final class ClusterTagPermission extends Permission
148.7.3
public interface FrameworkManager
148.7.4
public interface FrameworkNodeStatus extends NodeStatus, FrameworkManager
148.7.5
public interface NodeStatus
148.8
org.osgi.service.clusterinfo.dto
148.8.1
Summary
148.8.2
public class FrameworkNodeStatusDTO extends NodeStatusDTO
148.8.3
public class NodeStatusDTO extends DTO
150
Configurator Specification
150.1
Introduction
150.2
Entities
150.3
Configuration Resources
150.3.1
Configuration Resource Format
150.3.2
PIDs, Factory Configurations and Targeted PIDs
150.3.3
Configuration Dictionary
150.3.4
Data Types
150.3.5
Ranking
150.3.6
Overwrite Policies
150.4
Bundle Configuration Resources
150.5
Initial Configurations
150.6
Life Cycle
150.7
Grouping and Coordinations
150.8
Security
150.8.1
Configuration Permission
150.8.2
Service Permission
150.8.3
Configuration Admin Service
150.8.4
File Permission
150.9
Capabilities
150.9.1
osgi.extender Capability
150.10
osgi.configuration Namespace
150.11
Configuration Resources in a Repository
150.12
org.osgi.service.configurator
150.12.1
Summary
150.12.2
public final class ConfiguratorConstants
150.13
org.osgi.service.configurator.annotations
150.13.1
Summary
150.13.2
@RequireConfigurator
150.14
org.osgi.service.configurator.namespace
150.14.1
Summary
150.14.2
public final class ConfigurationNamespace extends Namespace
150.15
References
151
JAX-RS Whiteboard Specification
151.1
Introduction
151.1.1
Entities
151.2
The JAX-RS Whiteboard
151.2.1
The JAX-RS Service Runtime Service
151.2.2
Inspecting the Runtime DTOs
151.2.3
Relation to the Servlet Container
151.2.4
Isolation between JAX-RS Whiteboards
151.3
Common Whiteboard Properties
151.4
Registering JAX-RS Resources
151.4.1
JAX-RS Resource mapping
151.4.2
JAX-RS Whiteboard Resource Lifecycle
151.4.3
Resource Service Properties
151.4.4
A JAX-RS Whiteboard Resource Example
151.5
Registering JAX-RS Extensions
151.5.1
Name Binding and JAX-RS Extensions
151.5.2
Extension ordering
151.5.3
Extension dependencies
151.5.4
Built in extensions
151.5.5
JAX-RS Whiteboard Extension Lifecycle
151.5.6
Extension Service Properties
151.5.7
A JAX-RS Whiteboard Extension Example
151.6
Registering JAX-RS Applications
151.6.1
Application shadowing
151.6.2
Application Extension Dependencies
151.6.3
Application Service Properties
151.6.4
Accessing the Application service properties
151.6.5
A JAX-RS Whiteboard Application Example
151.7
Advertising JAX-RS Endpoints
151.8
Whiteboard Error Handling
151.9
The JAX-RS Client API
151.9.1
Client Filters, Interceptors, Readers and Writers
151.9.2
Reactive Clients
151.9.3
Consuming Server Sent Events
151.10
Portability and Interoperability
151.10.1
Media Type support
151.11
Capabilities
151.11.1
osgi.implementation Capability
151.11.2
osgi.contract Capability
151.11.3
osgi.service Capability
151.12
Security
151.12.1
Service Permissions
151.12.2
Runtime Introspection
151.12.3
Calling JAX-RS Whiteboard Services
151.13
org.osgi.service.jaxrs.client
151.13.1
Summary
151.13.2
public interface PromiseRxInvoker extends RxInvoker
151.13.3
public interface SseEventSourceFactory
151.14
org.osgi.service.jaxrs.runtime
151.14.1
Summary
151.14.2
public interface JaxrsEndpoint
151.14.3
public interface JaxrsServiceRuntime
151.14.4
public final class JaxrsServiceRuntimeConstants
151.15
org.osgi.service.jaxrs.runtime.dto
151.15.1
Summary
151.15.2
public class ApplicationDTO extends BaseApplicationDTO
151.15.3
public abstract class BaseApplicationDTO extends BaseDTO
151.15.4
public abstract class BaseDTO extends DTO
151.15.5
public abstract class BaseExtensionDTO extends BaseDTO
151.15.6
public final class DTOConstants
151.15.7
public class ExtensionDTO extends BaseExtensionDTO
151.15.8
public class FailedApplicationDTO extends BaseApplicationDTO
151.15.9
public class FailedExtensionDTO extends BaseExtensionDTO
151.15.10
public class FailedResourceDTO extends BaseDTO
151.15.11
public class ResourceDTO extends BaseDTO
151.15.12
public class ResourceMethodInfoDTO extends DTO
151.15.13
public class RuntimeDTO extends DTO
151.16
org.osgi.service.jaxrs.whiteboard
151.16.1
Summary
151.16.2
public final class JaxrsWhiteboardConstants
151.17
org.osgi.service.jaxrs.whiteboard.annotations
151.17.1
Summary
151.17.2
@RequireJaxrsWhiteboard
151.18
org.osgi.service.jaxrs.whiteboard.propertytypes
151.18.1
Summary
151.18.2
@JaxrsApplicationBase
151.18.3
@JaxrsApplicationSelect
151.18.4
@JaxrsExtension
151.18.5
@JaxrsExtensionSelect
151.18.6
@JaxrsMediaType
151.18.7
@JaxrsName
151.18.8
@JaxrsResource
151.18.9
@JaxrsWhiteboardTarget
151.18.10
@JSONRequired
151.19
References
152
CDI Integration Specification
152.1
Introduction
152.1.1
Essentials
152.1.2
Entities
152.1.3
Synopsis
152.2
Components
152.3
Component Scope
152.3.1
Contexts
152.4
Container Component
152.4.1
Container Component Configuration
152.4.2
Container Component Life Cycle
152.5
Standard Definitions
152.5.1
Annotation Inheritance
152.5.2
Code Examples
152.6
Single Component
152.6.1
Single Component Naming
152.6.2
Single Component Configuration
152.7
Factory Component
152.7.1
Factory Component Naming
152.7.2
Factory Component Configuration
152.8
Component Properties
152.8.1
Reference Properties
152.9
Bean Property Types
152.9.1
Bean Property Type Mapping
152.9.2
Coercing Bean Property Type Values
152.9.3
Standard Bean Property Types
152.10
Providing Services
152.10.1
@Service applied to bean class
152.10.2
@Service applied to type use
152.10.3
@Service applied to Producers
152.10.4
@Service Type Restrictions
152.10.5
Service Properties
152.10.6
Service Scope
152.10.7
Container Component Services
152.10.8
Single Component Services
152.10.9
Factory Component Services
152.11
Component Property Injection Points
152.11.1
Coordinator Support
152.12
Reference Injection Points
152.12.1
Reference injection point types
152.12.2
Reference Service scope
152.12.3
Bean Service Objects
152.12.4
Reference Greediness
152.12.5
Service Type
152.12.6
Any Service Type
152.12.7
Target Filter
152.12.8
Reference Names
152.12.9
Static References
152.12.10
Static Optional References
152.12.11
Static Multi-cardinality References
152.12.12
Default Minimum Cardinality
152.12.13
Dynamic References
152.13
Interacting with Service Events
152.14
CDI Component Runtime
152.14.1
Relationship to the OSGi Framework
152.14.2
Injecting the Bundle Context
152.14.3
Starting and Stopping CCR
152.14.4
Logging Messages
152.14.5
Bundle Activator Interaction
152.14.6
Introspection
152.14.7
Logger Support
152.14.8
Disabling Components
152.14.9
Container Component and Service Cycles
152.15
Capabilities
152.16
Relationship to CDI features
152.16.1
Bean Descriptors
152.16.2
Bean Discovery
152.16.3
Portable Extensions
152.16.4
Bean Manager
152.16.5
Decorators and Interceptors
152.17
Security
152.17.1
Service Permissions
152.17.2
Required Admin Permission
152.17.3
Using hasPermission
152.17.4
Configuration Multi-Locations and Regions
152.18
org.osgi.service.cdi
152.18.1
Summary
152.18.2
public class CDIConstants
152.18.3
enum ComponentType
152.18.4
enum ConfigurationPolicy
152.18.5
enum MaximumCardinality
152.18.6
enum ReferencePolicy
152.18.7
enum ReferencePolicyOption
152.18.8
enum ServiceScope
152.19
org.osgi.service.cdi.annotations
152.19.1
Summary
152.19.2
@Bean
152.19.3
@BeanPropertyType
152.19.4
public static final class BeanPropertyType.Literal extends AnnotationLiteral implements BeanPropertyType
152.19.5
@Beans
152.19.6
@ComponentProperties
152.19.7
public static final class ComponentProperties.Literal extends AnnotationLiteral implements ComponentProperties
152.19.8
@ComponentScoped
152.19.9
public static final class ComponentScoped.Literal extends AnnotationLiteral implements ComponentScoped
152.19.10
@FactoryComponent
152.19.11
public static final class FactoryComponent.Literal extends AnnotationLiteral implements FactoryComponent
152.19.12
@MinimumCardinality
152.19.13
public static final class MinimumCardinality.Literal extends AnnotationLiteral implements MinimumCardinality
152.19.14
@PID
152.19.15
public static final class PID.Literal extends AnnotationLiteral implements PID
152.19.16
@PIDs
152.19.17
public static final class PIDs.Literal extends AnnotationLiteral implements PIDs
152.19.18
@PrototypeRequired
152.19.19
public static final class PrototypeRequired.Literal extends AnnotationLiteral implements PrototypeRequired
152.19.20
@Reference
152.19.21
public static final class Reference.Any
152.19.22
public static final class Reference.Literal extends AnnotationLiteral implements Reference
152.19.23
@Reluctant
152.19.24
public static final class Reluctant.Literal extends AnnotationLiteral implements Reluctant
152.19.25
@RequireCDIExtender
152.19.26
@RequireCDIImplementation
152.19.27
@Service
152.19.28
public static final class Service.Literal extends AnnotationLiteral implements Service
152.19.29
@ServiceInstance
152.19.30
public static final class ServiceInstance.Literal extends AnnotationLiteral implements ServiceInstance
152.19.31
@SingleComponent
152.19.32
public static final class SingleComponent.Literal extends AnnotationLiteral implements SingleComponent
152.20
org.osgi.service.cdi.propertytypes
152.20.1
Summary
152.20.2
public class BeanPropertyException extends RuntimeException
152.20.3
@ExportedService
152.20.4
@ServiceDescription
152.20.5
@ServiceRanking
152.20.6
@ServiceVendor
152.21
org.osgi.service.cdi.reference
152.21.1
Summary
152.21.2
public interface BeanServiceObjects
152.21.3
public interface BindBeanServiceObjects
152.21.4
public interface BindService
152.21.5
public interface BindServiceReference
152.22
org.osgi.service.cdi.runtime
152.22.1
Summary
152.22.2
public interface CDIComponentRuntime
152.23
org.osgi.service.cdi.runtime.dto
152.23.1
Summary
152.23.2
public class ActivationDTO extends DTO
152.23.3
public class ComponentDTO extends DTO
152.23.4
public class ComponentInstanceDTO extends DTO
152.23.5
public class ConfigurationDTO extends DTO
152.23.6
public class ContainerDTO extends DTO
152.23.7
public class ExtensionDTO extends DTO
152.23.8
public class ReferenceDTO extends DTO
152.24
org.osgi.service.cdi.runtime.dto.template
152.24.1
Summary
152.24.2
public class ActivationTemplateDTO extends DTO
152.24.3
public class ComponentTemplateDTO extends DTO
152.24.4
public class ConfigurationTemplateDTO extends DTO
152.24.5
public class ContainerTemplateDTO extends DTO
152.24.6
public class ExtensionTemplateDTO extends DTO
152.24.7
public class ReferenceTemplateDTO extends DTO
152.25
References
702
XML Parser Service Specification
702.1
Introduction
702.1.1
Essentials
702.1.2
Entities
702.1.3
Operations
702.2
JAXP
702.3
XML Parser service
702.4
Properties
702.5
Getting a Parser Factory
702.6
Adapting a JAXP Parser to OSGi
702.6.1
JAR Based Services
702.6.2
XMLParserActivator
702.6.3
Adapting an Existing JAXP Compatible Parser
702.7
Usage of JAXP
702.8
Security
702.9
org.osgi.util.xml
702.9.1
Summary
702.9.2
public class XMLParserActivator implements BundleActivator, ServiceFactory
702.10
References
705
Promises Specification
705.1
Introduction
705.1.1
Essentials
705.1.2
Entities
705.2
Promise
705.3
Deferred
705.4
Callbacks
705.4.1
Runnable
705.4.2
Consumer
705.4.3
Success and Failure
705.5
Chaining Promises
705.6
Monad
705.7
Timing
705.8
Functional Interfaces
705.9
Utility Methods
705.10
Security
705.11
org.osgi.util.promise
705.11.1
Summary
705.11.2
public class Deferred
705.11.3
public class FailedPromisesException extends RuntimeException
705.11.4
public interface Failure
705.11.5
public interface Promise
705.11.6
public class PromiseFactory
705.11.7
public class Promises
705.11.8
public interface Success
705.11.9
public class TimeoutException extends Exception
705.12
org.osgi.util.function
705.12.1
Summary
705.12.2
public interface Consumer
705.12.3
public interface Function
705.12.4
public interface Predicate
705.13
References
705.14
Changes
706
Push Stream Specification
706.1
Introduction
706.1.1
Essentials
706.1.2
Entities
706.2
Asynchronous Event Streams
706.2.1
The Push Event
706.2.2
The Push Event Source
706.2.3
The Push Event Consumer
706.2.4
Closing the Event Stream
706.3
The Push Stream
706.3.1
Simple Pipelines
706.3.2
Buffering, Back pressure and Circuit Breakers
706.3.3
Forking
706.3.4
Coalescing and Windowing
706.3.5
Merging and Splitting
706.3.6
Time Limited Streams
706.3.7
Closing Streams
706.4
The Push Stream Provider
706.4.1
Building Buffers
706.4.2
Mapping between Java 8 Streams and Push Streams
706.5
Simple Push Event Sources
706.5.1
Optimizing Event Creation
706.6
Security
706.7
org.osgi.util.pushstream
706.7.1
Summary
706.7.2
public interface BufferBuilder>>
706.7.3
public interface PushbackPolicy>>
706.7.4
enum PushbackPolicyOption
706.7.5
public abstract class PushEvent
706.7.6
enum PushEvent.EventType
706.7.7
public interface PushEventConsumer
706.7.8
public interface PushEventSource
706.7.9
public interface PushStream extends AutoCloseable
706.7.10
public interface PushStreamBuilder>> extends BufferBuilder,
T, U>
706.7.11
public final class PushStreamProvider
706.7.12
public interface QueuePolicy>>
706.7.13
enum QueuePolicyOption
706.7.14
public interface SimplePushEventSource extends PushEventSource, AutoCloseable
706.8
References
707
Converter Specification
707.1
Introduction
707.2
Entities
707.3
Standard Converter
707.4
Conversions
707.4.1
Generics
707.4.2
Scalars
707.4.3
Arrays and Collections
707.4.4
Maps, Interfaces, Java Beans, DTOs and Annotations
707.5
Repeated or Deferred Conversions
707.6
Customizing converters
707.6.1
Catch-all rules
707.7
Conversion failures
707.8
Security
707.9
org.osgi.util.converter
707.9.1
Summary
707.9.2
public class ConversionException extends RuntimeException
707.9.3
public interface Converter
707.9.4
public interface ConverterBuilder
707.9.5
public interface ConverterFunction
707.9.6
public class Converters
707.9.7
public interface Converting extends Specifying
707.9.8
public interface Functioning extends Specifying
707.9.9
public abstract class Rule implements TargetRule
707.9.10
public interface Specifying>
707.9.11
public interface TargetRule
707.9.12
public class TypeReference
707.9.13
public class TypeRule implements TargetRule
707.10
References

Same domain → Similar titles →

C U Cyber History — Public Interest Web Archive

Preserving fading web memories. Discover history that once existed.