1 Introduction

The OSGi™ Alliance was founded in March 1999. Its mission is to create open specifications for the network delivery of managed services to local networks and devices. The OSGi organization is the leading standard for next-generation Internet services to homes, cars, mobile phones, desktops, small offices, and other environments.

The OSGi Core specification delivers an open, common architecture for service providers, developers, software vendors, gateway operators and equipment vendors to develop, deploy and manage services in a coordinated fashion. It enables an entirely new category of smart devices due to its flexible and managed deployment of services. OSGi specifications target set-top boxes, service gateways, cable modems, consumer electronics, PCs, industrial computers, cars, mobile phones, and more. Devices that implement the OSGi specifications will enable service providers like telcos, cable operators, utilities, and others to deliver differentiated and valuable services over their networks.

This is the sixth release of the OSGi Core specification developed by representatives from OSGi member companies. The OSGi Core Release 8 mostly extends the existing APIs into new areas. The few modifications to existing APIs are backward compatible so that applications for previous releases should run unmodified on Release 8 Frameworks. The built-in version management mechanisms allow bundles written for the new release to adapt to the old Framework implementations, if necessary.

1.1 OSGi Framework Overview

The Framework forms the core of the OSGi Specifications. It provides a general-purpose, secure, and managed Java framework that supports the deployment of extensible and downloadable applications known as bundles.

OSGi-compliant devices can download and install OSGi bundles, and remove them when they are no longer required. The Framework manages the installation and update of bundles in an OSGi environment in a dynamic and scalable fashion. To achieve this, it manages the dependencies between bundles and services in detail.

It provides the bundle developer with the resources necessary to take advantage of Java's platform independence and dynamic code-loading capability in order to easily develop services for small-memory devices that can be deployed on a large scale.

The functionality of the Framework is divided in the following layers:

  • Security Layer

  • Module Layer

  • Life Cycle Layer

  • Service Layer

  • Actual Services

This layering is depicted in Figure 1.1.

Figure 1.1 Layering


The Security Layer is based on Java security but adds a number of constraints and fills in some of the blanks that standard Java leaves open. It defines a secure packaging format as well as the runtime interaction with the Java security layer. The Security Layer is described in Security Layer.

The Module Layer defines a modularization model for Java. It addresses some of the shortcomings of Java's deployment model. The modularization layer has strict rules for sharing Java packages between bundles or hiding packages from other bundles. The Module Layer can be used without the life cycle and Service Layer. The Life Cycle Layer provides an API to manage the bundles in the Module Layer, while the Service Layer provides a communication model for the bundles. The Module Layer is described in Module Layer.

The Life Cycle Layer provides a life cycle API to bundles. This API provides a runtime model for bundles. It defines how bundles are started and stopped as well as how bundles are installed, updated and uninstalled. Additionally, it provides a comprehensive event API to allow a management bundle to control the operations of the OSGi framework. The Life Cycle Layer requires the Module Layer but the Security Layer is optional. A more extensive description of the Life Cycle layer can be found at Life Cycle Layer.

The Service Layer provides a dynamic, concise and consistent programming model for Java bundle developers, simplifying the development and deployment of service bundles by de-coupling the service's specification (Java interface) from its implementations. This model allows bundle developers to bind to services only using their interface specifications. The selection of a specific implementation, optimized for a specific need or from a specific vendor, can thus be deferred to run-time.

The framework uses the service layer to provide an extension mechanism, called hooks. Hooks are services that are used by the framework to provide additional functionality.

A consistent programming model helps bundle developers cope with scalability issues in many different dimensions - critical because the Framework is intended to run on a variety of devices whose differing hardware characteristics may affect many aspects of a service implementation. Consistent interfaces insure that the software components can be mixed and matched and still result in stable systems.

The Framework allows bundles to select an available implementation at run-time through the Framework service registry. Bundles register new services, receive notifications about the state of services, or look up existing services to adapt to the current capabilities of the device. This aspect of the Framework makes an installed bundle extensible after deployment: new bundles can be installed for added features or existing bundles can be modified and updated without requiring the system to be restarted.

The Service Layer is described in Service Layer.

The interactions between the layers is depicted in Figure 1.2.

Figure 1.2 Interactions between layers

Interactions between layers

1.2 Reader Level

This specification is written for the following audiences:

  • Application developers

  • Framework and system service developers (system developers)

  • Architects

The OSGi Specifications assume that the reader has at least one year of practical experience in writing Java programs. Experience with embedded systems and server environments is a plus. Application developers must be aware that the OSGi environment is significantly more dynamic than traditional desktop or server environments.

System developers require a very deep understanding of Java. At least three years of Java coding experience in a system environment is recommended. A Framework implementation will use areas of Java that are not normally encountered in traditional applications. Detailed understanding is required of class loaders, garbage collection, Java security, and Java native library loading.

Architects should focus on the introduction of each subject. This introduction contains a general overview of the subject, the requirements that influenced its design, and a short description of its operation as well as the entities that are used. The introductory sections require knowledge of Java concepts like classes and interfaces, but should not require coding experience.

Most of these specifications are equally applicable to application developers and system developers.

1.3 Conventions and Terms

1.3.1 Typography

A fixed width, non-serif typeface (sample) indicates the term is a Java package, class, interface, or member name. Text written in this typeface is always related to coding.

Emphasis (sample) is used the first time an important concept is introduced. Its explanation usually follows directly after the introduction.

When an example contains a line that must be broken into multiple lines, the « character is used. Spaces must be ignored in this case. For example:

http://www.acme.com/sp/ «

is equivalent to:


1.3.2 General Syntax Definitions

In many cases in these specifications, a syntax must be described. This syntax is based on the following symbols:

*           Repetition of the previous element zero or
            more times, e.g. ( ',' element )*
+           Repetition one or more times
?           Previous element is optional
( ... )     Grouping
'...'       Literal
|           Or
[...]       Set (one of)
..          list, e.g. 1..5 is the list 1 2 3 4 5
<...>       Externally defined token
~           Not

The following terminals are pre defined and used throughout the specifications:

ws              ::= <see Character.isWhitespace>
digit           ::= [0..9]
alpha           ::= [a..zA..Z]
alphanum        ::= alpha | digit
token           ::= ( alphanum | '_' | '-' )+
number          ::= digit+
jletter         ::= <see [1] Java Language Specification: Java SE 8 Edition
                     for JavaLetter>
jletterordigit  ::= <see [1] Java Language Specification: Java SE 8 Edition
                     for JavaLetterOrDigit>

qname           ::= <see [1] Java Language Specification: Java SE 8 Edition
                     for fully qualified class names>
identifier      ::= jletter jletterordigit *
extended        ::= ( alphanum | '_' | '-' | '.' )+
quoted-string   ::= '"' ( ~["\#x0D#x0A#x00] | '\"' | '\\' )* '"'
argument        ::= extended  | quoted-string
parameter       ::= directive | attribute
directive       ::= extended ':=' argument
attribute       ::= extended '=' argument

unique-name     ::= identifier ( '.' identifier )*
symbolic-name   ::= token ( '.' token )*
package-name    ::= unique-name

path            ::= special-chars+ | quoted-string
special-chars   ::= ~["\#x0D#x0A#x00:=;,<see
                     [1] Java Language Specification: Java SE 8 Edition for whitespace>]

Whitespaces between terminals are ignored unless specifically noted. Any value that contains a space, a comma, colon, semi-colon, equal sign or any other character that is part of a terminal in the grammar must be quoted.

1.3.3 Object Oriented Terminology

Concepts like classes, interfaces, objects, and services are distinct but subtly different. For example, "LogService" could mean an instance of the class LogService, could refer to the class LogService, or could indicate the functionality of the overall Log Service. Experts usually understand the meaning from the context, but this understanding requires mental effort. To highlight these subtle differences, the following conventions are used.

When the class is intended, its name is spelled exactly as in the Java source code and displayed in a fixed-width typeface: for example, the "HttpService class", "a method in the HttpContext class" or "a javax.servlet.Servlet object". A class name is used in its fully qualified form, like javax.servlet.Servlet, when the package is not obvious from the context, nor is it in one of the well known java packages like java.lang, java.io, java.util and java.net. Otherwise, the package is omitted like in String.

In many cases, a type can be used as a scalar but also a collection of that type or an array of that type. In those cases, a simple + will be suffixed to the type. For example String+, indicates that a String, a String[], and a Collection<String> are all valid forms.

Exception and permission classes are not followed by the word "object". Readability is improved when the "object" suffix is avoided. For example, "to throw a Security Exception" and to "to have File Permission" is more readable then "to have a FilePermission object".

Permissions can further be qualified with their actions. ServicePermission[com.acme.*,GET|REGISTER] means a ServicePermission with the action GET and REGISTER for all service names starting with com.acme. A ServicePermission[Producer|Consumer, REGISTER] means the ServicePermission for the Producer or Consumer class with REGISTER action.

When discussing functionality of a class rather than the implementation details, the class name is written as normal text. This convention is often used when discussing services. For example, "the User Admin service" is more readable.

Some services have the word "Service" embedded in their class name. In those cases, the word "service" is only used once but is written with an upper case S. For example, "the Log Service performs".

Service objects are registered with the OSGi Framework. Registration consists of the service object, a set of properties, and a list of classes and interfaces implemented by this service object. The classes and interfaces are used for type safety and naming. Therefore, it is said that a service object is registered under a class/interface. For example, "This service object is registered under PermissionAdmin."

1.3.4 Diagrams

The diagrams in this document illustrate the specification and are not normative. Their purpose is to provide a high-level overview on a single page. The following paragraphs describe the symbols and conventions used in these diagrams.

Classes or interfaces are depicted as rectangles, as in Figure 1.3. Interfaces are indicated with the qualifier <<interface>> as the first line. The name of the class/interface is indicated in bold when it is part of the specification. Implementation classes are sometimes shown to demonstrate a possible implementation. Implementation class names are shown in plain text. In certain cases class names are abbreviated. This is indicated by ending the abbreviation with a full stop.

Figure 1.3 Class and interface symbol

Class and interface symbol

If an interface or class is used as a service object, it will have a black triangle in the bottom right corner.

Figure 1.4 Service symbol

Service symbol

Service are crucial interaction elements and they can occur many times in diagrams describing services. Therefore, an alternative service symbol is the triangle. Triangles can be connected in different ways, representing different meanings:

  • Point - Connections to the point of a triangle indicate the registration. This makes the point of the triangle point to the object that receives the method calls from the service users.

  • Straight Side - Connections to the straight side indicate service clients. Clients call the methods of the service.

  • Angled Side - The angled side is reserved for service listeners.

Figure 1.5 Alternative Service symbol

Alternative Service symbol

Inheritance (the extends or implements keyword in Java class definitions) is indicated with an arrow. Figure 1.6 shows that the AdminPermission class implements or extends the Permission class.

Figure 1.6 Inheritance (implements or extends) symbol

Inheritance (implements or extends) symbol

Relations are depicted with a line. The cardinality of the relation is given explicitly when relevant. Figure 1.7 shows that each (1) BundleContext object is related to 0 or more BundleListener objects, and that each BundleListener object is related to a single BundleContext object. Relations usually have some description associated with them. This description should be read from left to right and top to bottom, and includes the classes on both sides. For example: "A BundleContext object delivers bundle events to zero or more BundleListener objects."

Figure 1.7 Relations symbol

Relations symbol

Associations are depicted with a dashed line. Associations are between classes, and an association can be placed on a relation. For example, "every ServiceRegistration object has an associated ServiceReference object." This association does not have to be a hard relationship, but could be derived in some way.

When a relationship is qualified by a name or an object, it is indicated by drawing a dotted line perpendicular to the relation and connecting this line to a class box or a description. Figure 1.8 shows that the relationship between a UserAdmin class and a Role class is qualified by a name. Such an association is usually implemented with a Dictionary or Map object.

Figure 1.8 Associations symbol

Associations symbol

Bundles are entities that are visible in normal application programming. For example, when a bundle is stopped, all its services will be unregistered. Therefore, the classes/interfaces that are grouped in bundles are shown on a grey rectangle as is shown in Figure 1.9.

Figure 1.9 Bundles


1.3.5 Key Words

This specification consistently uses the words can, should, and must. Their meaning is well-defined in:

  • must - An absolute requirement. Both the Framework implementation and bundles have obligations that are required to be fulfilled to conform to this specification.

  • should - Recommended. It is strongly recommended to follow the description, but reasons may exist to deviate from this recommendation.

  • may or can - Optional. Implementations must still be interoperable when these items are not implemented.

1.3.6 Numbered Lists

When a specification uses a numbered list, unless otherwise specified, the intention is that the actions described by the items in the list happen in the numerical order of the items. From a Java concurrency point-of-view, this means that the actions described in lower numbered items happens-before the actions described in higher numbered items.

1.4 Version Information

This document specifies OSGi Core Release 8. This specification is backward compatible to all prior releases.

This specification is based upon the [1] Java Language Specification: Java SE 8 Edition.

All Security, Module, Life Cycle and Service Layers are part of the Framework Specification

Components in this specification have their own specification version, independent of the document release number. The following table summarizes the packages and specification versions for the different subjects.

When a component is represented in a bundle, a version is needed in the declaration of the Import-Package or Export-Package manifest headers.

Table 1.1 Packages and versions OSGi Core

Item Package Version
Framework Specification (all layers) org.osgi.framework Version 1.10
Framework Launching org.osgi.framework.launch Version 1.2
6 Resource API Specification org.osgi.resource Version 1.0
7 Bundle Wiring API Specification org.osgi.framework.wiring Version 1.2
8 Framework Namespaces Specification org.osgi.framework.namespace Version 1.2
9 Start Level API Specification org.osgi.framework.startlevel Version 1.0
50 Conditional Permission Admin Service Specification org.osgi.service.condpermadmin Version 1.1
51 Permission Admin Service Specification org.osgi.service.permissionadmin Version 1.2
52 URL Handlers Service Specification org.osgi.service.url Version 1.0
53 Resolver Hook Service Specification org.osgi.framework.hooks.resolver Version 1.0
54 Bundle Hook Service Specification org.osgi.framework.hooks.bundle Version 1.1
55 Service Hook Service Specification org.osgi.framework.hooks.service Version 1.1
56 Weaving Hook Service Specification org.osgi.framework.hooks.weaving Version 1.1
57 Data Transfer Objects Specification






Version 1.1
58 Resolver Service Specification org.osgi.service.resolver Version 1.1
59 Condition Service Specification org.osgi.service.condition Version 1.0
60 Connect Specification org.osgi.framework.connect Version 1.0
101 Log Service Specification



Version 1.5
701 Tracker Specification org.osgi.util.tracker Version 1.5
Versioning Annotations org.osgi.annotation.versioning Version 1.1
Bundle Annotations org.osgi.annotation.bundle Version 1.1

A compliant framework implementation must implement all of the specifications in this document except as outlined below.

1.5 References

[1]Java Language Specification: Java SE 8 Editionhttps://docs.oracle.com/javase/specs/jls/se8/html/index.html

1.6 Changes