8 Framework Namespaces Specification

8.1 Introduction

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

package-name

( ',' package-name )*

A list of packages used in calculation class space consistency.

effective

RD,

CD

O String 'resolve' | <any name>

A name indicating if a resolve operation applies to this requirement. Default and only defined value is resolve.

resolution RD O String 'mandatory' | 'optional'

If mandatory, then this requirement must be satisfied before the resource is resolved. The default is mandatory.

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 osgi.wiring.* namespaces and is forbidden in any other namespace.

deprecated CD O String argument Indicates the capability has been deprecated. The value is the human-readable reason to developers for the deprecation. This reason should include the version in which the capability was deprecated and any removal plan.

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.

8.2 osgi.ee 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 (',' \u002C) character.

version CA M

List

<Version>

version ( ',' version )*

A comma separated list of versions, comparisons must be done with version ordering because the version attribute must be declared with the List<Version> type.


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.


8.3 osgi.wiring.package Namespace

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.

Figure 8.1 Example osgi.wiring.package Namespace

Example osgi.wiring.package Namespace

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.

deprecated CD O String argument The deprecated directive, if any, defined on the Export-Package clause. Indicates the package has been deprecated. The value is the human-readable reason to developers for the deprecation. This reason should include the version in which the capability was deprecated and any removal plan.
resolution RD O String

'dynamic' |

'mandatory' |

'optional'

This directive is inherited from the default namespace but this namespace adds an additional value dynamic.


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.

8.4 osgi.wiring.bundle Namespace

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.

deprecated CD O String argument The deprecated directive, if any, defined on the Bundle-SymbolicName header. Indicates the bundle has been deprecated. The value is the human-readable reason to developers for the deprecation. This reason should include the version in which the capability was deprecated and any removal plan.
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.

8.5 osgi.wiring.host Namespace

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

'always' |

'resolve-time' |

'never'

Indicates how, or if, a fragment can attach to this host. This capability is defined on the Bundle-SymbolicName header with its corresponding fragment-attachment directive. See Bundle-SymbolicName.

deprecated CD O String argument The deprecated directive, if any, defined on the Bundle-SymbolicName header. Indicates the bundle has been deprecated. The value is the human-readable reason to developers for the deprecation. This reason should include the version in which the capability was deprecated and any removal plan.
extension RD O String

'framework'

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.

8.6 osgi.identity Namespace

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

osgi.bundle |

osgi.fragment |

'unknown' |

<any>

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 false. For an OSGi bundle this is the singleton directive as defined in the Bundle-SymbolicName header.

deprecated CD O String argument Indicates the resource has been deprecated. The value is the human-readable reason to developers for the deprecation. This reason should include the version in which the capability was deprecated and any removal plan. For an OSGi bundle this is the deprecated directive as defined in the Bundle-SymbolicName header.
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.

8.6.1 Related Resources

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;
    }

8.7 osgi.native Namespace

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

List

<String>

osname

( ',' osname )*

A comma separated list of canonical os name aliases to the org.osgi.framework.os.name launching property value (See Table 4.3 and [11] OSGi Reference Names). For example, an org.osgi.framework.os.name value of Windows95 will get a List<String> value of Windows95,Windows 95,Win95,Win32

osgi.native.osversion CA M

Version

version

A Version as parsed from the value of the org.osgi.framework.os.version launching property

osgi.native.processor CA M

List

<String>

processor

( ',' processor )*

A comma separated list of canonical processor aliases to the org.osgi.framework.processor launching property value (See Table 4.2 and [11] OSGi Reference Names). For example, an org.osgi.framework.processor value of x86 will get a List<String> value of x86,pentium,i386,i486,i586,i686

osgi.native.language CA M

String

 

The value of the org.osgi.framework.language launching property


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.

8.8 References

[1]Specification Referenceshttps://docs.osgi.org/reference/

8.9 Changes

  • Added new deprecated directive in Table 8.1.