A key aspect of the OSGi dependency model based on requirements and
capabilities is the concept of a namespace. A
Namespace defines the semantics of a Requirement-Capability pair. This
generic model is defined in Resource API Specification. This
section defines a number of namespaces that are part of the OSGi Core
specification. The osgi.wiring.*
namespaces map to the module
layer, others are used as foundations for other specifications.
Namespaces that are mapped from OSGi manifest headers must never be specified as generic requirements or capabilities in the manifest. The purpose of these namespaces is only to provide the Modularity manifest headers in generic form; the framework must translate the specific manifest headers defined in the Module Layer to their generic form so that requirements and capabilities can be used in a uniform way, regardless if they originate from specialized or generic manifest headers.
Each namespace is defined with the following items:
-
Name - the name of an attribute or directive
-
Kind - Defines where the attribute or directive can be used
-
CA
- Capability Attribute -
CD
- Capability Directive -
RA
- Requirement Attribute -
RD
- Requirement Directive
-
-
M/O - Mandatory (
M
) or Optional (O
). -
Type - The data Type
-
Syntax - Any syntax rules. The syntax refers in general to the syntaxes defined in General Syntax Definitions and Common Header Syntax and later sections.
Attributes on manifest headers that define capabilities are used as
matching attributes in the requirement's filter and are available as the
attributes of a Capability
object. Attributes on manifest
headers that define requirements are translated to a conjunction of
assertions in the filter that correspond to the semantics of their header.
That is, these attributes on requiring manifest headers are not visible on
the Requirement
objects as attributes.
Unless an attribute is specifically overridden, all namespaces inherit the attributes and directives of the default namespace as defined in Table 8.1 and in Namespace.
Table 8.1 Default Namespace
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
uses |
CD |
O |
String |
|
A list of packages used in calculation class space consistency. |
effective |
|
O |
String |
'resolve' | <any name> |
A name indicating if a resolve operation applies to
this requirement. Default and only defined value is
|
resolution |
RD |
O |
String |
'mandatory' | 'optional' |
If |
filter |
RD |
O |
String |
filter |
The given filter is matched against the capability's attributes to satisfy the requirement. A filter is optional, if no filter directive is specified the requirement always matches. |
cardinality |
RD |
O |
String |
'multiple' | 'single' |
Allow the requirement to be satisfied by just one capability or provide wires to any capability that satisfies the requirement. |
mandatory |
CD |
O |
String |
extended ( ',' extended )* |
List of attribute names that the requirement's filter must assert to be equal to the values in the capability's attributes. This directive must only be used for the
|
Namespaces can have any additional attributes and directives, both defined in a namespace as well as ad-hoc. However, none of these additional directives or attributes must require different or additional matching rules.
All directives and attributes specified on the OSGi manifest headers that are translated to requirements and capabilities are visible in these capabilities and requirements, except when they are specifically noted to be ignored in the definition of a namespace.
An OSGi Framework must register capabilities for all the execution
environments the Java VM is known to be backward compatible with. For
example, if the Java VM provides Java SE 6, then it is backward compatible
with 1.2, 1.3, 1.4, 1.5, and 1.6. The osgi.ee
capability
defines the provided versions as a comma separated list. For
example:
Provide-Capability: «
osgi.ee; «
osgi.ee="OSGi/Minimum"; «
version:List<Version>="1.0,1.1,1.2", «
osgi.ee; «
osgi.ee="JavaSE"; «
version:List<Version>="1.2,1.3,1.4,1.5,1.6"
Bundles can require the osgi.ee
capability if they have
a dependency on a specific execution environment, for example:
Require-Capability: «
osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.6))"
This is useful when the bundle contains class files compiled to
target a version of the Java VM and thus cannot be loaded by prior
versions of the Java VM. If a bundle needs to require that specific
java.*
packages are available in the runtime, it should use
the Import-Package header to require those packages. See Execution Environment.
The osgi.ee
requirement is not hosted when it is part
of a Fragment. That is, a requirement from this namespace must be treated
as part of the Fragment Bundle and must not be hosted.
The osgi.ee
capability is defined in table Table 8.2 and in the ExecutionEnvironmentNamespace class.
Table 8.2 osgi.ee Namespace definition
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
osgi.ee |
CA |
M |
String |
~(ws|',')+ |
The name of the execution environment. The name can
contain any character except white space (as defined by Java) or
the comma ( |
version |
CA |
M |
|
version ( ',' version )* |
A comma separated list of versions, comparisons must
be done with version ordering because the version attribute must
be declared with the |
Provide-Capability headers in the osgi.ee
namespace
must not be used in a bundle's manifest; Require-Capability with this
namespace is allowed. An osgi.ee
requirement is the
replacement for the Bundle-RequiredExecutionEnvironment header in Bundle-RequiredExecutionEnvironment.
The names for the execution environments are not normatively defined in this specification except those defined in Table 8.3. A list of well-known (non-normative) names are maintained at [1] Specification References.
Table 8.3 osgi.ee execution environment names
Name | Description |
---|---|
JavaSE |
Should be used for all Java SE execution environments since Java 1.2. The name for the Java Runtime Environment has changed several times but for all environments the Java SE name must be used. |
JavaSE/compact1 |
Java SE Embedded compact1 profile. |
JavaSE/compact2 |
Java SE Embedded compact2 profile. |
JavaSE/compact3 |
Java SE Embedded compact3 profile. |
OSGi/Minimum |
The OSGi Minimum execution environment. |
The osgi.wiring.package
namespace reflects the
information in the manifest Import-Package, DynamicImport-Package, and
Export-Package clauses as defined Import-Package, Export-Package, and Dynamic Import Package.
The Import-Package header and DynamicImport-Package headers are
represented as a Bundle Requirement for each of their clauses. The
Export-Package header is represented as a Bundle Capability for each
clause. DynamicImport-Package clauses have a resolution
directive set to dynamic
and can only be wired after the
bundle has been resolved.
For example, the following bundles:
Bundle A:
Import-Package: p
DynamicImport-Package: q.*
Bundle B:
Export-Package: p
This example is depicted in Figure 8.1. Package
p
is wired to a Bundle Revision of bundle B
because it exports package p
. The DynamicImport-Package
clause is not wired but this can change when during run time package s
refers to a class that cannot be found.
The osgi.wiring.package
attributes are defined in Table 8.4 and in the PackageNamespace class.
Table 8.4 osgi.wiring.package Namespace definition
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
osgi.wiring.package |
CA |
M |
String |
package-name |
The name of the package. |
version |
CA |
M |
Version |
version |
A version of the exported package |
bundle-symbolic-name |
CA |
M |
String |
symbolic-name |
The bundle symbolic name of the bundle that exports the package |
bundle-version |
CA |
M |
Version |
version |
The bundle version as defined in the Bundle-Version header. |
* |
CA |
O |
String |
* |
Any attributes defined on the Export-Package clause |
resolution |
RD |
O |
String |
|
This directive is inherited from the default
namespace but this namespace adds an additional value
|
The following directives must be ignored when specified on the Import-Package, or Export-Package, or DynamicImport-Package manifest headers:
-
effective
-
cardinality
The requirements and capabilities in the
osgi.wiring.package
namespace must never be used in the
Require-Capability and Provide-Capability headers.
The osgi.wiring.bundle
namespace reflects the
information in the bundle headers for the purpose of requiring another
bundle. The Require-Bundle header is a requirement on the capability
provided by the pair of Bundle-SymbolicName/Bundle-Version headers.
Requiring this namespace through a Require-Bundle header creates a wire
from the requiring bundle to the required bundle.
A bundle must only provide this capability when the
Bundle-ManifestVersion >= 2. The osgi.wiring.bundle
attributes are defined in table Table 8.5 and in the BundleNamespace class.
Table 8.5 osgi.wiring.bundle Namespace definition
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
osgi.wiring.bundle |
CA |
M |
String |
symbolic-name |
The name of the bundle as defined in the Bundle-SymbolicName header. |
bundle-version |
CA |
M |
Version |
version |
The version of the bundle as defined in the Bundle-Version header. |
* |
CA |
O |
String |
* |
Any attributes defined on the Bundle-SymbolicName header |
singleton |
CD |
O |
String |
'true' | 'false' |
Indicates if this is a singleton bundle, see Bundle-SymbolicName. |
visibility |
RD |
O |
String |
'private' | 'reexport' |
See Require-Bundle. |
The effect of the osgi.wiring.bundle
namespace is that
the exported packages of any required bundles become available to the
requirer as defined in the Requiring Bundles. A Bundle Wire in the
osgi.wiring.bundle
namespace does not imply the availability
of osgi.wiring.package
Bundle Wires that correspond to the
required bundle's exported packages. If there is a need to know what
packages will become available then this must be deduced from the
osgi.wiring.package
capabilities of the required
bundle.
The following directives must be ignored when specified on the Require-Bundle or Bundle-SymbolicName manifest headers:
-
uses
-
effective
-
cardinality
The requirements and capabilities in the
osgi.wiring.bundle
namespace must not be used in the
Require-Capability and Provide-Capability headers.
The osgi.wiring.host
namespace reflects the information
in the bundle headers for the purpose of fragments. The Fragment-Host
header is a requirement on the capability that is provided by the pair of
Bundle-SymbolicName/Bundle-Version headers. Satisfying this requirement
allows a fragment to attach itself to a host. A bundle must only provide
this capability when the fragment-attachment
directive allows
fragments to attach and the Bundle-ManifestVersion >= 2.
The osgi.wiring.host
namespace is defined in table
Table 8.6 and in the
HostNamespace class.
Table 8.6 osgi.wiring.host Namespace definition
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
osgi.wiring.host |
CA |
M |
String |
symbolic-name |
The name of the bundle as defined in the Bundle-SymbolicName header. |
bundle-version |
CA |
M |
Version |
version |
The version of the bundle as defined in the Bundle-Version header. |
* |
CA |
O |
String |
* |
Any attributes defined on the Bundle-SymbolicName header |
fragment-attachment |
CD |
O |
String |
|
Indicates how, or if, a fragment can attach to this
host. This capability is defined on the Bundle-SymbolicName header
with its corresponding |
extension |
RD |
O |
String |
|
Indicates if the requiring fragment bundle is a framework extension. See Fragment-Host. |
The effect of the osgi.wiring.host
namespace is that
all declared capabilities and requirements of the fragment, except the
osgi.wiring.host
and osgi.ee
requirements and
the osgi.identity
capability, are merged with the host bundle
as defined in the Fragment Bundles.
The following directives must be ignored when specified on the Fragment-Host or Bundle-SymbolicName manifest headers:
-
uses
-
effective
-
cardinality
The requirements and capabilities in the
osgi.wiring.host
namespace must not be used in the
Require-Capability and Provide-Capability headers.
The osgi.identity
namespace has a capability that can
uniquely identify a resource. Its purpose is to identify a type for the
resource and then provide a name that is unique for that type. That is,
the type can be osgi.bundle
and then the name is a
Bundle-SymbolicName. For example, for a certificate the type could be x509
and the name could then its SHA-1 fingerprint. Each must have associated
rules for the names uses as the identity name. It is required that the
value of the osgi.identity
attribute, plus the value of the
type
attribute, plus the version
attribute are a
unique combination.
The definition of the osgi.identity
namespace is in
Table 8.7 and in the IdentityNamespace class.
Table 8.7 osgi.identity Namespace definition
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
osgi.identity |
CA |
M |
String |
symbolic-name |
The identity of the resource, for an OSGi bundle this is the bundle symbolic name as defined in the Bundle-SymbolicName header. |
type |
CA |
M |
String |
|
The type of the resource |
version |
CA |
M |
Version |
version |
The version of the resource. For an OSGi bundle this is as defined in the Bundle-Version header. |
singleton |
CD |
O |
String |
'true' |'false' |
If this resource is a singleton. The default value is
|
copyright |
CA |
O |
String |
A human readable copyright notice as defined for the Bundle-Copyright header. |
|
description |
CA |
O |
String |
A human readable description of the resource as defined for the Bundle-Description header. |
|
documentation |
CA |
O |
String |
<url> |
A URL to where documentation of the resource can be found as defined for the Bundle-DocURL header. |
license |
CA |
O |
String |
<url> |
A URL to the license for this resource. The URL must be the name of the license as defined in the Bundle-License header. |
tags |
CA |
O |
List<String> |
extended ( ',' extended )* |
A list of tag names used to identify an aspect of this resource that is not otherwise expressed by the capabilities of this resource. |
* |
CA |
O |
String |
* |
Any other attributes for the resource. For an OSGi bundle this is includes the attributes defined in the Bundle-SymbolicName header. |
classifier |
RD |
O |
String |
<see text> |
A name for the relation. Though any name is usable, a number of names are defined in Related Resources. |
Provide-Capability headers in the osgi.identity
Namespace must not be used in the manifest, Require-Capability with this
Namespace is allowed.
A resource can have related resources. For example, a Bundle can have Javadoc, source code, link to a source control management system, etc. It is assumed that these artifacts are also resources. It is therefore necessary that a resource can specify a relation with another resource.
A resource can specify a relation to other resource by declaring
an optional requirement to that other resource. Such relation
requirements should be placed in another effective time than resolve to
not interfere with resolving, for example the effective time
meta
. The requirements should be in to the
osgi.identity
namespace and assert:
-
osgi.identity
- The name of the resource. -
type
- The type of the resource. -
version
- The version of the resource.
The requirement must then add a directive classifier
that defines the related type so that tools like IDEs can find the
relations by iteration over all the osgi.identity
requirements that have a classifier
directive. In general,
these requirement should be optional
and have a
cardinality
of single
.
The following values are defined for the classifier
directive:
-
sources
- An archive containing the source code in the same directory layout as this resource. -
javadoc
- An archive containing the Javadoc in the same directory layout as this resource -
* - Any other names
For example, a bundle could contain the following requirement modeling a relation:
Require-Capability: «
osgi.identity; «
filter:="(&(osgi.identity=org.example.foo-source)(version=1.1))"; «
effective:=meta; «
classifier:=sources; «
resolution:=optional
The code to retrieve a related resource could look like:
Repository repository = ...;
InputStream getRelated(Resource resource, String classifier)
throws IOException {
for ( Requirement r : resource.getRequirements("osgi.identity")) {
if ( classifier.equals(r.getDirectives().get("classifier"))){
Collection<Capability> caps =
repository.findProviders(Collections.singleton(r)).get(r);
if ( caps==null || caps.isEmpty())
continue;
Capability c = caps.iterator().next();
Resource related = c.getResource();
return ((RepositoryContent)related).getContent();
}
}
return null;
}
The osgi.native
namespace is used to describe the
native environment in which the Framework is executing. An OSGi Framework
must provide a capability in the osgi.native
namespace that
represents the native environment in which the Framework is executing. For
example, the following capability is provided when running a 64-bit VM on
a Windows 7 machine with the language set to en_US:
Provide-Capability: «
osgi.native; «
osgi.native.osname:List<String>="Windows7,Windows 7,Win7,Win32"; «
osgi.native.osversion:Version="7.0"; «
osgi.native.processor:List<String>="x86-64,amd64,em64t,x86_64"; «
osgi.native.language="en"
Provide-Capability headers in the osgi.native
namespace
must not be used in a bundle's manifest. Bundles can require an
osgi.native
capability which matches the native environment
required for the bundle to function properly, for example:
Require-Capability: «
osgi.native; «
filter:=" «
(& «
(osgi.native.osname~=win32) «
(osgi.native.processor~=x86-64) «
(osgi.native.language~=en) «
)"
The osgi.native
namespace is not used to specify native
code paths packaged within a bundle. The Bundle-NativeCode
header is used to specify native code paths. The OSGi Framework converts a
Bundle-NativeCode
into an osgi.native
requirement which describes the native environment required to execute
native code packaged within a Bundle (see Loading Native Code Libraries). There is no
need for a bundle to specify both a Bundle-NativeCode
header
and an osgi.native
requirement.
Native code included in a Fragment Bundle gets loaded by the class
loaders of the Host Bundles the Fragment is attached to, therefore the
osgi.native
requirement is hosted when it is part of a
Fragment. That is, a requirement from this namespace must be treated as
part of the Host Bundles the Fragment is attached to.
The osgi.native
capability is defined in table Table 8.8 and in the NativeNamespace class.
Table 8.8 osgi.native Namespace definition
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
osgi.native.osname |
CA |
M |
|
|
A comma separated list of canonical os name aliases
to the |
osgi.native.osversion |
CA |
M |
|
version |
A |
osgi.native.processor |
CA |
M |
|
|
A comma separated list of canonical processor aliases
to the |
osgi.native.language |
CA |
M |
|
The value of the
|
In addition to the attributes defined in Table 8.8 an OSGi Framework must
populate the osgi.native
capability attributes with the
values included in the Framework launching properties (see Launching Properties). Launching property
keys that start with osgi.native.
are excluded to prevent
collisions with the defined capability attribute keys.
[1]Specification Referenceshttps://docs.osgi.org/reference/
-
Added '*' (any) attribute description to Table 8.5, Table 8.6, and Table 8.7.
-
Removed deprecated
bootclasspath
extension type in osgi.wiring.host Namespace. -
Added new
tags
attribute to Table 8.7.