OSGi Service Platform 4.2

OSGi Service Platform
core specification v4.2

Ilya Katsov, Grid Dynamics
2010
1

Agenda
OSGi motivation
OSGi technology overview
Basics of OSGi architecture

Bundles and Manifests
Module Layer Bundles wiring
Class loaders

Framework lifecycle
Life Cycle Layer Bundle lifecycle
Events

Registering services
Service Layer Locating services
Service events, filters, factories

Package Admin service
Standard services and tools
Start Level service

2

Part I
OSGi Technology Overview

3

OSGi :: 1
J2ME – Java in every pocket
OSGi – Java server in every pocket

Designed by Open Services Gateway Initiative Alliance for
Digital mobile phones
Vehicles
Embedded appliances
Industrial computers
Desktop PCs

The scope of the OSGi Service Platform is:
A powerful model for co-existence of different components/applications in a single JVM.

A secure environment that executes applications in a sandbox so that these applications
cannot harm the environment, nor interfere with other resident applications.

A flexible remote management architecture that allows platform operators (the
organization that manages the platform) and enterprises to manage thousands or even
millions of Service Platforms from a single management domain.

A number of standardized, optional services: Logging, Configuration, HTTP, XML, Wiring,
IO, Event Handling, Device Discovery and driver loading and many more
4

OSGi :: 2

Remote manager

bundles

Bundles and
Initial request
configuration

Management agent
OSGicontainer
container
OSGicontainer
OSGicontainer
OSGicontainer
OSGicontainer
OSGicontainer
OSGi

5

Challenges :: 1

Presentation

Business logic

Web container Persistence Libs

JRE

6

Challenges :: 2

content controller checkout signup

domain common service utils
dao messaging gateway assembler

catalina jasper-api hibernate log4j
spring xerces
el-api servlet-api
persistence-api lucene
jsp-api tomcat-coyote jdo xstream

rt jce jsse javaws charsets dnsns
sunmscapi localedata sunpkcs11 plugin

7

Challenges :: 3
content controller checkout signup content controller checkout signup

domain common service utils domain common service utils
dao messaging gateway assembler dao messaging gateway assembler

catalina jasper-api hibernate log4j catalina jasper-api hibernate log4j
spring xerces spring xerces
el-api servlet-api el-api servlet-api
persistence-api lucene persistence-api lucene
jsp-api tomcat-coyote jdo xstream jsp-api tomcat-coyote jdo xstream

rt jce jsse javaws charsets dnsns rt jce jsse javaws charsets dnsns
sunmscapi localedata sunpkcs11 plugin sunmscapi localedata sunpkcs11 plugin








8

Photo by shutterberry (http://www.flickr.com/photos/shutterberry/) of
Autumn Rhythm (Number 30), 1950 by Jackson Pollack. 9

OSGi motivation

The following drawbacks of Java are crucial for the automatically
distributable and manageable system:

Limited deployment and
management support

Poor support of logical system
partitioning

Error-prone class path concept

Unreliable dynamic updates

No versioning in runtime

10

OSGi motivation

The following drawbacks of Java are crucial for the automatically
distributable and manageable system:

Limited deployment and
management support

Poor support of logical system
partitioning

Error-prone class path concept

Unreliable dynamic updates

No versioning in runtime

11

OSGi Service Platform Architecture

Bundles

execute register, unregister, get, unget

class load

Security
start, stop

Service Layer
manage
Life Cycle Layer
install, uninstall

Module layer

OSGi framework

Execution environment
Native libraries

OS

Hardware

12

OSGi specifications

R4 Core
R1 Specification R2 Specification R3 Specification
Specification

Core
Core Core
Core
Services
Services
Permission
Admin R4 Service
Updated R2 Compendium
Log services Specification
Http Services
XML Parser

IO Connector Updated R3
services
Wiring Admin
Event Admin
…
Monitor Admin

…
13

What’s up?

“OSGi Alliance Publishes Enterprise Specification. Enterprise-
tailored specification addresses use cases in enterprise scenarios. ”
OSGi press release
23 Mar 2010

“OSGi Cloud Computing Workshop. The Eclipse Foundation and
the OSGi Alliance are organizing a Cloud Workshop at Thursday
March 25 during the OSGi DevCon/EclipseCon in Santa Clara…”
OSGi press release

“In my famous company innoQ I currently have the opportunity to
work on a real cool tool: Bundle-Bee. It claims to be able to take any
OSGi bundle and distribute the computational load to an ad-hoc grid
(e.g. all machines in an office) without special setup or
configuration.”
Joerg Plewe
28 Jan 2010

14

Implementations and usages
OSGi implementations:
Equinox OSGi Knopflerfish OSGi Apache Felix

Industry leading servers moves towards OSGi:
Glassfish v3

WebSphere V7
WebLogic

More OSGi projects:
“The Spring Dynamic Modules for OSGi(tm) Service Platforms project makes it easy to build
Spring applications that run in an OSGi framework…”
“Apache ACE is a software distribution framework that allows you to centrally manage and
distribute software components, configuration data and other artifacts to target systems…”
“Apache Sling is an innovative web framework that is intended to bring back the fun to web
development… The embedded Apache Felix…”
“The Chameleon project aims to provide a simple way to lay out specific OSGi runtimes fitting
your requirements. The strategy is to provide a layered stack…”
“The Apache CXF Distributed OSGi subproject provides the Reference Implementation of the
Distribution Provider component of the OSGi Remote Services Specification…”
15

Part II
Bundles

Service Layer

Security
Life Cycle Layer

Module Layer

OSGi framework

16

Bundles

A bundle is comprised of Java classes and other resources,
which together can provide functions to end users.

A bundle is a JAR file that:

Contains the resources necessary to provide some functionality.
These resources may be class files for the Java programming
language, as well as other data such as HTML files, help files,
icons, other JRAs, and so on.

Contains a manifest file describing the contents of the JAR file
and providing information about the bundle.

Can contain optional documentation in the OSGI-OPT directory of
the JAR file or one of its sub-directories. Management systems
may remove this information to save storage space in the OSGi
Service Platform.

17

Class loaders :: 1

Boot class
loader

System Bundle Bundle Bundle
bundle class class class class
loader loader loader loader

A class space is then all classes reachable from a given bundle’s class
loader. Thus, a class space for a given bundle can contain classes from:
The parent class loader (normally java.* packages
from the boot class path)
Imported packages
Required bundles
The bundle's class path (private packages)
Attached fragments 18

Class loaders :: 2

A class space must be consistent, such that it never contains two
classes with the same fully qualified name (to prevent Class Cast
Exceptions). However, separate class spaces in an OSGi Platform
may contain classes with the same fully qualified name.

One bundle can access to class loader of other bundle in runtime
under control of Framework.

The Framework must always delegate any package that starts with
java.* to the parent class loader. Other packages that must be
loaded from the boot class loader can therefore be specified with the
System property org.osgi.framework.bootdelegation

org.osgi.framework.bootdelegation=sun.*,com.sun.*

19

Manifest :: format notes
Header is an item of manifest. Common header syntax:

package-name | path

Import-Package: com.acme.foo;com.acme.bar;version="[1.23,1.24]";
resolution:=mandatory,com.acme.next
attribute
directive

parameter ::= directive | attribute

A Framework implementation must ignore unrecognized manifest
headers, unknown attributes and directives. The bundle
developer can define additional manifest headers as needed.

Organizations that want to use headers that do not clash with
OSGi Alliance defined names or bundle header names from other
organizations should prefix custom headers with x-, for
example x-LazyStart. Organizations external to the OSGi can
request header names in the OSGi namespace.
20

Manifest :: version
2.0.5.GD_v2-patch

major minor micro qualifier

Specification doesn’t define version compatibility policy. However it
recommends the following:
major – An incompatible update
minor – A backward compatible update
micro – A change that does not affect the interface: for example,
a bug fix.

Version interval is specified using standard mathematical notation:
Import-package: com.acme.foo;version=“[1.2, 2)”
com.acme.bar;version=7.5.1
Single version is interpreted as [version, ∞)
Exact version should be specified as [1.5.1, 1.5.1]
Default version is 0.0.0
Default range is [0.0.0, ∞)
21

Manifest :: general declarations :: 1
Bundle-ManifestVersion
The Framework version 1.3 (or later) bundle manifest version must
be’2’. Bundle manifests written to previous specifications’ manifest
syntax are taken to have a bundle manifest version of '1', although
there is no way to express this in such manifests.

Bundle-SymbolicName
The Bundle-SymbolicName manifest header is a mandatory header.
The bundle symbolic name and bundle version allow a bundle to be
uniquely identified in the Framework.

Directive singleton may be specified:
Bundle-SymbolicName: com.acme.foo;singleton:=true
This directive indicates that the bundle can only have a single
version resolved. A value of true indicates that the bundle is a
singleton bundle. The default value is false. The Framework must
resolve at most one bundle when multiple versions of a singleton
bundle with the same symbolic name are installed. Singleton bundles
do not affect the resolution of non-singleton bundles with the same
symbolic name.
22

Manifest :: general declarations :: 2

Bundle-RequiredExecutionEnvironment
A bundle can require that a Framework provides a certain execution
environment before it is resolved. This header contains comma
separated list of the following values:
CDC-1.1/Foundation-1.1 Equal to J2ME Foundation Profile

OSGi/Minimum-1.2 OSGi EE that is a minimal set that allows
the implementation of an OSGi
Framework.
J2SE-1.2 Java 2 SE 1.2.x
JavaSE-1.6 Java SE 1.6.x

Bundle-Version
23

Versions

A: Import-Package: p; version="[1,2)"
B: Export-Package: p; version=1.5.1

A B
version=[1,2)
p p-1.5.1

C
p-2.4.1

import

export

25

Package constraints :: 1

Package s from B depends on particular version of package p from D
(for example s is a service and p is a domain object). Client A should
not import package p from the arbitrary location:

A B
s s
p p

This route is dictated uses
by uses directive
This route will cause directive
ClassCastException

C D
p-2.1 p-2.4

26

Package constraints :: 2
A B A: Import-Package: p;t
B: Export-Package: p;uses:=“q”
p p
Import-Package: q
t q C: Export-Package: q;uses:=“r,s”
Import-Package: r;s
D: Export-Package: s,t
C
E: Export-Package: r;uses:=“t”
q Import-Package: t
r
s

D E
s r
t t

To maintain class space consistency, the Framework must ensure that
none of its bundle imports conflicts with any of that bundle’s implied
packages.
27

Class filtering

An exporter can limit the visibility of the classes in a package with
the include and exclude directives on the export definition. The
value of each of these directives is a comma-separated list of class
names.

Class names must not include their package name and do not end
with .class. That is, the class com.acme.foo.Daffy is named Daffy
in either list. The class name can include multiple wildcards (’*’).

The ordering of include and exclude is not significant. The default
for the include directive is ’*’.

Export-Package: com.acme.foo;exclude:=“*Impl”

28

Provider selection
Specification defines the following headers which may be used
[in particular] for wiring:
Bundle-SymbolicName
Bundle-Version
bundle-symbolic-name and
The following definitions will match: bundle-version must not be
A: Bundle-SymbolicName: A declared in Export-Package
explicitly. The Framework will
Import-Package: com.acme.foo; automatically associate this
bundle-symbolic-name=B; information.
bundle-version="[1.41,2.0)"
B: Bundle-SymbolicName: B
Bundle-Version: 1.41
Export-Package: com.acme.foo
The following definitions not match because B does not
specify a version and thus defaults to 0.0.0:
A: Bundle-SymbolicName: A
Import-Package: com.acme.foo;
bundle-symbolic-name=B;
bundle-version="[1.41,2.0)"
Export-Package: com.acme.foo;version=1.42 29

Custom attributes :: 1
We already know that the Import-Package header may be used with
the following attributes: version, bundle-symbolic-name, bundle-
version. The Export-Package header may be used with the version
attribute (bundle-symbolic-name and bundle-version will be added
automatically).

In accordance with the specification developer may declare custom
attributes in the Export-Package and check these attributes in
Import-Package. Attributes are compared as strings.

The following statements will match because a match is not
prevented if the export definition contains attributes that do not
occur in the import definition:

A: Import-Package: com.acme.foo;company=“ACME”
B: Export-Package: com.acme.foo;company="ACME";security=false

30

Custom attributes :: 2

The mandatory directive may be used to declare attributes which
must occur in the import definition. The following statements will
not match because import definition doesn’t specify mandatory
security attribute:

A: Import-Package: com.acme.foo;company=“ACME”
B: Export-Package: com.acme.foo;company="ACME";
security=false;mandatory:=security

31

Optional packages
A bundle can indicate that it does not require a package to resolve
correctly, but it may use the package if it is available. For example,
logging is important, but the absence of a log service should not
prevent a bundle from running.

Optional imports can be specified in the following ways:
Resolution Directive – The resolution directive on an import
definition specifying the value optional. A bundle may successfully
resolve if a suitable optional package is not present.

Dynamic Imports – The DynamicImport-Package header is
intended to look for an exported package when that package is
needed. The key use case for dynamic import is the Class.forName
method when a bundle does not know in advance the class name it
may be requested to load.

An attempt is made to establish a wire for a dynamic import every time
there is an attempt to load a class in that package, whereas the wire
for a resolution optional package may only be established when the
bundle is resolved.
32

Resolution directive

The resolution directive can take the following values:
mandatory
optional

A: Import-Package: p;
resolution:=optional;
version=1.6
B: Export-Package: p;
q;
version=1.5.0
The implementation of a bundle that uses optional packages must
be prepared to handle the fact that the packages may not be
available: that is, an exception can be thrown when there is a
reference to a class from a missing package.

When an optional package cannot be resolved, any attempts by the
bundle to load classes from it will follow normal bundle class
loading search order as if the import never existed.
33

Dynamic import
DynamicImport-Package: org.foo.*
Dynamic imports apply only to packages for which no wire has been
established and no definition could be found in any other way. Dynamic
import is used as last resort. This will be discussed later.
No directives are architected by the Framework for DynamicImport-
Package. Arbitrary matching attributes may be specified. The following
arbitrary matching attributes are architected by the Framework:
version – A version range to select the version of an export
definition. The default value is 0.0.0.
bundle-symbolic-name – The bundle symbolic name of the
exporting bundle.
bundle-version – a version range to select the bundle
version of the exporting bundle. The default value is 0.0.0.

Dynamic imports must be searched in the order in which they are
specified. The order is particularly important when package names with
wildcards are used. The order will then determine the order in which
matching occurs. This means that the more specific package
specifications should appear before the broader specifications.
34

Fragment bundles :: 1
Fragments are bundles that can be attached to one or more host
bundles by the Framework. Attaching is done as part of resolving: the
Framework appends the relevant definitions of the fragment bundles to
the host’s definitions before the host is resolved.

A key use case for fragments is providing translation files for different
locales. This allows the translation files to be treated and shipped
independently from the main application bundle.

All class or resource loading of a fragment is handled through the host’s
class loader or Bundle object, a fragment must never have its own class
loader. Fragment bundles are treated as if they are an intrinsic part of
their hosts. Fragment can’t declare Bundle-Activator header.

Fragment can’t declare Bundle-Activator header.

A B
<<host>> <<fragment>>

35

Fragment-Host: BundleA-Symbolic-Name

The bundle-version of the host bundle may be specified as an attribute.

Fragments can never unilaterally insert code ahead of their host’s
bundle class path. Nevertheless host bundle can allow to insert code
ahead of its own code – this will be discussed later.

36

Fragments must remain attached to a host as long as the host remains
resolved. When a host bundle becomes unresolved, then all its attached
Fragment bundles must be detached from the host bundle. When a
fragment bundle becomes unresolved the Framework must:
1. Detach it from the host
2. Re-resolve the host bundles
3. Reattach the remaining attached fragment bundles.

A Fragment bundle can become unresolved by calling the
refreshPackages method.

C A B
<<fragment>> <<host>> <<fragment>>

37



C A B

38



C A B

39



C A B

40

Extension bundles :: 1
Extension bundles can deliver optional parts of the Framework
implementation or provide functionality that must reside on the boot
class path. These packages cannot be provided by the normal
import/export mechanisms.
Fragment-Host: com.acme.impl.framework; extension:=framework
Directive extension is only applicable when the Fragment-Host is the
System Bundle. The following values are supported:
framework – The fragment bundle is a Framework extension
bundle. Framework extensions are necessary to provide
implementation aspects of the Framework. For example, a
Framework vendor could supply the optional services like
Permission Admin service and Start Level service with
Framework extension bundles.

bootclasspath – The fragment bundle is a boot class path
extension bundle. Boot class path extensions are necessary
because certain package implementations assume that they are
on the boot class path or are required to be available to all
clients.
41

Extension bundles :: 2
An extension bundle must throw a BundleException if it is
installed or updated and it specifies any of the following headers:

Import-Package
Require-Bundle
Bundle-NativeCode
DynamicImport-Package
Bundle-Activator

42

Requiring bundles :: 1
The Require-Bundle manifest header contains a list of bundle
symbolic names that need to be searched after the imports are
searched but before the bundle’s class path is searched. Fragment or
extension bundles can not be required.

The framework must take all exported packages from a required
bundle, including any packages exported by attached fragments, and
wire these packages to the requiring bundle.

The following directives can be used in the Require-Bundle header:
visibility – If the value is private (default), then all visible
packages from the required bundles are not re-exported. If the
value is reexport then bundles that require this bundle will
transitively have access to these required bundle’s exported
packages.
resolution – If the value is mandatory (default) then the
required bundle must exist for this bundle to resolve. If the value
is optional, the bundle will resolve even if the required bundle
does not exist.
43

Requiring bundles :: 2
Requiring bundles is quite dangerous and error-prone way to wire bundles.
Specification underlines the following drawbacks of this approach:
Split Packages – Classes from the same package can come from different
bundles with Require bundle, such a package is called a split package.
Completeness – Split packages are open ended, it is difficult to
guarantee that all the intended pieces of a split package have
actually been included.
Ordering – If the same classes are present in more than one
required bundle, then the ordering of Require-Bundle is
significant. A wrong ordering can cause hard to trace errors,
similar to the traditional class path model of Java.
Performance – A class must be searched in all providers when
packages are split. This potentially increases the number of
times that a ClassNotFoundException must be thrown which can
potentially introduce a significant overhead.
Mutable Exports – The feature of visibility:=reexport that the export
signature of the requiring bundle can unexpectedly change depending on
the export signature of the required bundle.
Shadowing – The classes in the requiring bundle that are shadowed by
those in a required bundle depend on the export signature of the
required bundle and the classes the required bundle contains. 44

System bundle exports
The system property
org.osgi.framework.system.packages
contains the export packages descriptions for the system bundle.
Framework implementations should attempt to load these classes
from the boot class path.

45

Resolving process

46

Bundle class path :: 1

Bundle JAR

Fragment (id=1) JAR
Entry path
Fragment (id=2) JAR

Fragment (id=3) JAR

The Bundle-ClassPath header may be declared in manifest in order to
manage class path.
The content of the effective bundle class path is constructed from the
bundle’s Bundle-Classpath header, concatenated with the Bundle-
Classpath headers of any fragments, in ascending bundle id order.

47


A: Bundle-ClassPath:.,resource.jar
B: Fragment-Host: A

The effective class path is A:/, resource.jar, B:/

resource.jar is first looked up in the host bundle’s container, and if
not found, the entry is looked up in the container of B.

48

Fragments can never unilaterally insert code ahead of their host’s
bundle class path. Nevertheless host bundle can allow to insert code
ahead of its own code.

A: Bundle-SymbolicName: A
Bundle-ClassPath:.,required.jar,optional,default.jar
Fragment-Host: A
A B
required.jar optional/..
default.jar fragment.jar

The effective class path is:
A:/
A: required.jar
B: optional
A: default.jar
B: fragment.jar
49

Search order :: 1

50

Search order :: 2

51

Search order :: 3

52

Activation Policy
Bundle may specify activation policy in its manifest. Activation
means triggering of Bundle Activator. The only policy defined is the
lazy activation policy. If no Bundle-ActivationPolicy
header is specified, the bundle will use eager activation.
By default, any class load can trigger the lazy activation, however,
resource loads must not trigger the activation. The lazy activation
policy can define which classes cause the activation with the
following directives:

include – A list of package names that must trigger the activation
when a class is loaded from any of these packages. The default is all
package names present in the bundle.

exclude – A list of package names that must not trigger the
activation of the bundle when a class is loaded from any of these
packages. The default is no package names.

Bundle-ActivationPolicy: lazy;
include:="com.acme.service.base,com.acme.service.help"
53

Manifest Headers :: 1
Bundle-ActivationPolicy: lazy
The Bundle-ActivationPolicy specifies how the framework should activate the bundle once started.

Bundle-Activator: com.acme.fw.Activator
The Bundle-Activator header specifies the name of the class used to start and stop the bundle.

Bundle-Category: osgi, test, nursery
The Bundle-Category header holds a comma-separated list of category names.

Bundle-ClassPath: /jar/http.jar,.
The Bundle-ClassPath header defines a comma-separated list of JAR file path names or directories
(inside the bundle) containing classes and resources. The period (’.’) specifies the root directory of
the bundle’s JAR. The period is also the default.

Bundle-ContactAddress: 2400 Oswego Road, Austin, TX 74563
The Bundle-ContactAddress header provides the contact address of the vendor.

Bundle-Copyright: OSGi (c) 2002
The Bundle-Copyright header contains the copyright specification for this
bundle.

Bundle-Description: Network Firewall
The Bundle-Description header defines a short description of this bundle.

54

Bundle-DocURL: http:/www.acme.com/Firewall/doc
The Bundle-DocURL headers must contain a URL pointing to documentation
about this bundle.

Bundle-Icon: /icons/acme-logo.png
The optional Bundle-Icon header provides a list of URLs to icons representing
this bundle in different sizes.

Bundle-License:
http://www.opensource.org/licenses/jabberpl.php
The Bundle-License header provides an optional machine readable form of license information.

Bundle-Localization: OSGI-INF/l10n/bundle
The Bundle-Localization header contains the location in the bundle where localization files can be
found. The default value is OSGI-INF/l10n/bundle. Translations are by default therefore OSGI-
INF/l10n/bundle_de.properties, OSGI-INF/l10n/bundle_nl.properties

Bundle-ManifestVersion: 2
The Bundle-ManifestVersion header defines that the bundle follows the rules of this specification.
The Bundle-ManifestVersion header determines whether the bundle follows the rules of this
specification. It is 1 (the default) for Release 3 Bundles, 2 for Release 4 and later.

Bundle-Name: Firewall
The Bundle-Name header defines a readable name for this bundle. This should be a short, human-
readable name that can contain spaces.

55

Bundle-NativeCode: /lib/http.DLL; osname = QNX; osversion =
3.1
The Bundle-NativeCode header contains a specification of native code
libraries contained in this bundle.

Bundle-RequiredExecutionEnvironment: CDC-1.0/Foundation-1.0
The Bundle-RequiredExecutionEnvironment contains a comma-separated list of execution
environments that must be present on the Service Platform.

Bundle-SymbolicName: com.acme.daffy
The Bundle-SymbolicName header specifies a non-localizable name for this bundle. The bundle
symbolic name together with a version must identify a unique bundle.

Bundle-UpdateLocation:
http://www.acme.com/Firewall/bundle.jar
The Bundle-UpdateLocation header specifies a URL where an update for this bundle should come
from. If the bundle is updated, this location should be used, if present, to retrieve the updated JAR
file.

Bundle-Vendor: OSGi Alliance
The Bundle-Vendor header contains a human-readable description of the bundle vendor.

Bundle-Version: 1.1
The Bundle-Version header specifies the version of this bundle.

56

DynamicImport-Package: com.acme.plugin.*
The DynamicImport-Package header contains a comma-separated list of
package names that should be dynamically imported when needed.

Export-Package: org.osgi.util.tracker;version=1.3
The Export-Package header contains a declaration of exported packages.

Export-Service: org.osgi.service.log.LogService
Deprecated.

Fragment-Host: org.eclipse.swt; bundle-version="[3.0.0,4.0.0)"
The Fragment-Host header defines the host bundles for this fragment.

Import-Package:
org.osgi.util.tracker,org.osgi.service.io;version=1.4
The Import-Package header declares the imported packages for this bundle.

Import-Service: org.osgi.service.log.LogService
Deprecated

Require-Bundle: com.acme.chess
The Require-Bundle header specifies that all exported packages from
another bundle must be imported, effectively requiring the public interface
of another bundle.

57

Part III
Bundles

Service Layer

Security
Life Cycle Layer

Module Layer

OSGi framework

58

Interfaces overview
An optional part of a bundle. An optional part of a bundle. Initializes
Enables bundle to listen events bundle. Framework passes personal
BundleContext to each activator
<<interface>> <<register>> <<interface>>
BundleListener BundleActivator
<<create>>
<<interface>> <<register>>
FrameworkListener <<receive>>
Is used to
start, stop, <<install new>>
update <<interface>> <<interface>>
bundle and Bundle BundleContext
control its <<association>>
state and
parameters Each bundle has its own instance of context
and each context has a context bundle

Framework <<interface>> <<create>> <<interface>> Is used to
is a bundle Framework FrameworkFactory instantiate the
Framework

59

Launching Framework :: 1
void launch( String factoryName, File[] bundles )throws Exception {
Map p = new HashMap();
p.put( "org.osgi.framework.storage",
System.getProperties("user.home")+File.separator+"osgi");
FrameworkFactory factory = (FrameworkFactory)
Class.forName( factoryName ).newInstance();

Framework framework = factory.newFramework(p);
framework.init();

// Framework state is STARTING, context is available, bundles are in
// INSTALLED state

BundleContext context = framework.getBundleContext();
for ( File bundle : bundles )
context.installBundle( bundle.toURL().toString() );

framework.start();

// Framework and bundles are in ACTIVE state, services may be
// obtained via getService

framework.waitForStop();

// Framework releases any resources and goes to RESOLVED state, may
// be started again
} 60

Launching properties :: 1

Map p = new HashMap();
...
Framework framework = factory.newFramework(p);

The Map object given as a parameter to the newFramework
method provides the initialization properties to the framework.
The framework must not look in the System properties, the
given Map is complete.

61

Launching properties :: 2

org.osgi.framework.executionenvironment

org.osgi.framework.storage - The framework is free to use this
directory as it sees fit, for example, completely erase all files and
directories in it.

org.osgi.framework.system.packages - The packages that should be
exported from the System Bundle.

org.osgi.framework.system.packages.extra - Packages specified in
this property are added to the org.osgi.framework.system.packages
property and therefore have the same syntax. This allows the
configurator to only define the additional packages and leave the
standard VM packages to be defined by the framework.

org.osgi.framework.trust.repositories - This property is used to
configure trust repositories for the framework. The value is path of files.

62

Framework Lifecycle

newFramework

update
stop init
INSTALLED
STARTING
init start
update start start init
stop init
start

RESOLVED ACTIVE
stop
update
stop
update
stop
update
start STOPPING
init

update stops the Framework and restarts to its previous state
63

BundleContext :: 1
A bundle's execution context within the Framework. The context is
used to grant access to other methods so that this bundle can interact
with the Framework.
BundleContext methods allow a bundle to:
Subscribe to events published by the Framework.

Register service objects with the Framework service registry.

Retrieve ServiceReferences from the Framework service registry.

Get and release service objects for a referenced service.

Install new bundles in the Framework.

Get the list of bundles installed in the Framework.

Get the Bundle object for a bundle.

Create File objects for files in a persistent storage area provided
for the bundle by the Framework. 65

BundleContext :: 2
A BundleContext object will be created and provided to the bundle
associated with this context when it is started using the
BundleActivator.start(org.osgi.framework.BundleContext)
method. The same BundleContext object will be passed to the
bundle associated with this context when it is stopped using the
BundleActivator.stop(org.osgi.framework.BundleContext)
method. A BundleContext object is generally for the private use of
its associated bundle and is not meant to be shared with other
bundles in the OSGi environment.

The Bundle object associated with a BundleContext object is
called the context bundle.
The BundleContext object is only valid during the execution of its
context bundle. The BundleContext object must never be reused
after its context bundle is stopped.

66

Getting bundle information

The BundleContext interface defines methods to retrieve
information about bundles installed in the OSGi Service Platform:

getBundle() – Returns the single Bundle object associated
with the BundleContext object.

getBundles() – Returns an array of the bundles currently
installed in the Framework.

getBundle(long) – Returns the Bundle object specified by
the unique identifier, or null if no matching bundle is found.

67

Persistent storage and properties

The Framework should provide a private persistent storage area
for each installed bundle on platforms with some form of file
system support. BundleContext interface defines the following
method:
File getDataFile(String filename)

The BundleContext interface defines a method for returning
information pertaining to Framework properties:
getProperty(String). In particular the following properties are
supported:

org.osgi.framework.version
org.osgi.framework.processor
org.osgi.framework.os.name

68

The bundle object

69

The Bundle Object

For each bundle installed in the OSGi Service Platform, there is
an associated Bundle object. The Bundle object for a bundle can
be used to manage the bundle’s life cycle.

Bundle is identified by:
Bundle Identifier - A long that is a Framework assigned
unique identifier for the full lifetime of a bundle, even if
it is updated or the Framework is restarted.

Bundle location – A name assigned by the management
agent (Operator) to a bundle during the installation. This
string is normally interpreted as a URL to the JAR file but
this is not mandatory. Within a particular Framework, a
location must be unique.
Bundle Symbolic Name and Bundle Version – A name and
version assigned by the developer. The combination of
Bundle Version and Bundle Symbolic Name is a globally
unique identifier for a bundle.
70

Bundle Lifecycle :: 1

install
update
refresh

INSTALLED
STARTING
refresh
resolve update
start

RESOLVED ACTIVE
uninstall
uninstall stop

UNINSTALLED STOPPING

71

Bundle Lifecycle :: 2

When a bundle is installed, it is stored in the persistent
storage of the Framework and remains there until it is
explicitly uninstalled. Whether a bundle has been started or
stopped must be recorded in the persistent storage of the
Framework. A bundle that has been persistently recorded as
started must be started whenever the Framework starts until
the bundle is explicitly stopped.

72

Installing and resolving bundles

The BundleContext defines the following methods for
installing a bundle:

Bundle installBundle(String location)
Bundle installBundle(String location, InputStream input)

Will be used as identifier

Every bundle is uniquely identified by its location string. If an
installed bundle is using the specified location, the
installBundle methods must return the Bundle object for
that installed bundle and not install a new bundle.

The returned bundle may be in INSTALLED or RESOLVED state.
The Framework decides when to resolve bundle, resolving
can’t be triggered via Bundle or BundleContext API.

73

Starting bundles
The Bundle defines the following methods:
Is used to specify activation policy for
void start() current start and/or alter persistent
void start(int options) autostart setting

Each bundle is associated with persistent autostart setting.
This setting can have the following values:

Stopped – The bundle should not be started.

Started with eager activation – The bundle must be started
once it is ready and it must then be eagerly activated.

Started with declared activation – The bundle must be
started once it is ready and it must then be activated
according to its declared activation policy (Bundle-
ActivationPolicy).

74

Activation
A bundle is activated by calling its Bundle Activator object, if one
exists. The start(BundleContext) method will be called.
Fragment bundles must not have a Bundle Activator specified.
Activation policy:
Bundle may specify activation policy in its manifest. The only
policy defined is the lazy activation policy. If no Bundle-
ActivationPolicy header is specified, the bundle will use
eager activation
A lazy activation policy indicates that the bundle, once
started, must not be activated until a class is loaded from it;
either during normal class loading or via the Bundle
loadClass method.
The lazy activation policy allows a Framework implementation
to defer the creation of the bundle class loader and activation
of the bundle until the bundle is first used; potentially saving
resources and initialization time during startup.
Started bundle has state STARTING until activation. After
successful activation state is ACTIVE. 75

Stopping bundles
May simply deactivate bundle or set
void stop() autostart setting to Stopped
void stop(int options)

A bundle is deactivated by calling its Bundle Activator object, if
one exists. The stop(BundleContext) method will be called.

76

Updating bundles

void update()
void update(InputStream input)

The update process supports migration from one version of a
bundle to a newer version of the same bundle. The exports of an
updated bundle must be immediately available to the
Framework. If none of the old exports are used, then the old
exports must be removed. Otherwise, all old exports must
remain available for existing bundles and future resolves until
the refreshPackages method is called or the Framework is
restarted. The refreshPackages method will be discussed later.

After the update operation is complete, the framework must
attempt to move the bundle to the same state as it was before
the operation taking the activation policy into account, without
changing the autostart setting.

77

Uninstalling bundles

void uninstall()

Once this method returns, the state of the OSGi Service Platform
must be the same as if the bundle had never been installed,
unless bundle exports packages or bundle was selected by the
Framework as the exporter of packages. If none of the old
exports are used, then the old exports must be removed.
Otherwise, all old exports must remain available for existing
bundles and future resolves until the refreshPackages method
is called or the Framework is restarted.

78

Detecting bundle changes
The Framework must keep the time that a bundle is changed by
any of the life cycle operations. The getLastModified() method
will return the last time the bundle was installed, updated, or
uninstalled. This last modified time must be stored persistently.

79

Loading classes
One bundle can load classes directly form foreign class loader.

Load plugins from another bundle
Start an application model activator
Interact with legacy code

BundleContext A

1: Bundle getBundle(long id)

2: Class loadClass(String name)
Bundle A Bundle B

Class Loader B

Class X

80

Resources
The Bundle interface defines two methods to return manifest
header information:
Dictionary getHeaders()
Dictionary getHeaders(String locale)

The resources from a bundle can come from different sources.
They can come from the raw JAR file, Fragment bundles,
imported packages, or the bundle class path. The Bundle
interface provides a number of methods that access
resources but use different strategies:
java.net.URL getResource(java.lang.String name)- provide
access to resources that is consistent with the class space as
described in Overall Search Order.

findEntries(String path, String filePattern, boolean
recurse) - Returns entries in this bundle and its attached fragments
(scans JARs). Required bundles will not be scaned.

getEntry(String path) - Returns a URL to the entry at the
specified path in this bundle (scan JAR).
81

The System Bundle
In addition to normal bundles, the Framework itself is represented
as a bundle. The bundle representing the Framework is referred to
as the system bundle.

The system bundle is listed in the set of installed bundles returned
by BundleContext.getBundles()

The system bundle is always assigned a bundle identifier of zero.

The system bundle’s life cycle cannot be managed like normal
bundles. Its life cycle methods must behave as follows:
start – Does nothing because the system bundle is already started.
stop – Returns immediately and shuts down the Framework on
another thread.
update – Returns immediately, then stops and restarts the
Framework on another thread.
uninstall – The Framework must throw a BundleException
indicating that the system bundle cannot be uninstalled.

82

Events
BundleEvent Reports changes in the life cycle of bundles.

Reports that the Framework is started, start level
FrameworkEvent has changed, packages have been refreshed, or
that an error has been encountered.

BundleContext defines the following methods:

void addBundleListener(BundleListener listener)
void addFrameworkListener(FrameworkListener listener)
void removeBundleListener(BundleListener listener)
void removeFrameworkListener(FrameworkListener listener)

Bundle listeners may be synchronous or asynchronous, framework
listeners are asynchronous.

84

Bundle listeners
<<interface>>
BundleListener
INSTALLED STOPPED
bundleChanged(BundleEvent event) LAZY_ACTIVATION STOPPING
RESOLVED UNINSTALLED
STARTED UNRESOLVED
<<interface>> STARTING UPDATED
SynchronousBundleListener

SynchronousBundleListener objects are called synchronously
during the processing of the event and must be called before any
BundleListener object is called.
Asynchronous delivery: The Framework may use one or more threads
to hit listeners but each handler must receive the events in the same
order as the events were posted.
Synchronous delivery: In rare cases, events can be delivered out of
order to a listener. One pathological case is when a service listener
unregisters a service that it receives in the REGISTERED event for. If
there are listeners queued behind the pathological listener then they
see the unregistering before they see the registration.
85

Performance and memory footprint

The OSGi is said to have very little performance overhead

Standard java uses linear class path. OSGi supports fast class
loading because information about classes and class loaders is
usually indexed in a hash table. Nevertheless initialization is said
to be a bottleneck:

1 second per bundle is an extra minute boot time for a
system with 60 bundles

Don’t use name lookups and network access in the bundle
activators

Initialization process should be spread in time by means of
lazy initialization

Each bundle has its own class loader and class loaders are said to
be expensive. Don’t start to many bundles; stop unused bundles.
86

Part IV
Bundles

Service Layer

Security
Life Cycle Layer

Module Layer

OSGi framework

87

Interfaces overview

<<interface>> Is used to manage service
ServiceRegistration account <<interface>>
ServiceFactory

<<create>>
<<may implement>>
<<interface>> <<register/unregister, get/unget>>
BundleContext Service

<<locate>>
<<register>>
<<interface>>
Is used to obtain service, its
ServiceReference <<interface>>
properties and providing bundle
ServiceListener

<<navigate>> <<navigate>>

<<interface>> Provides information about
Bundle <<create>>
exported and used services

88

Example of workflow

1. Provider bundle contains service implementation and/or interfaces.
Service implementation may optionally implement ServiceFactory
interface.
2. Provider bundle registers new service via BundleContext and stores
returned ServiceRegistration.
3. Client bundle locates ServiceReference by service name and filters
via BundleContext.
4. Client obtains actual service object by ServiceReference via
BundleContext.

5. Client works with service.

6. Client releases service object via BundleContext.
7. Provider unregisters service via ServiceRegistration.
8. The Framework publishes unregistering event. All clients must clear
references to service object.

89

Registering Services

BundleContext declares the following methods for service registering:

ServiceRegistration registerService(String clazz,
Object service,
Dictionary properties)

ServiceRegistration registerService(String[] clazz,
Object service,
Dictionary properties)
clazz – Interface name(s)
service – Service implementation
properties – Service properties

Every successful service object registration must yield a unique
ServiceRegistration object even if the same service object is registered
multiple times.

90

Service properties :: 1
Service properties are used to specify meta information about services.
This information may be used to filter services during location.

The values of properties should be limited to primitive or standard
Java types to prevent unwanted inter bundle dependencies.

Key must be a String and value should be a type recognized by
Filter objects (if value is not a String, it should implement
Comparable and have constructor taking single String object).

The key of a property is not case sensitive. When a Dictionary object
that contains keys that only differ in case is passed, the Framework
must raise an exception.

All properties share a single name space in the Framework service
registry.

The service properties are intended to provide information about the
service object. The properties should not be used to participate in the
actual function of the service. Modifying the properties for the service
registration is a potentially expensive operation.
91

Service properties :: 2
The Framework supports the following standard properties:

Property Type Description
service.id Long The Framework assigns a unique value to every
registered service object that is larger than values
provided to all previously registered service objects.
service.pid Long The purpose of a Persistent Identifier (PID) is to
identify a service across Framework restarts. If the
bundle is stopped and later started, the same
PID must always be used.
service.ranking Integer When registering a service object, a bundle may
optionally specify a service.ranking number as one of
the service object’s properties. If multiple qualifying
service interfaces exist, a service with the highest
SERVICE_RANKING number determines which
service object is returned by the Framework.
objectClass String[] The objectClass property contains the set of interface
names under which a service object is registered
with the Framework. The Framework must set this
property automatically.

92

Locating services
Bundle context declares the following methods for service locating:

ServiceReference getServiceReference(String clazz)
If multiple such services exist, the service with the highest ranking
is returned. If there is a tie in ranking, the service with the lowest
service ID; that is, the service that was registered first is returned.

ServiceReference[] getServiceReferences(String clazz,
String filter)
The returned array of ServiceReference objects contains services
that were registered under the specified class, match the specified
filter criteria, and the packages for the class names under which the
services were registered match the context bundle's packages.

ServiceReference[] getAllServiceReferences(String clazz,
String filter)
As previous but doesn’t check that package under which the
services were registered are assignable to the context bundle’s
packages. This method is infrastructural, it shouldn’t be used for
ordinal service location. 93

Getting and releasing service object

BundleContext declares the following methods for service clients:

Object getService(ServiceReference reference)

boolean ungetService(ServiceReference reference)

true if actually unregistered, false if service is not
[already] associated with bundle

94

Service Factory
Often, the service object that is registered by a bundle is returned
directly. If, however, the service object that is registered implements
the ServiceFactory interface, the Framework must call methods on this
object to create a unique service object for each distinct bundle that
gets the service.
Object getService(Bundle bundle,
ServiceRegistration registration)
void ungetService(Bundle bundle,
ServiceRegistration registration,
Object service)
The Framework calls getService if the bundle’s usage count of that
service object is zero. After this the Framework must cache the mapping
of the bundle-to-service request, and return the cached service object.

The Framework must check the service object returned by this method.
If it is not an instance of all the classes named when the service factory
was registered, null is returned to the caller that called getService.

The Framework calls ungetService if the bundle’s usage count for that
service object must drop to zero after this call returns; that is, the
bundle is about to release its last dependency on the service object. 95

Unregistering Services :: 1

The ServiceRegistration interface defines the unregister()
method to unregister the service object. This must remove the
service object from the Framework service registry.
ServiceEvent.UNREGISTERING will be published.
The bundle that unregisters a service object might not be the same
bundle that registered it.

96

Unregistering Services :: 2

Framework invalidates all ServiceReferences after unregistering, but
pointers to service objects can not be cleared by framework. Bundles
must listen to events generated by the Framework to clean up and
remove stale references.

Service developers can minimize the consequences of (but not
completely prevent) stale references by using the following
mechanisms:
Implement service objects using the ServiceFactory
interface. The methods in the ServiceFactory interface
simplify tracking bundles that use their service objects.
Use indirection in the service object implementations.
Service objects handed out to other bundles should use a
pointer to the actual service object implementation. When
the service object becomes invalid, the pointer is set to null,
effectively removing the reference to the actual service
object.

97

Service Events
BundleContext declares the following methods for listeners registration:
void addServiceListener(ServiceListener listener)
void addServiceListener(ServiceListener listener, String filter)
void removeServiceListener(ServiceListener listener)

REGISTERED – A service has been registered.

MODIFIED – The properties of a service have been modified.

MODIFIED_ENDMATCH – Listeners registered with a filter can not see
the MODIFIED event when a modification makes this filter no longer
match. The lack of this notification complicates tracking a service with
a filter. The MODIFIED_ENDMATCH event is therefore delivered if the
old service properties matched the given filter but the modified
properties do not.

UNREGISTERING – A service is in the process of being unregistered.
This event is synchronously delivered before the service has completed
unregistering. That is, the service object is still valid. The bundle
receiving this event must release all references to this service before
this method returns. 98

Part V
Basic Services

99

Package Admin Service

100

Packages :: 1

The PackageAdmin class provides the following methods:

getExportedPackage(String) – Returns an ExportedPackage object
that provides information about the requested package. This
information can be used to make the decision to refresh the package.

getExportedPackages(Bundle) – Returns a list of ExportedPackage
objects for each package that the given bundle exports.

resolveBundles(Bundle[]) – The Framework must attempt to resolve
the given bundles.

101

Packages :: 2

refreshPackages(Bundle[]) – The management agent may call this
method to refresh the exported packages of the specified bundles.

1. Compute a graph of bundles starting with the specified
bundles. If no bundles are specified, compute a graph of
bundles starting with bundle updated or uninstalled since the
last call to this method. Add to the graph any bundle that is
wired to a package that is currently exported by a bundle in the
graph. The graph is fully constructed when there is no bundle
outside the graph that is wired to a bundle in the graph. The
graph may contain UNINSTALLED bundles that are currently still
exporting packages.
2. Each bundle in the graph that is in the ACTIVE state will be
stopped as described in the Bundle.stop method.

3. Each bundle in the graph that is in the RESOLVED state is
unresolved and thus moved to the INSTALLED state. The effect
of this step is that bundles in the graph are no longer
RESOLVED.
102

Packages :: 3
4. Each bundle in the graph that is in the UNINSTALLED state is
removed from the graph and is now completely removed from
the Framework.
5. Each bundle in the graph that was in the ACTIVE state prior to
Step 2 is started as described in the Bundle.start method,
causing all bundles required for the restart to be resolved.
6. A framework event of type
FrameworkEvent.PACKAGES_REFRESHED is fired.

103

Bundles

getBundle(Class) – Answer the bundle with the class loader that
loaded the given class.

getBundles(String,String)– Find a the set of bundles with the given
bundle symbolic name and that fall within the given version. If the
version is null, all bundles with the given bundle symbolic name are
returned.

getBundleType(Bundle) – Answer the type of the bundle. This is a
bitmap of the different types.

104

Fragments and hosts
getFragments(Bundle) – Return an array of bundles that currently act
as fragment to the given bundle. If there are no fragments attached,
null must be returned.

getHosts(Bundle) – Return the bundles that acts as host to this
fragment bundle. The given bundle should be an attached fragment
bundle, otherwise null is returned.

getRequiredBundles(String) – Return an array of RequiredBundle
objects that match the given name (or all of the given name is null).
The RequiredBundle object provides structural information about a
required bundle.

105

Start Level Service

106

Start level
A start level is defined as a non-negative integer. A start level of 0 is
the state in which the Framework has either not been launched or
has completed shutdown (these two states are considered
equivalent). In this state, no bundles are running. Progressively
higher integral values represent progressively higher start levels.
For example, 2 is a higher start level than 1. The Framework must
support all positive int values (Integer.MAX_VALUE) for start levels.

The System Bundle is defined to have a start level of zero. The start
level of the System Bundle cannot be changed.

107

Start level service
The Framework has an active start level that is used to decide which
bundles can be started. All bundles must be assigned a bundle start
level. This is the minimum start level to start a bundle.

The bundle start level can be set with the
setBundleStartLevel(Bundle, int) method.

When a bundle is installed, it is initially assigned the bundle start
level returned by getInitialBundleStartLevel(). The initial bundle
start level to be used when bundles are installed can be set with
setInitialBundleStartLevel(int).

108

Active start level
A Management Agent can influence the active start level with the
setStartLevel(int) method. The Framework must then increase or
decrease the active start level by 1 until the requested start level is
reached. The process of starting or stopping bundles, which is
initiated by the setStartLevel(int) method, must take place
asynchronously.

109

Start up and shut down
At startup, the Framework must have an active start level of zero. It
must then move the active start level to the beginning start level. The
beginning start level is specified with an argument when starting the
Framework or through some other means, which is left undefined in
the specification. If no beginning start level is given, the Framework
must assume a beginning start level of one.

When the Framework shuts down, the requested start level must be
set to zero. The Framework must then follow the described process
to make the active start level equal to zero.

110

Part VI
Beyond this presentation

111

Beyond this presentation
Security. Platform has powerful mechanisms for security management
(roles, permissions, security-related services etc).

Special services and mechanisms. Specification describes several
auxiliary mechanisms like OSGi-specific URL handling or service
proxying.

Standard services. OSGi platform contains many standard services. In
particular:
Admin services. These services enables Management Agent
to control wiring strategies, deployment process,
configuration, monitoring etc.
Application services. Services for logging, IO, XML parsing.
Enterprise specification declares services for JTA, JMX, JPA,
and Web utilization.
Remote services. OSGi R4 introduces a distribution
providers.

112

OSGi Service Platform 4.2

More Related Content

What's hot (20)

Similar to OSGi Service Platform 4.2 (20)

Recently uploaded (20)

OSGi Service Platform 4.2