Prev Next

Quick Start


In this tutorial we’ll first run, and then re-create and re-run, a simple OSGi Microservice.

Build and Run

We start by first downloading, building and running the enRoute quick start example. In addition to demonstrating the simple application this will also confirm that your local environment meets the required prerequisites.

Download the enroute examples from GitHub and change directory into examples/quickstart.

Building the example

Build the Application with the following command:

$ mvn verify

Running the example

We now have a runnable artifact which can be started with the command:

$ java -jar app/target/app.jar

To test that the application is running visit the quickstart application URL for a friendly greeting,


or if minimalism is more your thing, the raw REST endpoint http://localhost:8080/rest/upper/lower.

When you want to terminate the application press Ctrl+C.

Recreating Quick Start

We’ll now recreate the quick start example locally as though it were your own greenfield OSGi project.

It is assumed that you have the required environment installed on your laptop and have created the settings.xml necessary if you are using SNAPSHOT archetypes.

Project Setup

First issue the command to create the project template:

$ mvn -s settings.xml archetype:generate -DarchetypeGroupId=org.osgi.enroute.archetype -DarchetypeArtifactId=project -DarchetypeVersion=7.0.0-SNAPSHOT

Fillng the project details with appropriate values:

Define value for property 'groupId': org.osgi.enroute.examples.quickstart
Define value for property 'artifactId': quickstart
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' org.osgi.enroute.examples: :
Confirm properties configuration:
groupId: com.acme.example
artifactId: quickstart
version: 1.0-SNAPSHOT
package: com.acme.example
Y: : 

If you’re using an IDE then this would be a good time to import the generated maven projects.

Implementing the Microservice

Having created the project skeleton, edit quickstart/impl/src/main/java/org/osgi/enroute/examples/quickstart/rest/


import org.osgi.service.component.annotations.Component;

public class ComponentImpl {
    //TODO add an implementation

and add the following implementation details



import org.osgi.service.component.annotations.Component;
import org.osgi.service.http.whiteboard.propertytypes.HttpWhiteboardResource;
import org.osgi.service.jaxrs.whiteboard.propertytypes.JaxrsResource;

@HttpWhiteboardResource(pattern="/quickstart/*", prefix="static")
public class Upper {
    public String toUpper(@PathParam("param") String param) {
        return param.toUpperCase();

and then save the file.

The important modifications include:

  • A JAX-RS resource method implementation, replacing the the TODO section.
  • The @Component is modified to register this component as an OSGi service.
  • The @JaxrsResource annotation is used to mark this as a JAX-RS whiteboard resource.
  • Remember to change the name of the component from to

Building the Implementation

It’s now time to build the implementation project.

From the quickstart/impl project we now build the impl bundle.

$ mvn install

Here, we use the install goal to make sure that the built artifact is available to other projects in later steps.

If the install fails, continue to the next stage - resolve - then repeate mvn install

When using Bndtools your IDE will be incrementally rebuilding your projects every time that you save, so there’s no need to run a build. You can also run a build manually.

Right click the quickstart module in the left pane, and select Run As -> Maven

Modularity and complexity

Enter package as the goal and click Run

Resolving the Application

Before generating the runtime dependency information used by the OSGi framework take a look at the file quickstart\app\app.bndrun

index: target/index.xml

-standalone: ${index}

-runrequires: osgi.identity;filter:='(osgi.identity=org.osgi.enroute.examples.quickstart.impl)'
-runfw: org.apache.felix.framework
-runee: JavaSE-1.8

As shown, the bndrun contains a runrequires statement that specifies a capability; i.e. the implementation for quickstart. However, no runbundles a currently listed; i.e. the actual bundles needed at runtime to create quickstart.

The runbundles are automatically calculated for us via the process of resolving.

From the quickstart/app project we now resolve the application using the bnd-resolver-maven-plugin

$ mvn bnd-resolver:resolve

In the app maven module, open the app.bndrun to display the Bndtools Resolve screen. Here we can see that the implementation bundle is added to the run requirements.

Click the Resolve button…

Modularity and complexity

Now click Finish button…

Modularity and complexity

If you look again at the app.bndrun file you will now see that our rest service implementation org.osgi.enroute.examples.quickstart.impl, OSGi Declarative Services implementation org.apache.felix.scr, and a number of other bundles required at runtime are now listed by runbundles.

index: target/index.xml

-standalone: ${index}

-runrequires: osgi.identity;filter:='(osgi.identity=org.osgi.enroute.examples.quickstart.impl)'
-runfw: org.apache.felix.framework
-runee: JavaSE-1.8
-runbundles: \

Running the application

We now create a runnable application JAR.

Note that in this version of quickstart only the REST endpoint will be available.

Now that the initial development is done we’re ready to build and package the whole application by running the following command in the project root.

$ mvn package

Your version of quickstart may now be started as described above; the REST endpoint at http://localhost:8080/rest/upper/lower.

In the app maven module, open the app.bndrun to display the Bndtools Resolve screen. Select the Run OSGi button

Modularity and complexity

See the results in the console screen.

Modularity and complexity

With the project running, navigate to http://localhost:8080/rest/upper/lower and check the results

Modularity and complexity

If you want to get hold of the runnable application jar then right click the quickstart module in the left pane, and select Run As -> Maven

Modularity and complexity

Enter package as the goal and click Run

Modularity and complexity

Wait for maven to finish the generation.

Modularity and complexity

The runnable jar file created will be app/target/app.jar, and may be started as described above; the REST endpoint at http://localhost:8080/rest/upper/lower.