8 Framework Namespaces Specification - OSGi Core 8 (original) (raw)

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

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 specificjava.* 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

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

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

The osgi.wiring.package attributes are defined in Table 8.4 and in the PackageNamespace class.

Table 8.4 osgi.wiring.package Namespace definition

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

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 theosgi.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 theosgi.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 theosgi.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 tableTable 8.6 and in theHostNamespace class.

Table 8.6 osgi.wiring.host Namespace definition

The effect of the osgi.wiring.host namespace is that all declared capabilities and requirements of the fragment, except theosgi.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 theosgi.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 thetype attribute, plus the version attribute are a unique combination.

The definition of the osgi.identity namespace is inTable 8.7 and in the IdentityNamespace class.

Table 8.7 osgi.identity Namespace definition

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 timemeta. The requirements should be in to theosgi.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 acardinality 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 anosgi.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 aBundle-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 theosgi.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

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

8.9 Changes

• Added new deprecated directive in Table 8.1.