Presentation I gave on OSGi with Eclipse Virgo and OSGi Blueprint

1. Introduction to OSGi
& Eclipse Virgo
Gordon Dickens
@gdickens
linkedin.com/in/gordondickens
Blog: technophile.gordondickens.com
GitHub: github.com/gordonad
1

2. >OSGi Terminology
 OSGI container
 Bundle
 Service
 Spring Dynamic Modules
 Spring dm Server
2

3. OSGI Container
 A low-footprint engine that manages
OSGi components
 Can be embedded into applications to
provide modular components
 Three 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
3

4. The OSGi Bundle
 JAR with extra Config Info
◦ Classes and resources that deliver
functions to consumers
◦ Can “export” services & packages
◦ Can “import” services & packages
4

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
5

6. Sample META-
INF/MANIFEST.MF
Manifest-Version: 1.0
Export-Package: com.gordondickens.utils,org.osgi.framework”
Bundle-Name: Maven OSGi Demo – Services
Build-Jdk: 1.6.0
Bundle-Version: 1.0.0
Bundle-ManifestVersion: 2
Bundle-Activator: com.gordondickens.services.ServiceActivator
Bundle-SymbolicName: maven-osgi-demo-services
Import-Package: org.osgi.framework;version="1.3"
6

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
7

8. Dependencies
 Bundles 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
8

9. Bundle Lifecycle
9

10. What can you do with a
bundle?
 Bundles just expose
packages or services
Service
to be used Service
◦ Does not automatically
hide impl classes Service
◦ Package exporting
should only be for
utility packages
(plumbing).
Bundle
◦ You only want to
expose “services”
10

11. Services
 Register 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
11

12. Preparing the Manifest
 You 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
12

13. Bundlor
 Input: • Generates:
◦ jar
– manifest.mf
◦ template.mf
 Import-Template
jar
The BUNDLOR manifest.mf
template.mf
13

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
14

15. The Blueprint Extender
 Extender 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 contexts
 Replaces Bundle Activator
15

16. Template.mf
The Bundlor uses the template.mfto generate the OSGi required manifest.mffile
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.
16

17. Dependency Management
 If a Bundle requires another bundle
◦ Load the other bundle
◦ Damping - Suspends any threads
attempting to access the imported
packages
◦ Once loaded, threads are resumed
17

18. Using Blueprint
 Configuring your context
 The blueprint: namespace
 Exporting beans as OSGi Services
into Registry
 Importing beans from OSGi Registry
18

19. Configuring your Context
 Good practice:
◦ Separate Spring configuration from
Blueprint imports/exports
 bundle-context.xml
 bundle-context-osgi.xml
 Create2 context files in META-
INF/spring
◦ All *.xml files in this dir are
processed
19

20. Blueprint Services
 Blueprint enables services to be
published and consumed using
descriptions written in XML
 Eclipse Virgo supports Blueprint
 The XML descriptions reside in files
with extension .xml in the bundle’s
META-INF/spring sub-directory.
20

21. Spring DM Services
 To 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
21

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">
<serviceref="exampleBean"
interface="com.gordondickens.demo.bean.ExampleBean"/>
</blueprint>
22

23. Consuming the Service
 Use the blueprint: namespace:
◦ Service Beans
◦ Valid OSGi Service beans
 Can be injected into other Beans using
◦ XML injection
◦ annotation-driven injection
23

24. Example: Consuming an OSGi
Service
 Use 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>
24

25. Alternative: use bean-name
 Exposing
<bean id="exampleBean”
class="com.gordondickens.demo.bean.internal.ExampleBeanImpl" />
<service id="exampleBeanService”
ref="exampleBean"
interface="com.gordondickens.demo.bean.ExampleBean"/>
 Consuming
<reference id="exampleBean”
interface="com.gordondickens.demo.bean.ExampleBean" />
25

26. Service Damping
 Proxies 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.
26

27. Blueprint Bundle Life
 When 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
27

28. Eclipse Virgo
 OSGi Server based on Equinox
 Provides a PAR file archive
 Provides PLAN file for grouped or scoped
bundles
 Provides Import-Bundle: tag to import all
packages of a given Bundle
 Bundle Repository used to manage
artifacts required by other projects
 Can be configured to automatically
download required bundles from a Maven
repository
28

29. Virgo Dependency Mgmt
 Import-Bundle:
◦ Import-Package is fine grained
◦ Import-Bundle imports all Packages
from a Bundle
 Import-Library:
◦ Imports a Blueprint configured Library
◦ A package of Bundles
◦ Example: the Spring 3.x Framework
◦ Can use wildcards
29

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
30

31. Virgo Feature - Slices
 Fragments for web apps
 Uses manifest values
 In myapp/web/template.mf
◦ Slice-Host
◦ Slice-ContextPath
Slice-Host:
com.gordondickenssolutions.runtime.webapp;version="[1.1.0,1.1.0]"
Slice-ContextPath: /myapp
31

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
32

33. Virgo Feature -Plan Files
 Recommended over PARs
 Deployment strategy for a Virgo applications
 Similar to PARs describing a collection of
bundles to load together as an application
 Simple 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
33

34. Virgo Plan Files
 Deploys the artifacts in the order listed
 Can contain other plans (nesting)
 Easily share content between plans
 Update individual parts of a plan
without repackaging (re-JAR)
 Copy the bundles to the repository
 the $DMS_HOME/repository/usr
directory
34

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>
35

36. Connecting to OSGi Platform
 bin/startup.sh –shell
[or]
 ssh -p 2402 admin@localhost
36

37. Admin Console
 http://localhost:8080/admin
37

38. Terminology Review
 Bundle
 Service
 Extender
 Fragment
 Damping
 Slices
38

39. Summary
 Virgo makes OSGi easier
◦ Registers with the OSGi container
◦ Exposes Beans as Services
◦ Consumes Services as Beans
◦ Simplfies MANIFEST.MF creation
39