A key aspect of the OSGi general dependency model based on requirements and capabilities is the concept of a Namespace. A Namespace defines the semantics of a Requirement-Capability pair. The generic model is defined in the [3] Resources API Specification. This section defines a number of Namespaces that are not part of the OSGi Core Release 7 specification. Unless an attribute is specifically overridden, all Namespaces inherit the attributes and directives of the default Namespace as defined [4] Framework Namespaces Specification.

Each Namespace is defined with the following items:

An Extender is a bundle that uses the life cycle events from another bundle, the extendee, to extend that bundle's functionality when that bundle is active. It can use metadata (headers, or files inside the extendee) to control its functionality. Extendees therefore have a dependency on the Extender that can be modeled with the osgi.extender Namespace. The definition for this Namespace can be found in the following table and the ExtenderNamespace class.

Specifications for extenders (Blueprint, Declarative Services, etc.) should specify the values for these attributes. Extenders that provide such a capability should list the packages that they use in their specification in the uses directive of that capability to ensure class space consistency. For example a Declarative Services implementation could declare its capability with the following manifest header:

Provide-Capability: osgi.extender; 
   osgi.extender="osgi.component";
   uses:="org.osgi.service.component";
   version:Version="1.3"

A bundle that depends on a Declarative Services implementation should require such an extender with the following manifest header:

Require-Capability: osgi.extender;
  filter:="(&(osgi.extender=osgi.component)(version>=1.3)(!(version>=2.0)))"

Extenders can extend an extendee bundle even if that bundle does not require the extender, unless the extender's specification explicitly forbids this. It is recommended that an extender should only extend a bundle if one of the following is true:

Otherwise, the extender should not extend the bundle.

Products or technologies often have a number of related APIs consisting of a large set of packages. Some IDEs have not optimized for OSGi and requires work for each imported package. In these development environments using modularized systems tends to require a significant amount of manual effort to manage the imported packages.

The osgi.contract Namespace addresses this IDE deficiency. It allows a developer to specify a single name and version for a contract that can then be expanded to a potentially large number of packages. For example, a developer can then specify a dependency on Java Enterprise Edition 6 contract that can be provided by an application server.

The osgi.contract Namespace provides such a name and binds it to a set of packages with the uses constraint. The bundle that declares this contract must then import or export each of the listed packages with the correct versioning. Such a bundle is called a contract bundle. The contract bundle must ensure that it is bound to the correct versions of the packages contained within the contract it is providing. If the contract bundle imports the packages which are specified as part of the contract then proper matching attributes must be used to make sure it is bound to the correct versions of the packages.

Additionally, the osgi.contract Namespace can be used in cases where API is defined by parties that do not use Semantic Versioning. In those cases, the version of the exported package can be unclear and so it is difficult to specify a meaningful version range for the package import. In such cases, importing the package without specifying a version range and specifying a requirement in the osgi.contract Namespace can provide a way to create portable bundles that use the API. OSGi has defined contract names for a number of such APIs. See [2] Portable Java Contract Definitions for more information.

An osgi.contract capability can then be used in the following ways:

The uses directive will make it impossible to get wired to packages that are not valid for the contract. Since the uses constrains enforce the consistency, it is in principle not necessary to version the imported packages on client bundles since only the correctly versioned packages can be used. Contracts are aggregates and therefore make clients depend on the whole and all their transitive dependencies, even if the client only uses a single package of the contract.

The recommended way of using contracts is to create a contract bundle that provides the osgi.contract capability and imports the packages with their required version range. For example:

Provide-Capability: osgi.contract;
    osgi.contract=JavaServlet;
    version:Version=2.5;
    uses:="javax.servlet,javax.servlet.http"
Export-Package:
    javax.servlet;      version="2.5",
    javax.servlet.http; version="2.5"

A contract may support multiple versions of a named contract. Such a contract must use a single capability for the contract name that specifies a list of all the versions that are supported. For example, the JavaServlet 3.1 contract capability would be specified with the following:

Provide-Capability: osgi.contract;
    osgi.contract=JavaServlet;
    version:List<Version>="2.5,3.0,3.1";
    uses:=
        "javax.servlet,
        javax.servlet.annotation,
        javax.servlet.descriptor,
        javax.servlet.http"
Export-Package:
    javax.servlet;            version="3.1",
    javax.servlet.annotation; version="3.1",
    javax.servlet.descriptor; version="3.1",
    javax.servlet.http;       version="3.1"

A client bundle that requires the Servlet 2.5 contract can then have the following manifest:

Require-Capability: osgi.contract;
    filter:="(&(osgi.contract=JavaServlet)(version=2.5))",
Import-Package:
    javax.servlet, javax.servlet.http

The client bundle will be constrained by the contract's uses constraints and automatically gets the correct packages. In this example, no semantic versioning is used for the contract because the Servlet Specifications do not use semantic versioning (version 3.0 is backward compatible with 2.X).

In this model it is even possible to use the normally not recommended DynamicImport-Package header with a wild card since also this header is constrained by the uses constraints. However, using a full wildcard can also dynamically import packages that are not part of the contract. To prevent these unwanted dynamic imports, the exporter could include an attribute on the exports. For example:

Require-Capability: osgi.contract;
    filter:="(&(osgi.contract=JavaServlet)(version=2.5))"
DynamicImport-Package: 
    *;JavaServlet=contract

However, this model requires the exporter to specify an agreed attribute. The contract bundle does not require such coordination; it also allows the package exporters to reside in different and unrelated bundles.

The definition of the osgi.contract Namespace is in the following table and in the ContractNamespace class. See [2] Portable Java Contract Definitions.

The Service Namespace is intended to be used for:

A bundle providing this capability indicates that it can register such a service with at least the given custom attributes as service properties. At resolve time this is a promise since there is no guarantee that during runtime the bundle will actually register such a service; clients must handle this with the normal runtime dependency managers like Blueprint, Declarative Services, or others.

See the following table and the ServiceNamespace class for this Namespace definition.

The Implementation Namespace is intended to be used for:

A bundle providing this capability indicates that it implements a specification or contract with the specified name and version. For example, the Asynchronous Service Specification would provide the following capability:

Provide-Capability: osgi.implementation;
    osgi.implementation="osgi.async";
    version:Version="1.0";
    uses:="org.osgi.service.async"

See the following table and the ImplementationNamespace class for this Namespace definition.

The Unresolvable Namespace is intended to be used to mark a bundle as unresolvable:

For example, a bundle that must be unresolvable at runtime can include the following requirement:

Require-Capability: osgi.unresolvable;
  filter:="(&(must.not.resolve=*)(!(must.not.resolve=*)))"

The filter expression in the example above always evaluates to false.

See the UnresolvableNamespace class for this Namespace definition.