SyntaxHighlighter JS

2015-10-04

OSGi Tutorial: Make Classes and Interfaces public

What you will do:
  • Create an OSGi bundle that exports classes and interfaces
What you will learn:
  • What is an OSGi bundle
  • How to create an OSGi bundle using maven-bundle-plugin
  • How to install an OSGi bundle
  • How to expose classes and interfaces so other bundles can use it
  • Learn to use Export-Package in MANIFEST.MF
Code at: https://github.com/juttayaya/osgi/tree/master/api
This code is primarily tested on JBoss Fuse. ServiceMix and Karaf 3 and 4 are also supported.

An OSGi bundle is just a JAR file with custom entries in the META-INF/MANIFEST.MF file.

For this example, we want to make the Java interface com.jirawat.osgi.api.Echo and Java class com.jirawat.osgi.exception.EchoException public so that it can be reused. The end result is a JAR file with Echo and EchoException in it, just like you would normally package any Java classes in a JAR file.  The OSGi difference is that this JAR file contains an entry in META-INF/MANIFEST.MF called Export-Package.  As the name suggests, the Export-Package entry tells OSGi that classes in this Java package are public.

Step 1: Configure maven-bundle-plugin to export public packages
Configure maven-bundle-plugin to specify which Java package to make public by adding it to the Export-Package entries.

Step 2: Configure pom.xml for bundle packaging
Set maven-bundle-plugin extensions to true. Then add bundle as the packaging option

The pom.xml should look like this
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.jirawat.osgi</groupId>
    <artifactId>api</artifactId>
    <version>1.0.0</version>
    <packaging>bundle</packaging>
    <name>jirawat.com :: tutorial :: ${project.artifactId} Bundle</name>
    <description>Tutorial Bundle for ${project.artifactId}</description>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>3.0.0</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName>
                        <Export-Package>
                            com.jirawat.osgi.api,
                            com.jirawat.osgi.exception
                        </Export-Package>
                        <Import-Package>*</Import-Package>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Step 3: Build it
mvn clean package

This produces a JAR file with the Java classes and interfaces and a META-INF/MANIFEST.MF .  Notice the Export-Package entry exports the classes in the com.jirawat.osgi.api and com.jirawat.osgi.exception as public and reusable by other bundles. The MANIFEST.MF looks like

Manifest-Version: 1.0
Bnd-LastModified: 1443617839644
Build-Jdk: 1.7.0_45
Built-By: juttayaya
Bundle-Description: Tutorial Bundle for api
Bundle-ManifestVersion: 2
Bundle-Name: jirawat.com :: tutorial :: api Bundle
Bundle-SymbolicName: com.jirawat.osgi.api
Bundle-Version: 1.0.0
Created-By: Apache Maven Bundle Plugin
Export-Package: com.jirawat.osgi.api;version="1.0.0",com.jirawat.osgi.exception;version="1.0.0"
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.5))"
Tool: Bnd-3.0.0.201509101326

Step 4: Install it
Put the JAR file from step 3 in any directory and use the osgi:install JBoss Fuse command to install it

For example:
osgi:install -s file:/usr/local/osgi/api-1.0.0.jar

Note for ServiceMix and Karaf 3 and 4, use the bundle:install command

bundle:install -s file:/usr/local/osgi/api-1.0.0.jar

The osgi:list command shows the bundle installed. (bundle:list for ServiceMix and Karaf)

osgi:list

[ 268] [Active     ] [            ] [       ] [   80] jirawat.com :: tutorial :: api Bundle (1.0.0)