Creating an OSGi bundle and deploying it to Eclipse Virgo

The purpose of this article is to explain how to create a small OSGi application by example. For this example we use the Virgo OSGi server.

Installation

The installation of the OSGi server (Virgo) is very simple. You only need to download the installation file and unzip it in the directory you want. You can download Virgo at http://www.eclipse.org/virgo/download.
Choose to download the "Virgo Server for Apache Tomcat".

Starting Virgo

To run Virgo go to the bin directory and run the startup.sh or startup.bat.
This will start the Virgo server. After everything is started you can access the web console via http://localhost:8080

Creating an OSGi application

Lets create an OSGi application starting with an maven archetype:
 

mvn archetype:generate -B -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.0 -DgroupId=javacodingspot -DartifactId=osgi-server -Dversion=1.0 -Dpackage=nl.javacodingspot.osgi.server

Each jar needs to be converted to an OSGI compatible jar (an OSGI bundle). To do this, we need to change the manifest file. The manifest file needs to have the correct parameters set in order for OSGi to recognise it as a bundle.You can create the manifest file manually, but that is a lot of work and will probably result in errors. One of the tools you can use to generate the manifest file is the eclipse Bundlor tool, which also is there as a maven plug-in.

Creating the Manifest with Bundlor

We will let the Bundlor maven plug-in generate our manifest. Then we use the maven-jar-plugin to add the manifest.mf to our jar. To do this we have to add the plug-ins to the maven build in the pom.xml of the projects.

<project ...>
...
    <plugin>
        <groupId>org.eclipse.virgo.bundlor</groupId>
        <artifactId>org.eclipse.virgo.bundlor.maven</artifactId>
        <version>1.1.2.RELEASE</version>
        <executions>
            <execution>
                <id>bundlor</id>
                <goals>
                    <goal>bundlor</goal>
                </goals>
                <configuration>
                    <manifestTemplate>
Bundle-ManifestVersion: 2
Bundle-Name: JCS OSGi Server
Bundle-SymbolicName: nl.javacodingspot.osgi.server
Bundle-Version: 1.0.0
                    </manifestTemplate>
                </configuration>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.3.1</version>
        <configuration>
            <archive>
                <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
            </archive>
        </configuration>
    </plugin>
...
</project>

and you should add some maven repository to either your settings.xml file or the pom.xml files:

pom example:

<project ...>
...
  <repositories>
    <repository>
      <id>eclipse.virgo.build.bundles.release</id>
      <name>Eclipse Virgo Build</name>
      <url>http://build.eclipse.org/rt/virgo/maven/bundles/release</url>
    </repository>
    <repository>
      <id>com.springsource.repository.bundles.external</id>
      <name>SpringSource Enterprise Bundle Repository - External Bundle Releases</name>
      <url>http://repository.springsource.com/maven/bundles/external</url>
    </repository>
  </repositories>
...
</project>

You now created an OSGi bundle that is deployable on an OSGi server like Virgo.

Deploying the bundles to Virgo

There are multiple ways to deploy a bundle to Virgo:

• Via the web console
• In the Pickup directory
• With a plan file

The web console

You can deploy a jar file with the use of the Virgo web console. This console can be reached at http://localhost:8080 when the server is started. You can login with the default username/password: admin/springsource. You need to upload your jar files in the right order to avoid dependencies issues. The console is easy but time consuming. An advantage is that you can upload new jars from other systems easily.

The pickup directory

The easiest way to deploy a jar file is to dump it in the pickup directory in the Virgo installation directory. You can drop, remove, or update a jar while virgo is running.
A problem with deploying in this way is that there is no way to control the order in which virgo starts the bundles. This can be a real problem if you have jars with dependencies to other jars in the pickup directory.

A plan file

A more controlled way to deploy your application to Virgo is to create a plan file. This is a simple xml configuration file which let you decide the exact jars and versions are available and started, and you can decide the order in which virgo needs to start the jars.

First you need to remove the jars from the pickup directory. The jars that are needed can be copied to the repository/usr directory. The plan file itself can then be deployed in the pickup directory.


Next thing to do is to create an OSGi service.