Getting Started Developing Applications

OSGi — Helloworld OSGi quickstart

This quickstart shows you how to create and deploy a simple OSGi Bundle.

Tip
What is OSGi?

OSGi is a new feature to JBoss Enterprise Application Platform 6. It provides standards-based modularity and micro-services as defined in the OSGi 4.2 Core Specifications. You can deploy OSGi bundles directly into the server.

For more information on OSGi and on how to develop OSGi bundles, see the OSGi 4.2 Core Specification and the link:http://www.osgi.org/javadoc/r4v42[OSGi 4.2 Core Javadoc.

More information on the OSGi component can be found on the JBoss OSGi project pages.

Switch to the quickstarts/helloworld-osgi directory and instruct Maven to build and deploy the application:

mvn package jboss-as:deploy

Now, you should see the OSGi subsystem start up, and the bundle deployed and started:

console

Tip

If you wish to undeploy the quickstart, or redeploy after making some changes, it’s pretty easy:

  • mvn jboss-as:deploy - deploy any changes to the application to the application server

  • mvn jboss-as:undeploy - undeploy the quickstart

The Helloworld OSGi quickstart in depth

The OSGi Bundle has one Java Source file, the Bundle Activator:

src/main/java/org/jboss/as/helloworld/osgi/Activator.java
public class Activator implements BundleActivator {
    public void start(BundleContext context) throws Exception {
        System.out.println("Hello World!!");
    }

    public void stop(BundleContext context) throws Exception {
        System.out.println("Goodbye World!!");
    }
}

The bundle activator is very simple, and just prints out a message when the bundle starts and stops - allowing you to verify that OSGi is working properly.

Now, let’s look at the pom.xml , where we create the bundle:

pom.xml
<?xml version="1.0"?>
<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">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.jboss.eap.quickstarts</groupId>
    <artifactId>jboss-helloworld-osgi</artifactId>
    <version>7.1.1.Final</version>
    <packaging>bundle</packaging>                                    (1)
    <name>JBoss EAP Quickstarts: Helloworld OSGi</name>
    <description>JBoss EAP Quickstarts: Helloworld OSGi</description>

    <url>http://jboss.org/jbossas/osgi</url>
    <licenses>
        <license>
            <name>Apache License, Version 2.0</name>
            <distribution>repo</distribution>
            <url>
                http://www.apache.org/licenses/LICENSE-2.0.html
            </url>
        </license>
    </licenses>

    <properties>
        <!-- Explicitly declaring the source encoding eliminates the
             following message: -->
        <!-- [WARNING] Using platform encoding (UTF-8 actually) to
             copy filtered resources, i.e. build is platform
             dependent! -->
        <project.build.sourceEncoding>
            UTF-8
        </project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.osgi</groupId>                              (2)
            <artifactId>org.osgi.core</artifactId>
            <version>4.2.0</version>
            <scope>provided</scope>                                  (3)
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <!-- This plugin takes care of packaging the
                     artifact as an OSGi Bundle -->
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>         (4)
                <version>2.3.4</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <!-- OSGi Manifest Metadata is specified
                             here -->
                        <!-- The Bundle SymbolicName is the same as
                             the artifact ID -->
                        <Bundle-SymbolicName>
                            ${project.artifactId}
                        </Bundle-SymbolicName>

                        <!-- Specify the Bundle activator, which is
                             invoked when the Bundle is started -->
                        <Bundle-Activator>
                            org.jboss.as.quickstarts.helloworld.osgi.Activator
                        </Bundle-Activator>

                        <!-- Automatically compute all the necessary
                             Import-Package statements -->
                        <Import-Package>*</Import-Package>

                        <!-- This bundle does not export any
                             packages -->
                        <Export-Package />

                        <!-- Packages that are not exported but need
                            to be included need to be listed as
                            Private-Package -->
                        <Private-Package>
                            org.jboss.as.quickstarts.helloworld.osgi
                        </Private-Package>
                    </instructions>
                </configuration>
            </plugin>

            <!-- JBoss AS plugin to deploy artifact -->
            <plugin>
                <groupId>org.jboss.as.plugins</groupId>              (5)
                <artifactId>jboss-as-maven-plugin</artifactId>
                <version>7.1.1.Final</version>
                <configuration>
                    <filename>
                        ${project.build.finalName}.jar
                    </filename>
                </configuration>
            </plugin>

            <!-- Compiler plugin enforces Java 1.6 compatibility
                 to remove unnecessary warnings about execution
                 environment in IDE -->
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.3.1</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>

        </plugins>
    </build>
</project>
  1. The packaging of the maven module is set to bundle . This instructs maven and the maven-bundle-plugin to create an OSGi bundle.

  2. Since the activator uses an OSGi interface, these are provided through the OSGi interfaces artifact.

  3. Use the provided scope for dependencies that are either provided by the OSGi framework (i.e. JBoss Enterprise Application Platform 6) itself or for dependencies that are provided through separate bundles.

  4. The maven-bundle-plugin is used to create a bundle. You can configure it create import and export statements, and to specify the activator in use. You can read more about the OSGi Bundle Maven Plugin on the Apache Felix site.

  5. We can use the jboss-as Maven plugin to deploy the bundle to the server as usual.

As you can see, using OSGi with JBoss Enterprise Application Platform 6 is pretty easy!

Creating a new OSGi bundle using Eclipse

Eclipse has built-in support for creating OSGi bundles. Eclipse is built on OSGi, therefore support for developing OSGi bundles inside Eclipse is quite extensive.

To quickly create an OSGi Bundle using Eclipse, follow these steps. In Eclipse do File New → Project → Plug-in Project:

new

Select as the Target Platform a Standard OSGi Framework and click Next >.

On the following page, you can specify the Bundle Symbolic Name, version, _Bundle Activator+ and some other details. You may use the defaults, or, for example, you could put the Activator in a different package, e.g. org.jboss.as.quickstarts.helloworld.osgi.Activator.

Click Next > again.

On the Templates page select the Hello OSGi Bundle template and click Finish:

Template

After clicking Finish, the Plug-In Development perspective will open with the Manifest Editor. The Manifest Editor facilitates editing of the OSGi Metadata, such as the Imported Packages in the Dependencies tab and Exported Packages on the Runtime tab:

Manifest

Click on the Activator link in the Manifest Editor to open the Bundle Activator in the Java Editor.

Activator

When you are finished making changes you can export your OSGi bundle so that it can be deployed directly. Click on File → Export → Deployable plug-ins and fragments:

Export

You have now created an OSGi Bundle, and the JAR can be found in the plugins directory of the location specified in the screen above. You can deploy it to the server using any of the standard deployment mechanisms described in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6.

Share the Knowledge

Find this guide useful?

Feedback

Find a bug in the guide? Something missing? You can fix it by [forking the repository](http://github.com/jboss-jdf/jboss-as-quickstart), making the correction and [sending a pull request](http://help.github.com/send-pull-requests). If you're just plain stuck, feel free to ask a question in the [user discussion forum](http://jboss.org/jdf/forums/jdf-users).

Recent Changelog

  • Nov 25, 2013: Bz1032836: remove as7 from helloworld-osgi code examples in the guide Sande Gilda
  • Nov 04, 2013: Modified headers to remove setext titles Vineet Reynolds
  • Nov 01, 2013: Removed colons from document title Vineet Reynolds
  • Nov 01, 2013: Remove jboss as 7 references from quickstarts Sande Gilda
  • Jan 24, 2013: Compatibility updates for asciidoctor Dan Allen
  • Sep 17, 2012: Fixing jdf-78 Jason Porter
  • Jul 19, 2012: Add author to the guide Pete Muir
  • Jul 10, 2012: Initial import of getting started developing applications guide Pete Muir

See full history »