Package org.osgi.framework

Description

The OSGi Java Services Framework.

Welcome to the Open Service Gateway Initiative (OSGi) Framework API. This page gives an overview of what this framework is intended for and what the overall structure is.

The purpose of the framework is to provide a context for application developers to write code for small devices that are continuously running. In these environments applications are swapped in and out, they are updated on the fly and they must communicate in a structured and dependable way with other applications. Obviously this is quite different from normal applications that are started from a command line or mouse click.

The OSGi Framework takes advantage of the Java™ programming language's ability to download code from the network. It provides a rich and structured development platform for component-based architectures.

Goals

The primary goal of the framework is to provide an environment that supports:

The OSGi framework provides a life-cycle management framework that permits application developers to partition applications into small self-installable applications. These applications are called bundles in this context. Devices running the framework can download bundles on demand and remove them when they are no longer required. A bundle, when installed can register any number of services to be shared with other bundles under control of the framework.

The OSGi Framework also supports application developers in coping with scalability issues. This support is critical, because the framework is designed to run in a variety of devices; the different hardware characteristics of the devices could affect the scale of the services that they are able to support. The framework supports the development and use of services of varying scale by decoupling a service's specification from its implementation. By splitting the implementation of a service from its specification (its Java interface):

• Developers of service implementations can implement the same interface

• Developers who use a service can code against that service's interface without regard to its implementation

For example, in a high-end device, a logging service might be able to store log messages on a hard drive, while on a disk-less device, the log entries may have to be saved remotely. The developers of the two logging service implementations implement the same interface; the developers of services that use a logging service write code against the logging service interface, without regard to which implementation their service might use. The framework can fully hide and manage the different implementations from the bundles that use the service.

Concepts

The OSGi Framework is a lightweight framework for creating extensible services using the Java programming language. To take best advantage of the framework, developers should design an application as a set of services, with each service implementing a segment of the overall functionality. These services and other extension services are then packaged in a “bundle” and downloaded on demand by the target device. For example, a text editing application designed this way could rely on a spell-checking service. The editor would instruct its framework to download a spell-checker for it to use. The framework provides mechanisms to support this paradigm that are simple to use and help with the practical aspects of writing extensible applications. The key entities of the framework are:

• Services—Objects that provide a collection of methods providing some service

• Bundles—The infrastructure for delivering code

• Bundle contexts—The execution environments of the bundles

Services

In the OSGi Framework model, an application is built around a set of cooperating services: it can extend itself at runtime by requesting the services it requires. The framework maintains a set of mappings from services to their implementations and has a powerful query mechanism that enables an installed bundle to request and use the available services. The framework manages dependencies between services and bundles. For example, when a bundle is stopped, all the services that it registered will be unregistered automatically.

A standard group like the OSGi or a private group of developers define a service as an interface and publish it. Any developer can now offer this service by implementing this standard interface. Other developers can now write code that uses this interface and obtain implementations via the framework.

The framework provides an API that the developer then uses to register the service. A service can be registered with an optional set of properties describing the service. This could for example be the name of manufacturer, version, interfaces, or author. Any bundle that now wants to use a service can specify a filter string that can be used to filter the service registry for available services. The framework can be asked to pick any service that fulfills the filter or it can return a list of services.

The framework hands out references to services. These references can be queried for properties and other meta information. A reference to a desired service can be used to obtain the service object which implements the service. The framework tracks the services that are being used by each bundle.

Bundles

To be available to the framework, a service implementation must be packaged. Service implementations are packaged into entities called bundles. A bundle is a JAR file that:

• Contains the resources implementing zero or more services. These resources may be class files for the Java programming language, as well as any other data (such as HTML help files, icons, and so on).

• States static dependencies on some other resources, such as Java packages. If any dependencies are stated, the framework takes the appropriate actions to make the required resource available.

• Manifest header describing which class should be used to start() or stop() a service.

By packing all these items together in a single JAR file, the framework can uniformly download and control a bundle.

To write a bundle, the developer must put a tag in the manifest that defines the name of a class that implements the BundleActivator interface. This interface has a start and stop method to start/stop the bundle. In the start method the bundle should wait until all its requirements are fulfilled and then start registering its services or fulfilling its task.

Bundle Manifest Headers

The framework recognizes special headers in the bundle's manifest. These headers and their values contain important information about how the bundle will operate in the framework. Additional headers can be defined by a bundle programmer as needed. Headers and their values of all manifest headers can be retrieved with Bundle.getHeaders() method.

The following headers in the bundle's manifest have special meaning to the framework.

Bundle-Activator: class-name

If present, this header names the class in the bundle which implements the BundleActivator interface. This class will used when the bundle is started and stopped. class-name must be a fully qualified Java class name.

Bundle-Name: string

If present, this header contains a human readable string which is the name of the bundle. This information is available at runtime using the bundle's Bundle.getHeaders() method. The name string is the value of the key “Bundle-Name.”

Bundle-Vendor: string

If present, this header contains a human readable string describing the vendor of the bundle. This information is available at runtime using the bundle's Bundle.getHeaders() method. The vendor string is the value of the key “Bundle-Vendor.”

Bundle-Version: string

If present, this header contains a human readable string which is the version of the bundle. This information is available at runtime using the bundle's Bundle.getHeaders() method. The version string is the value of the key “Bundle-Version.”

Bundle-Description: string

If present, this header contains a human readable string describing the purpose or function of the bundle. This information is available at runtime using the bundle's Bundle.getHeaders() method. The description string is the value of the key “Bundle-Description.”

Bundle-DocURL: string

If present, this header contains a human readable string which is a URL which contains further information about the bundle. This information is available at runtime using the bundle's Bundle.getHeaders() method. The doc URL string is the value of the key “Bundle-DocURL.”

Bundle-ContactAddress: string

If present, this header contains a human readable string which is an e-mail address which can be contacted regarding the bundle. This information is available at runtime using the bundle's Bundle.getHeaders() method. The contact address string is the value of the key “Bundle-ContactAddress.”

Bundle-UpdateLocation: string

If present, this header contains a location string that will be used to locate an updated version of the bundle when the bundle is updated using the Bundle.update() method. If this header is not present, the bundle will be updated from its original location. The location string will typically be a URL.

Bundle-ClassPath: path (, path )*

If present, this header describes the classpath within the bundle. A bundle's JAR file can contain other JAR files within it. So the Bundle-ClassPath is used to describe the search order for classes. path can be either dot ('.') which represents the bundle's JAR file or it can be the path of a JAR file contained in the bundle's JAR file. If Bundle-ClassPath is not specified, the default value is dot. If Bundle-ClassPath is specified, but dot is not an element of the path, then the bundle's main JAR file will not be searched. Only the contained JAR files referenced by the path elements will be searched.

Export-Package: package-description (, package-description )*

If present, this header describes the packages which the bundle offers for share with other bundles. package-description has the following format

package-name (; specification-version=version-number )

package-name is the fully qualifed name of a Java package. version-number is the version number of the package as specified by Java™ Product Versioning Specification (http://java.sun.com/products/jdk/1.2/docs/guide/versioning/spec/VersioningSpecification.html #PackageVersionSpecification). Since multiple bundles may offer to share the same package, the framework will select the bundle offering to share the package at the highest version. The framework guarantees that only one bundle will be selected to share a given package name.

A bundle which offers to export a package must also import that package. If the bundle's manifest does not have an Import-Package header for the same package name, the bundle will automatically import the package using the same package-description it has offered for export.

Import-Package: package-description (, package-description )*

If present, this header describes the packages which the bundle requires. These packages must be exported by another bundle. See Export-Package for the definition of package-description. If no bundles export the required packages, then this bundle is not permitted to offer packages for export.

Packages that are part of the Java platform, such as those package names starting with “java.” should not be referenced in the Import-Package header. For all other packages required by the bundle, the package names of those packages should be specified in the Import-Package header.

Export-Service: class-name (, class-name )*

If present, this header describes the services the bundle may register. This header provides advisory information that is not used by the framework. It is intended for use by server-side management tools.

Import-Service: class-name (, class-name )*

If present, this header describes the services the bundle may use. This header provides advisory information that is not used by the framework. It is intended for use by server-side management tools.

Bundle-NativeCode: nativecode-clause ( ,nativecode-clause )*

If present, this header describes the files which contain the implementation of the native methods used by classes in the bundle. nativecode-clause has the following format

nativecode-clause: nativepaths ( ; env-parameter )*
nativepaths: nativepath ( ; nativepath )*
env-parameter: ( processordef | osnamedef | osversiondef | languagedef )
processordef: processor=token
osnamedef: osname=token
osversiondef: osversion=token
languagedef: language=token

nativepath is the path of a file in the bundle's JAR file containing native methods. The env-parameters are compared against property values provided by BundleContext.getProperty().

• processor is compared against org.osgi.framework.processor.

• osname is compared against org.osgi.framework.os.name.

• osversion is compared against org.osgi.framework.os.version.

• language is compared against org.osgi.framework.language.

If a group of specified env-parameters match the property values, the framework will make the files specified by the nativepaths preceding the env-parameters available to be loaded by System.loadLibrary.

Care should be taken to select a unique name for the file containing the native methods. The framework will extract the selected files from the bundle into a location where System.loadLibrary can find them. This location will be shared by all bundles.

When the framework starts and stops

When the framework is started. The following actions occur:

When the framework is stopped. The following actions occur:

Conformance Statement

Conforming implementations must not add any new methods or fields to any of the classes or interfaces defined in the OSGi specification (though, they may add them to subclasses, or classes that implement the interfaces), nor may they add any new classes or packages to the org.osgi package tree.