software development | Steinar Bangs blogg

Apache Karaf is a good platform for deploying OSGi based applications. Karaf is also a good platform for testing and debugging these applications. This article describes how to test and debug OSGi bundles and OSGi applications with karaf and eclipse.

The basic flow of development, is:

Build the application with maven
Start karaf as your own user in a way that makes it listen for remote debug connections
Install the application from the karaf console
Connect eclipse to karaf for a remote debug session
Make karaf listen to updates to bundles with SNAPSHOT versions, and automatically load the updated bundles
Make a change in eclipse
Run a maven build of the project
Observe that the change appears in karaf or in the debugger

For more detail, read on.

Preparations

Do the following:

Install eclipse
1. Open a web browser on https://www.eclipse.org/downloads/ and download the installer for your system
2. Run the installer to the end, using defaults for everything
Install apache maven
1. On debian GNU/linux, just do
```
apt-get install maven
```

Download and unpack the binary karaf distribution. In bash on GNU/linux (or in git bash on Windows), do:

mkdir -p ~/karaf
cd ~/karaf/
wget http://apache.uib.no/karaf/4.1.4/apache-karaf-4.1.4.tar.gz
tar --strip-components=1 -xf apache-karaf-4.1.4.tar.gz

Clone and build the sample application

mkdir -p ~/workspaces/ws01
cd ~/workspaces/ws01/
git clone https://github.com/steinarb/hello-karaf-demo.git
cd ~/workspaces/ws01/hello-karaf-demo/
mvn clean install

Import the sample application into eclipse:
1. Start eclipse
2. Open the workspace at ~/workspaces/ws01
3. Import the existing maven project hello-karaf-demo into the workspace (File->Import… then select Maven->Existing Maven Projects and click the wizard through to the end)

Install the application into karaf

Open a command line window and start karaf with an argument that makes karaf listen for remote debug connections
```
cd ~/karaf/
bin/karaf debug
```

From the karaf console prompt:

Install the run-time requirements for the test application

feature:repo-add mvn:no.priv.bang.osgi.service.adapters/service-adapters-karaf/1.0.0/xml/features
feature:install adapter-for-osgi-logservice
feature:install pax-http-whiteboard

Install the sample application with the following commands

bundle:install mvn:no.priv.bang.demos/hello-karaf-demo/1.0.0-SNAPSHOT
bundle:start mvn:no.priv.bang.demos/hello-karaf-demo/1.0.0-SNAPSHOT

Open a web browser on the following URL http://localhost:8181/hello

Debug into the application running in karaf

Set up a remote debug connection in karaf
1. Open the menu Run->Debug Configurations…
2. In the debug configurations dialog:
  1. Select “Remote Java Application”
  2. Click the “New launch configuration”
  3. In the Name field, write
```
Remote karaf debug
```
  4. In the Port field, write
```
5005
```
  5. Select the “Source” tab
  6. Click the button “Add…”
  7. In the “Add Source” dialog:
    1. Select “Java Project”
    2. Click the button “OK”
    3. In the “Project Selection” dialog
      1. Click the checkbox of “hello-karaf-demo”
      2. Click the button “OK”
  8. Click the button “Debug”
Set a breakpoint in the code
1. Open the HelloServlet.java file (press Ctrl-Shift-t to open the “Open Type” dialog, type HelloServlet and select the HelloServlet class)
2. Go to line 60 (press Ctrl-l, then type 60, and press Enter), i.e. this line
```
            response.setStatus(200);
```
3. Press Ctrl-Shift-b to set a breakpoint on line 61
Reload the web page in the web browser
Observe that the debugger stops at the breakpoint
Press F8 to make the code continue to run

Make a modification in the code, picked up by karaf

1. In the karaf console, give the following command to make karaf listen in the local repository for new versions of bundles with SNAPSHOT version
```
bundle:watch *
```
2. Modify the code in eclipse
  1. In the HelloServlet.java file, change
```
    private static final String TITLE = "Hello world!";
    private static final String PARAGRAPH = "This is sent via PAX Web Whiteboard Extender.";
```
    to
```
    private static final String TITLE = "Hello karaf world!";
    private static final String PARAGRAPH = "Powered by Apache Karaf.";
```
  2. Save the HelloServlet.java file
3. Build the project with maven
  1. In eclipse, select the menu Run->Run Configurations…
  2. In the dialog Run Configurations:
    1. Select “Maven Build” in the list on the left
    2. Click the “New launch configuration” icon (top left in the dialog)
    3. In the “Name:” field, type:
```
mvn install hello-karaf-demo
```
    4. In the “Base directory” field, type:
```
${project_loc:hello-karaf-demo}
```
    5. In the “Goals” field, type:
```
install
```
    6. Click the button “Run”
4. Reload the web page in the web browser and observe that the change now is present

Installing with a karaf feature

In the installation example earlier in this article the runtime requirements of the sample application were first installed into karaf (pax-http-whiteboard and adapter-for-osgi-logservice).

It is possible to install this example application in a way that also pulls in the dependencies:

The first thing to do, is to remove the existing installation in karaf:
1. Stop karaf
```
logout
```
2. Remove the “data” subdirectory
```
rm -rf data
```
3. Start karaf
```
bin/karaf debug
```
Removing the data directory removes all state in karaf, and karaf is back to a fresh installation, this can be verfied by:
1. listing the bundles in the karaf console
```
bundle:list
```
2. Verifying that http://localhost:8181/hello results in a 404 Not Found
The first thing to do, is to add the feature repository for the hello world application. The feature repository is an XML file containing one or more “karaf features”. A karaf feature can be a list of bundles to load, and it can also contain references to other features. The feature file for the hello world application is attached to the maven bundle artifact and can be installed with the following command:
```
feature:repo-add mvn:no.priv.bang.demos/hello-karaf-demo/1.0.0-SNAPSHOT/xml/features
```
Note: This is the same karaf commando as the first command of the dependencies install. The pax-http-whiteboard feature is built-in to karaf and doesn’t require a feature repository install
Now the feature for the hello world application can be installed
```
feature:install hello-karaf
```
Verify that the feature install has pulled in dependencies
```
bundle:list
```
Verify that the application is running on http://localhost:8181/hello

Some things to try on your own:

Remove the data directory again and try installing the bundle without the dependencies and see what happens
Start karaf watching for bundle modifications in the local maven repository
List bundles on different levels with the bundle:list command with the threshold argument (hint: all karaf commands take the “–help” argument)
Try launching the “mvn install” for the bundle using eclipse hotkeys after modifying the java file and observe that karaf loads the rebuilt module

Steinar Bangs blogg

Tag Archives: software development

Develop OSGi applications using karaf