1

Introduction to OSGi& Eclipse Virgo

Gordon Dickens

@gdickenslinkedin.com/in/gordondickensBlog: technophile.gordondickens.comGitHub: github.com/gordonad

2

>OSGi TerminologyOSGI containerBundleServiceSpring Dynamic ModulesSpring dm Server

3

OSGI ContainerA low-footprint engine that manages

OSGi componentsCan be embedded into applications

to provide modular componentsThree major OSGi Containers:

◦Equinox The reference implementation for the

framework. The container built into Eclipse. Used by default with Spring dm Server Spring dm Server moving to Eclipse Virgo

project◦Knoplerfish◦Apache Felix

4

The OSGi BundleJAR with extra Config Info

◦Classes and resources that deliver functions to consumers

◦Can “export” services & packages

◦Can “import” services & packages

5

More on Bundles (bundles for dummies?)

Bundle is a JAR

Requires a Manifest that describes the bundle◦META-INF/MANIFEST.MF

You configure the Manifest with◦A machine-readable ID◦Packages required◦Which packages are exportable/private◦Services interfaces to expose◦Requirements - such as the minimum JDK

6

Sample META-INF/MANIFEST.MF

Manifest-Version: 1.0Export-Package: com.gordondickens.utils,org.osgi.framework”Bundle-Name: Maven OSGi Demo – ServicesBuild-Jdk: 1.6.0Bundle-Version: 1.0.0Bundle-ManifestVersion: 2Bundle-Activator: com.gordondickens.services.ServiceActivatorBundle-SymbolicName: maven-osgi-demo-servicesImport-Package: org.osgi.framework;version="1.3"

7

MANIFEST.MF Keywords Bundle-ManifestVersion

◦ Which OSGi container rules to follow. 2 = OSGi Specification release 4 1 = OSGi version 3 or earlier

Bundle-Name◦ Short, human readable name

Bundle-SymbolicName◦ Unique, machine-usable name◦ Used by other bundles & container to refer to the bundle

Bundle-Version◦ Version of the bundle

Bundle-Activator◦ Listener class◦ May be bound to bundle lifecycle (start, stop events)

Bundle-Vendor◦ Human readable name for the vendor who created the bundle

Import-Package◦ Set of packages required for dependency management

8

DependenciesBundles are versioned using the

header Bundle-Version◦Matches Maven version numbers

(underscores converted to periods)Bundles can require other Bundles

to function◦This is configured with the Import-Package header

◦Required versions can be specified using the version= keyword

Versions can be a specific version or range

9

Bundle Lifecycle

10

What can you do with a bundle?

Bundles just expose packages or services to be used◦Does not automatically

hide impl classes◦Package exporting

should only be for utility packages (plumbing).

◦ You only want to expose “services”

11

ServicesRegister POJOs to container as a

service◦Source bundle registers the service interface

◦Target bundle asks the container registry for a reference to the service

Services are managed by Virgo◦Services are “published” to the container registry

◦Clients lookup and consume the services

12

Preparing the ManifestYou could do that by hand,

but…◦Format the MANIFEST.MF file EXACTLY per spec (ending each line on 72 characters, etc)

Instead, Virgo provides the Bundlor build tool

13

Bundlor

Input:◦ jar◦ template.mf

Import-Template

jar

template.mf

The BUNDLOR manifest.mf

• Generates:– manifest.mf

14

What is Blueprint?A framework that

◦Exposes & consumes services from Beans

◦Dynamically publishes App Contexts & beans

◦Handles dependencies◦Can pause bundles while locating

dependencies (during updates, etc)◦Simplifies defining OSGi bundles◦The basis for the Eclipse Virgo, a fully

OSGi-compliant platform based on Equinox

◦Originally from Spring Dynamic Modules

15

The Blueprint ExtenderExtender start up

◦ Looks for Blueprint enabled Bundles◦ Loads their application contexts

automatically◦ Publishes application contexts◦ Exports beans as Services◦ Injects any consumed services from other

Bundles automatically

When a bundle comes online◦ Detects & publishes the Application

Context◦ Inject beans from other required app

contextsReplaces Bundle Activator

16

Template.mfThe Bundlor uses the template.mf to generate the OSGi required manifest.mf file

Which header(s) to use for dependency resolution:

Import-Package - Core OSGi

◦ Used for every external package that the bundle depends on

Require-Bundle - Core OSGi

◦ Bundle must be found to start this bundle

◦ Used specifying the bundle and bundle's version

◦ Brittle, only searched if not found in Import-Package

Import-Bundle - Virgo

◦ Like Import-Package but all packages within an entire bundle

◦ Used specifying the bundle and bundle's version. Not always a best practice, too broad brush.

Import-Library - Virgo

◦ Imports all packages of a specific package, from a library in the Virgo repository.

◦ Packages can be resolved across multiple bundles

◦ Preferred approach for expressing dependency on the Spring Framework.

Import-Template - Bundlor

◦ Used to import packages by version range.

◦ Used when a transitive dependencies not found "your.package (0.0.0)" or "Import of package xyz doesn't specify a version”.

◦ Can use wildcards and setup custom patterns for matching.

In Summary, you need to Import Packages! Bundlor assists with directives to save you time instead of listing out all your packages in the standard OSGi Import-Package header.

17

Dependency ManagementIf a Bundle requires another

bundle◦Load the other bundle◦Damping - Suspends any threads

attempting to access the imported packages

◦Once loaded, threads are resumed

18

Using BlueprintConfiguring your contextThe blueprint: namespaceExporting beans as OSGi Services

into RegistryImporting beans from OSGi

Registry

19

Configuring your ContextGood practice:

◦Separate Spring configuration from Blueprint imports/exports bundle-context.xml bundle-context-osgi.xml

Create 2 context files in META-INF/spring◦All *.xml files in this dir are processed

20

Blueprint ServicesBlueprint enables services to be

published and consumed using descriptions written in XML

Eclipse Virgo supports BlueprintThe XML descriptions reside in

files with extension .xml in the bundle’s META-INF/spring sub-directory.

21

Spring DM ServicesTo publish a service <blueprint:service>

and specify◦ implementation class◦ interface class(es)◦ at bundle start, an instance is published to

the OSGi service registry under the interface

◦ impl class constructed like any other bean

To consume a service <blueprint:reference>◦ service may be passed into other beans using DI

22

Expose the Spring Bean as an OSGi Service

Use the osgi: namespace

<?xml version="1.0" encoding="UTF-8"?><blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd” default-activation="eager">

<service ref="exampleBean" interface="com.gordondickens.demo.bean.ExampleBean"/>

</blueprint>

23

Consuming the ServiceUse the blueprint: namespace:

◦Service Beans ◦Valid OSGi Service beans

Can be injected into other Beans using◦XML injection◦annotation-driven injection

24

Example: Consuming an OSGi ServiceUse the <reference> tag in the blueprint: namespace.

<?xml version="1.0" encoding="UTF-8"?><blueprint xmlns=http://www.osgi.org/xmlns/blueprint/v1.0.0 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd" default-activation="eager">

<reference id="exampleBeanService”/></blueprint>

25

Alternative: use bean-name

Exposing

Consuming

<bean id="exampleBean”class="com.gordondickens.demo.bean.internal.ExampleBeanImpl" />

<service id="exampleBeanService” ref="exampleBean"

interface="com.gordondickens.demo.bean.ExampleBean"/>

<reference id="exampleBean”interface="com.gordondickens.demo.bean.ExampleBean" />

26

Service DampingProxies automatically created services

◦ the actual service object may come and go at runtime

If service disappears, any proxies will wait for the service to re-appear.

This effect is known as damping.

27

Blueprint Bundle LifeWhen a bundle is started:

◦ builds application contexts as per the XML◦ creates proxies for specified services◦ publishes specified services to the registry

When a bundle is stopped:◦retracts any services◦closes bundle application context◦turns off damping of a service proxy◦proxy’s app context is being closed

28

Eclipse VirgoOSGi Server based on EquinoxProvides a PAR file archiveProvides PLAN file for grouped or

scoped bundlesProvides Import-Bundle: tag to import

all packages of a given BundleBundle Repository used to manage

artifacts required by other projectsCan be configured to automatically

download required bundles from a Maven repository

29

Virgo Dependency MgmtImport-Bundle:

◦Import-Package is fine grained◦Import-Bundle imports all Packages

from a BundleImport-Library:

◦Imports a Blueprint configured Library

◦A package of Bundles◦Example: the Spring 3.x Framework◦Can use wildcards

30

Virgo Fragments A bundle attached to a host bundle Treated as part of the host Can only add to the host

◦ Configuration◦ Classes◦ Resources

Can not have◦ activator◦ its own class loader

Designated in manifest.mf with Fragment-Host◦ Fragment-Host points to symbolic name of host

31

Virgo Feature - SlicesFragments for web appsUses manifest valuesIn myapp/web/template.mf

◦Slice-Host◦Slice-ContextPath

Slice-Host: com.gordondickenssolutions.runtime.webapp;version="[1.1.0,1.1.0]"

Slice-ContextPath: /myapp

32

Virgo Feature - PAR Files Platform Archive – like a jar/ear/war Multiple bundles packaged together Contains

◦ application name◦ version◦ symbolic name◦ description

The modules within are scoped together Cannot be shared accidentally by other apps The scope forms a boundary for automatic propagation of load

time weaving and bundle refresh The modules of a PAR have their exported packages imported

by the synthetic context bundle, used for thread context class loading

The PAR file is visible to management interfaces The PAR file can be undeployed and redeployed as a unit PARs physically contain the included artifacts

33

Virgo Feature - Plan FilesRecommended over PARsDeployment strategy for a Virgo applicationsSimilar to PARs describing a collection of

bundles to load together as an applicationSimple XML file

◦ defines a collection of artifacts

The syntax of a plan file◦ outer <plan/> tag defines a name and version, as

well as scoping and atomicity requirements◦ Inside the tag is at least one artifact tag with

type name version

34

Virgo Plan FilesDeploys the artifacts in the order

listedCan contain other plans (nesting)Easily share content between plansUpdate individual parts of a plan

without repackaging (re-JAR)Copy the bundles to the repositorythe $DMS_HOME/repository/usr

directory

35

Virgo Plan File Example<?xml version="1.0" encoding="UTF-8"?><plan name="greenpages.db.plan" version="2.4.3.RELEASE” scoped="false" atomic="true” xmlns=http://www.eclipse.org/virgo/schema/plan xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://www.eclipse.org/virgo/schema/plan http://www.eclipse.org/virgo/schema/plan/eclipse-virgo-plan.xsd"> <attributes> <attribute name="web.context.path" value="greenpages"/> </attributes>

<!-- Database properties file (minus file extension) to be deployed --> <artifact type="configuration" name="greenpages.db.config"/>

<artifact type="bundle" name="greenpages" version="[2.4, 2.5)"/> <artifact type="bundle" name="greenpages.db" version="[2.4, 2.5)"/> <artifact type="bundle" name="greenpages.jpa" version="[2.4, 2.5)"/>

<artifact type="bundle" name="greenpages.web" version="[2.4, 2.5)"> <property name="header:Web-ContextPath" value="${web.context.path}"/> </artifact></plan>

36

Connecting to OSGi Platformbin/startup.sh –shell

[or]ssh -p 2402 admin@localhost

37

Admin Consolehttp://localhost:8080/admin

38

Terminology ReviewBundleServiceExtenderFragmentDampingSlices

39

SummaryVirgo makes OSGi easier

◦Registers with the OSGi container

◦Exposes Beans as Services◦Consumes Services as Beans◦Simplfies MANIFEST.MF creation