Deep Dive into OSGi (Lifecycle Layer)

(Chapter 3)

Aruna Karunarathna

Discussion

o Software Lifecycle Management

o Lifecycle of a Bundle

o The Lifecycle API

o Explore relationship between modules and lifecycle layer

o Demo (Sample Application)

Software Lifecycle Management

● Installation○ Along with the all dependencies

● Execution○ Acquiring resources and start functionalities

it suppose to do, if no longer needed stop application● Update

○ Update application● Uninstall

○ Remove application when no longer needed

Note - Most Applications(e.g Standard Java app ) do above steps as whole; for modular applications, using fine grained lifecycle management it is possible for manage lifecycle of individual modules.

OSGi Lifecycle Layer

o Internal to your application

The lifecycle layer precisely defines the bundle lifecycle operations. These lifecycle operations allow you to manage and evolve your application by dynamically changing the composition of bundles inside a running framework

o External to your application

The lifecycle layer defines how your bundles gain access to their execution context, which provides them with a way to interact with the OSGi framework and the facilities it provides at execution time

OSGi Bundle Lifecycle

o Modular Layer - Relies on Metadata provided by bundle

o Lifecycle Layer - API provided by OSGi

There is no other way to deal with the OSGi Life Cycle other than the provided API.

● Which is very powerful

● OSGi core framework doesn’t mandate any particular mechanism of interacting with the lifecycle API

OSGi Framework role in Lifecycle - Installation

o Standard Java - Place Jar files in classpath

o OSGi Framework - Install bundles to framework

OSGi Framework role in Lifecycle - Installation Cntd...

o Inherent Dynamism

The OSGi framework supports the full bundle lifecycle at execution time. This is similar to modifying what’s on the classpath dynamically in a Standard java app.

o Persist the Cache

This means the next time you start the framework, any previously installed bundles are automatically reloaded from the bundle cache, and the original JAR files are no longer necessary

Note- You can disable the persist bundle cache if you need a fresh framework start.

Bundle Activator Manifest Entry

o Defines the bundle’s identity

o Specifies the packages on which this bundle depends

o Specifies the packages on which this bundle exports

o Declares additional human-readable information

Manifest-Version: 1.0Bnd-LastModified: 1405099135557Build-Jdk: 1.7.0_55Built-By: arunaBundle-Activator: org.sample.ActivatorBundle-ManifestVersion: 2Bundle-Name: sampleBundle-SymbolicName: sampleBundle-Vendor: WSO2 IncBundle-Version: 1.0.0Created-By: Apache Maven Bundle PluginExport-Package: org.sample;uses:="org.osgi.framework";version="1.0.0"Import-Package: org.osgi.framework;version="[1.7,2)"Tool: Bnd-2.1.0.20130426-122213

Bundle Activator Manifest Entry cntd...

o Bundle Activator Manifest Entry is the hook to the Bundle execution entry point.

o Similar to the Main Method of a Jar file?..o Header value specifies the name of a reachable class

o Either a class in an Imported Packageo A class in the Bundle class path

o This class implements the org.osgi.framework.BundleActivator interface, and implements the following two methods.

o Can use these two methods to customize the behaviours when the bundle is started and stopped.

public interface BundleActivator { void start(org.osgi.framework.BundleContext bundleContext) throws java.lang.Exception; void stop(org.osgi.framework.BundleContext bundleContext) throws java.lang.Exception;}

Bundle Activator Manifest Entry cntd...

o When the bundle installed and started, OSGi Framework creates an instance of Bundle Activator class and call the start() method.

o When the bundle stop is initiated, OSGi Framework call the stop()

method.o In practice when the stop is called, you should undo everything you did

in the start method.o The activator instance on which start() is called is the same

instance on which stop() is called.o The activator instance is discarded and isn’t used again, after

stop() is called.o If the bundle is subsequently restarted after being stopped, a new

activator instance is created, and the start() and stop() methods are invoked on it as appropriate.

Bundle Activator vs Threading

o OSGi is designed around the normal java thread abstraction.

o The framework assumes that you handle the thread management and the programs are correctly synchronized and thread safe.

o The OSGi libraries are thread safe, and callbacks are normally done in a thread safe manner

o for. e.g The same thread called the start() method, is guaranteed by the framework to be called the stop() method in order not concurrently.

o If threads are used in a bundle make sure that all threads are stopped when the stop() method returns.

Bundle Context

o Can be accessed via start() and stop() of Bundle Activator classo Bundle context object is its role as the unique execution context of

its associated bundleo Valid while the bundle is active. (The time range from the framework

call start() up until to the stop() is called )

o Gain access to two types of methodso Related to deployment and lifecycle management.o Related to bundle interaction via services.

o They should be treated as sensitive or private objects and not passed freely among bundles

Bundle

o For each installed bundle, the framework creates a Bundle objecto From Bundle object, a bundle can identified by two additional forms

o Bundle Identifiero Bundle Location

o Bundle object persist over the framework executions when the installed bundles are reloaded from the framework’s cache.

Bundle cntd...

o Why we need two execution time identifiers?..

o Can’t we use Bundle Symbolic name and version to identify?..

History plays a role here. The notion of using a bundle’s symbolic name and version to uniquely identify it didn’t exist in versions of the specification prior to R4. Therefore, prior to R4, it made sense to have internally and externally assigned identifiers. Now it makes less sense, because the bundle’s symbolic name and version pair are externally defined and explicitly recognized internally by the framework.

The System Bundle

o Execution time framework is represented as a bundle, with Bundle ID set to 0 and it is called as the System Bundle.

o You don’t explicitly install the System Bundle, it always exists while

the framework is runningo Follows the same lifecycle as other Bundles in the framework, and you

can manipulate it with the same operations as normal bundles

o Lifecycle operations performed on the system bundle have special meanings when compared to normal bundles

One example of the special meaning is evident when you stop the system bundle. Intuitively, stopping the system bundle shuts down the framework in a well behaved manner. It stops all other bundles first and then shuts itself down completely.

Lifecycle State Diagram

Bundle Start

o Calls the Bundle.start() of the respective Bundle Object

o If the Bundle is INSTALLED state, it transitions to ACTIVE state via the RESOLVED and STARTING states.

o If the Bundle is UNINSTALLED, throws an IllegalStateException.

o If the Bundle is in STARTING or STOPPING statestart() is blocked until it enters ACTIVE or RESOLVED.

o If the bundle is in ACTIVE state, calling start has no effect.

o If the Bundle can’t satisfy it’s dependencies, calling Start will result in throwing a BundleException

o If a BundleActivator is specified, will call the start() in the BundleActivator class

Bundle Stop

o Calls the Bundle.stop() of the respective Bundle Object.

o If the Bundle is in UNINSTALLED state, throws anIllegalStateException.

o If the Bundle is in STARTING or STOPPING statestop() is blocked until it enters START or RESOLVED.

o If a BundleActivator is specified, will call the stop() in the BundleActivator class

o If the stop() method in the BundleActivator class, throws an exception, a BundleException is throws by the Bundle.stop() method

Update Command

o Bundle.update() comes in two formso Without parameterso With parameter InputStream

o If the Bundle is in ACTIVE state, first the Bundle.stop()Needs to be called by the framework.

o The update happens either in INSTALLED or RESOLVED state.

o If the Bundle is in UNINSTALLED state, the framework will thrown an IllegalStateException.

Tips - Don’t use the Bundle-UpdateLocation MF header.

Uninstall Command

o Calls the Bundle.uninstall() method in the framework.

o If the Bundle is in ACTIVE state, first the Bundle.stop()Needs to be called by the framework.

o If the Bundle is already in UNINSTALLED state, the framework will throw an IllegalStateException.

Tips - bundle shouldn’t attempt to stop, update, uninstall itself (Bundle Suicide)

Bundle cache and framework restarts

o A Bundle can be installed in 2 wayso Providing the url for the bundleo Providing bundle as an inputstream

o Framework reads the bundle JAR file and saves a copy in a private area known as the bundle cache

o Installing a bundle into the framework is a persistent operationo After the bundle is installed, the framework no longer needs the

original copy of the bundle JAR file

Bundle cache and framework restarts cntd...

o Framework persists Bundle status too..

o Bundle start() is called, the framework persistently marked as STARTED

o Bundle stop() is called, the framework persistently marked as STOPPED

o What about update and uninstall?..

o Remove the existing bundle from the cacheo Install a totally new bundle in the persistent cache

Bundle Configuration Properties

o BundleContext.getProperty() method to retrieve the propertieso Avoid the global aspect of System.getProperty(), and provides per

framework instance propertieso If not found in the BundleContext scope search in the global System

scopeo If you need to use these standard properties, you can use the constants

defined in the org.osgi.framework.Constants class

Listening for events

o OSGi framework supports two types of events: BundleEvents and

FrameworkEventso The former event type reports changes in the lifecycle of bundles, whereas

the latter reports framework-related changeso The BundleContext object has methods to register BundleListener and

FrameworkListener objects for receiving BundleEvent and FrameworkEvent notifications, respectively

o How to implement BundleListener and FrameworkListener in your code?.a. Create a new class which Implements BundleListener or FrameworkListener b. Implement the bundleChanged(BundleEvent) or

frameworkEvent(FrameworkEvent) methods respectively.c. Register by creating a new Object of the implemented class to the

BundleContext as a Listener using the bundleContext.addBundleListener() or bundleContext.addFrameworkListener() respectively.

o No need to call the removeBundleListener() or removeFrameworkListener(), which will automatically removed when the bundle is stopped.

Sample code for listening for events

public class MyListener implements BundleActivator , FrameworkListener , BundleListener{ @Override public void start(BundleContext bundleContext) throws Exception { bundleContext.addBundleListener(new MyListener ()); bundleContext.addFrameworkListener(new MyListener ()); }

@Override public void stop(BundleContext bundleContext) throws Exception { }

@Override public void bundleChanged(BundleEvent event) {

//TODO - implement }

@Override public void frameworkEvent(FrameworkEvent event) { //TODO - implement }}

Framework events

o FrameworkEvent.STARTED —Indicates the framework has performed all initialization and has finished starting up.

o FrameworkEvent.INFO —Indicates some information of general interest in various

situations.

o FrameworkEvent.WARNING —Indicates a warning. Not crucial, but may indicate a

potential error.

o FrameworkEvent.ERROR —Indicates an error. Requires immediate attention.

o FrameworkEvent.PACKAGES_REFRESHED —Indicates the framework has refreshed

some shared packages.

o FrameworkEvent.STARTLEVEL_CHANGED —Indicates the framework has changedits start level.

Bundle Events

o BundleEvent.INSTALLED — Indicates a bundle was

installed

o BundleEvent.RESOLVED — Indicates a bundled was

resolved

o BundleEvent.STARTED — Indicates a bundle was

started

o BundleEvent.STOPPED — Indicates a bundle was

stopped

o BundleEvent.UPDATED — Indicates a bundle was

updated

o BundleEvent.UNINSTALLED — Indicates a bundle was

uninstalled

o BundleEvent.UNRESOLVED — Indicates a bundle was

unresolved

Following events are only send to SynchronousBundleListeners (listener is notified during the processing of the event - HANDLE WITH CARE…!!!)

BundleEvent.STARTING — Indicates a bundle is about to be startedBundleEvent.STOPPING — Indicates a bundle is about to be stopped

DEMO

References

OSGi Alliance Specifications http://www.osgi.org/Specifications/HomePage

OSGI in Action - CREATING MODULAR APPLICATIONS IN JAVA

Sample - https://github.com/arunasujith/osgi-sample