Creating an OSGi Bundle out of a Third Party Library for Using as WSO2 Product Dependency

WSO2 platform supports a modular based architecture where third party libraries which are used in WSO2 products are exposed into the environment as OSGi bundles. This blog post is about how to OSGify a third party library, to be used as a dependency inside WSO2 MB.

We have recently used 'Disruptor', a high performance inter-thread messaging library  as a dependency in WSO2 Message Broker for improving the performance by using disruptor based message writing operations into Cassandra storage. When doing this it is first needed to create an OSGi bundle out of 'Disruptor' library, so it can be referred in the runtime when Message Broker is running.

As common to all OSGi bundle generations, first you need to have a manifest.mf file which describes the bundle information, version info, which packages needed to be imported/exported etc. However as it is not easy to write this file correctly by hand we use maven-bundle-plugin in order to get this done. This process is common to any third party dependency and you can follow the same process in building an osgi bundle for any of them.

1. First let's create a directory named 'disruptor' inside <WSO2_Carbon_Source>/platform/dependencies/orbit/ directory. As we have used Disruptor 2.10.4 version i created a new package called 2.10.4-wso2v1 inside disruptor directory. (This is the common notation across the platform <LibraryVersion>-wso2v<VersionNumber>when naming the versions of the dependencies.)

2. Add a new maven build file (pom.xml) inside package 2.10.4-wso2v1.

3. Now let's add the required details which needs to generate the OSGi bundle into this file. This pom file can be used as a sample template by replacing the required entries when adding another dependency.

<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/maven-v4_0_0.xsd">

<parent>
   <groupId>org.wso2.carbon</groupId>
   <artifactId>carbon-dependents</artifactId>
   <version>4.1.0</version>
   <relativePath>../../../pom.xml</relativePath>
</parent>

<modelVersion>4.0.0</modelVersion>
<groupId>com.googlecode.disruptor.wso2</groupId>
<artifactId>disruptor</artifactId>
<packaging>bundle</packaging>
<name>WSO2 Carbon - Orbit - disruptor</name>
<version>2.10.4-wso2v1</version>
<description>This bundle exports packages from disruptor jar files</description>
<url>http://wso2.org</url>

<dependencies>
   <dependency>
      <groupId>com.googlecode.disruptor</groupId>
      <artifactId>disruptor</artifactId>
      <version>2.10.4</version>
      <optional>true</optional>
   </dependency>
</dependencies>

<build>
     <plugins>
            <plugin>
                 <groupId>org.apache.felix</groupId>
                 <artifactId>maven-bundle-plugin</artifactId>
                 <version>1.4.0</version>
                 <extensions>true</extensions>
                 <configuration>
                      <instructions>
                        <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                        <Bundle-Name>${project.artifactId}</Bundle-Name>
                        <Export-Package>
                                com.lmax.disruptor.*;version=2.10.4,
                         </Export-Package>
                        <Import-Package>
                                !sun.misc,
                                *
                        </Import-Package>
                      </instructions>
                </configuration>
            </plugin>
     </plugins>
</build>

<!--<repositories>
    <repository>
       <snapshots>
          <enabled>true</enabled>
          <updatePolicy>daily</updatePolicy>
          <checksumPolicy>ignore</checksumPolicy>
    </snapshots>
    <id>wso2-maven2-snapshot-repository</id>
    <name>WSO2 Maven2 Snapshot Repository</name>
    <url>http://dist.wso2.org/snapshots/maven2/</url>
    <layout>default</layout>
  </repository>
</repositories>-->

<properties>
     <disruptor.build.version>2.10.4</disruptor.build.version>
     <disruptor.version>${disruptor.build.version}-wso2v1</disruptor.version>
 <disruptor.orbit.version>${disruptor.build.version}.wso2v1</disruptor.orbit.version>
</properties>
</project>

Let's go trough the important entries in the file.

<dependencies>
<dependency>
<groupId>com.googlecode.disruptor</groupId>
<artifactId>disruptor</artifactId>
<version>2.10.4</version>
<optional>true</optional>
</dependency>
</dependencies>

As we are using external library in the OSGi bundle we need to add this as a maven dependency entry for the bundle. You can find maven dependency entries of lot of libraries in here.

<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>1.4.0</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
<Bundle-Name>${project.artifactId}</Bundle-Name>
<Export-Package>
             com.lmax.disruptor.*;version=2.10.4,
</Export-Package>
<Import-Package>
             !sun.misc,
             *
</Import-Package>
</instructions>
</configuration>
</plugin>
</plugins>
</build>

This is how we use maven-bundle-plugin to generate the disruptor osgi bundle. The Export-Package, Import-Package and DynamicImport-Package tags are used to control the exposure of certain packages to other bundles. With <Export-Package> tag it will find the defined project classes or dependencies, and they will be copied to the osgi bundle. With using <Import-Package> here, we can import the extra classes that have been referred from our osgi bundle. By keeping * as the value here by default it imports all the reference classes that needs for OSGi bundle generation. However when using default value here for 'disruptor bundle' i encountered the following error.

org.osgi.framework.BundleException: The bundle could not be resolved. Reason: Missing Constraint: Import-Package: sun.misc; version="0.0.0"

So I added the entry '!sun.misc' to resolve this issue and it seems as the sun.misc package is already there to be referred by the osgi framework, we need to tell that it is not needed to explicitly import it in this case. This is a 'Disruptor' bundle specific entry and you don't have to add the same configuration in each bundle you create. However if the bundle's classes use sun.misc package, this setting might be useful in resolving similar errors.


4. That's it! Save the pom file and build it with maven ( WSO2 projects use Maven3). You will see that in the <WSO2_Carbon_Source>/platform/dependencies/orbit/disruptor/2.10.4-wso2v1/target folder the newly created osgi bundle 'disruptor-2.10.4-wso2v1.jar' is present.

If you see the manifest.mf file of the new bundle it will be as follows.

Manifest-Version: 1.0
Export-Package: com.lmax.disruptor.collections;version="2.10.4",com.lm
ax.disruptor;uses:="com.lmax.disruptor.util";version="2.10.4",com.lma
x.disruptor.dsl;uses:="com.lmax.disruptor,com.lmax.disruptor.util";ve
rsion="2.10.4",com.lmax.disruptor.util;uses:="com.lmax.disruptor";ver
sion="2.10.4"
Ignore-Package: sun.misc
Built-By: <your_host_name>
Tool: Bnd-0.0.238
Bundle-Name: disruptor
Created-By: Apache Maven Bundle Plugin
Bundle-Version: 2.10.4.wso2v1
Build-Jdk: 1.6.0_30
Bnd-LastModified: 1373904351577
Bundle-ManifestVersion: 2
Bundle-Description: This bundle exports packages from disruptor jar fi
les
Bundle-SymbolicName: disruptor
Import-Package: com.lmax.disruptor;version="2.10.4",com.lmax.disruptor
.collections;version="2.10.4",com.lmax.disruptor.dsl;version="2.10.4"
,com.lmax.disruptor.util;version="2.10.4"


To know more about creating OSGi bundles with maven-bundle-plugin, you can read the following article in WSO2 Library.


[1]. http://wso2.com/library/tutorials/develop-osgi-bundles-using-maven-bundle-plugin

Remote debugging maven jetty with IntelliJ Idea in Ubuntu 11.10

Jetty web server is an open source http server/client container which can be used to run and test webapps.  Jetty server provides a plugin to integrate with apache maven and it can be used to run a webapp in a maven project. To do this we need to add jetty-maven-plugin into our <plugins> section by adding it into webapp pom.xml file.

<plugin>
            <groupId>org.mortbay.jetty</groupId>
            <artifactId>maven-jetty-plugin</artifactId>
            <version>6.1.10</version>
            <configuration>
               <webXml>${project.build.directory}/jetty/WEB-INF/web.xml</webXml>
               <webAppConfig>
                  <contextPath>/${webapp.name}</contextPath>
                  <!--enable reloading static resources -->
                  <overrideDescriptor>src/test/resources/override-web.xml</overrideDescriptor>
               </webAppConfig>
               <scanIntervalSeconds>10</scanIntervalSeconds>
            </configuration>
         </plugin>


Now add the following Maven Options line into your .bashrc file.

For JDK 1.3 or above :

export MAVEN_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000"

For below JDK 1.3:

export MAVEN_OPTS="-Xnoagent -Djava.compiler=NONE -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000"

Goto the webapp folder from terminal and enter,

 mvn jetty:run

Jetty server will start on debug mode and will listen on port 8000 now. The following info will be appeared in terminal.

Goto IntelliJ Idea project and create a remote debug confiruation giving following parameters. (to do this follow the path Run --> Edit Configurations. Click on the + button followed by Remote and you will see remote configuration window appears)


Host = localhost
Port = 8000

Run the remote debug and it will also listen on port 8000 now.