Beginning Karaf

Few weeks ago I started playing with the Apache Karaf application server. I already had some experience with OSGi containers, namely Eclipse Virgo as part of my regular job and I wanted to see what else is out there. To quickly outline the major differences between the servers, Virgo is using Equinox OSGi implementation provided by Eclipse (and powering the IDE of the same name) while Karaf is a subproject of Apache Felix, another major OSGi implementation. Karaf can use both Felix and Equinox but by default uses the former. Both application servers support web application bundles (the OSGi equivalent of WARs) and other enterprise features.

Getting acquainted with Karaf, I came to appreciate its tooling the most – there is a Maven plugin that makes the creation and maintenance of OSGi bundles a walk in the park. Still the tooling documentation is a bit lacking and having lost around three weeks with the project, cross-checking tutorials, official documentation, mailing threads and Karaf’s codebase I decided that it would be beneficial to have my sample project as a blueprint (pun intended) for other people interested in developing Karaf-based applications.

The sample project demonstrates the following OSGi / Karaf features:

Maven bundle packaging.
Maven kar packaging.
Maven karaf-assembly packaging.
Vanilla OSGi bundles.
Blueprint-wired bundles.
Web bundles.
Preparing a Karaf archive a.k.a. a KAR.
Building a customized Karaf distribution.

Project Overview

The project has been uploaded under https://github.com/tonyganchev/blog/tree/master/karaf. The project consists of two vanilla OSGi bundles – karaf-bundle-a and karaf-bundle-b to demonstrate how to consume the service exposed from one bundle in another bundle. Then there is a blueprint-based bundle – karaf-bundle-c – that consumes the same service as bundle-b but does so using blueprint declarations instead of hard-coding the service resolution within the bundle activator. karaf-wab demonstrates how to write a web application bundle that has some static content and a single servlet.

Apart from the functional modules, there are two modules that deal with how the example is delivered. First of all is karaf-kar providing a complete archive with all aforementioned bundles consolidated into a Karaf feature and wrapped in a single archive and ready to be deployed in any Karaf distributions that meets the feature’s prerequisites. This is made even easier with karaf-assembly which packages a full Karaf distribution that runs the project’s feature on startup.

All projects except karaf-wab were created using the Karaf Maven archetypes as described in Karaf’s developers guide. Note that the guide does not explain the org.apache.karaf.archetypes:karaf-assembly-archetype but you can see it is available by running:

mvn archetype:generate -Dfilter=karaf

Vanilla OSGi Bundles

Let’s look at the POM for such a bundle – for example karaf-bundle-a/pom.xml:


<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
...
	<artifactId>karaf-bundle-a</artifactId>
	<packaging>bundle</packaging>
	<dependencies>
		<dependency>
			<groupId>org.osgi</groupId>
			<artifactId>org.osgi.core</artifactId>
			<scope>provided</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
				<configuration>
					<instructions>
						<Bundle-Activator>com.tonyganchev.blog.karaf.a.Activator</Bundle-Activator>
						<Export-Package>com.tonyganchev.blog.karaf.a*;version=${project.version}</Export-Package>
						<Import-Package>*</Import-Package>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Few important things to note. First, there is the packaging (line 4) – bundle. It is provided by the karaf-maven-plugin defined in the root POM:

	<build>
	...
		<pluginManagement>
		...
			<plugins>
				...
				<plugin>
					<groupId>org.apache.karaf.tooling</groupId>
					<artifactId>karaf-maven-plugin</artifactId>
					<version>${karaf.version}</version>
					<extensions>true</extensions>
				</plugin>
				...

The other interesting piece of configuration is the invocation of the Felix maven bundle plugin which is a maven interface to the bnd tool. It is in charge of generating a proper OSGi META/MANIFEST.MF for the bundle. The instructions shown tell bnd what is the bundle activator (i.e. the class that will act on events such as bundle start/stop), What packages to allow for export (namely everything under com.tonyganchev.blog.karaf.a using the project’s version as the package version) and what to import (everything from the classpath).

The resulting META/MANIFEST.MF file looks like this:

Manifest-Version: 1.0
Bnd-LastModified: 1452520995636
Build-Jdk: 1.8.0_25
Built-By: tony
Bundle-Activator: com.tonyganchev.blog.karaf.a.Activator
Bundle-DocURL: http://www.tonyganchev.com/
Bundle-ManifestVersion: 2
Bundle-Name: karaf-bundle-a
Bundle-SymbolicName: karaf-bundle-a
Bundle-Vendor: Tony Ganchev
Bundle-Version: 1.0.0.SNAPSHOT
Created-By: Apache Maven Bundle Plugin
Export-Package: com.tonyganchev.blog.karaf.a;version="1.0.0.SNAPSHOT";uses:="org.osgi.framework",
 com.tonyganchev.blog.karaf.a.impl;version="1.0.0.SNAPSHOT";uses:="com.tonyganchev.blog.karaf.a"
Import-Package: com.tonyganchev.blog.karaf.a;version="[1.0,2)",
 com.tonyganchev.blog.karaf.a.impl;version="[1.0,2)",
 org.osgi.framework;version="[1.8,2)"
Private-Package: com.tonyganchev.blog.karaf.a,
 com.tonyganchev.blog.karaf.a.impl
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.7))"
Tool: Bnd-3.0.0.201509101326

The highlighted lines are the result from the instructions discussed above. All other headers get generated based on instructions specified for the bundle plugin in the plugin management section of the root POM.

karaf-bundle-a exposes a single service for consumption by other bundles through the GreetingService interface. Service registration is done in the bundle activator:

package com.tonyganchev.blog.karaf.a;

import java.util.Hashtable;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;

import com.tonyganchev.blog.karaf.a.impl.GreetingServiceImpl;

public class Activator implements BundleActivator {
	@Override
	public void start(final BundleContext context) {
		System.out.println("A: Starting the bundle");
		serviceRegistration = context
				.registerService(GreetingService.class, new GreetingServiceImpl(), new Hashtable<String, String>());
	}

	@Override
	public void stop(final BundleContext context) {
		System.out.println("A: Stopping the bundle");
		serviceRegistration.unregister();
	}

	private ServiceRegistration<GreetingService> serviceRegistration;

}

Now let’s take a look at the OSGi bundles consuming this service. Let’s start with karaf-bundle-b. It’s pom.xml looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
...
	<artifactId>karaf-bundle-b</artifactId>
	<packaging>bundle</packaging>
	<dependencies>
		<dependency>
			<groupId>org.osgi</groupId>
			<artifactId>org.osgi.core</artifactId>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>com.tonyganchev.blog</groupId>
			<artifactId>karaf-bundle-a</artifactId>
			<version>${project.version}</version>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
				<configuration>
					<instructions>
						<Bundle-Activator>com.tonyganchev.blog.karaf.b.Activator</Bundle-Activator>
						<Export-Package>com.tonyganchev.blog.karaf.b*;version=${project.version}</Export-Package>
						<Import-Package>*</Import-Package>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

It is essentially the same as bundle-a’s but it also adds a compile-time dependency to bundle-a. On starting bundle-b it’s activator seeks a reference to an implementation of GreetingService and calls its greet() method:

package com.tonyganchev.blog.karaf.b;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;

import com.tonyganchev.blog.karaf.a.GreetingService;

public class Activator implements BundleActivator {
	@Override
	public void start(final BundleContext context) {
		System.out.println("B: Starting the bundle");
		greetingServiceRef = context.getServiceReference(GreetingService.class);
		context.getService(greetingServiceRef).greet("Bundle B started!");
	}

	@Override
	public void stop(final BundleContext context) {
		System.out.println("B: Stopping the bundle");
		context.ungetService(greetingServiceRef);
	}

	private ServiceReference<GreetingService> greetingServiceRef;
}

Blueprint OSGi Bundles

Now let’s see how the same service can be consumed by a blueprint bundle. This is what karaf-bundle-c is for. The pom.xml looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<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/xsd/maven-4.0.0.xsd">
...
	<artifactId>karaf-bundle-c</artifactId>
	<packaging>bundle</packaging>
	<dependencies>
		<dependency>
			<groupId>com.tonyganchev.blog</groupId>
			<artifactId>karaf-bundle-a</artifactId>
			<version>${project.version}</version>
		</dependency>
		<dependency>
			<groupId>org.osgi</groupId>
			<artifactId>org.osgi.core</artifactId>
			<scope>provided</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
				<configuration>
					<instructions>
						<Bundle-Activator>com.tonyganchev.blog.karaf.c.Activator</Bundle-Activator>
						<Export-Package>com.tonyganchev.blog.karaf.c*;version=${project.version}</Export-Package>
						<Import-Package>*</Import-Package>
						<_removeheaders>Import-Service,Export-Service</_removeheaders>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Again, nothing particularly interesting apart from the highlighted line. The _removeheaders instruction commands bnd to strip some of the generated MANIFEST.MF headers. Why is it needed? If not added, bnd tends to generate an Import-Service entry for the GreetingService. Unfortunately this fails bundle’s startup since no other bundle exports this service (i.e. there is no corresponding Export-Service entry in karaf-bunle-a). Alternative solution is to add the missing entry by hand (bnd cannot auto-generate it as we register the service in code in bundle-a’s activator) but the OSGi Alliance recommends that Import/Export-Service should not be used.

The consumers are wired trough the blueprint configuration:

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" ...
	default-activation="eager">
	<reference id="greetingService" interface="com.tonyganchev.blog.karaf.a.GreetingService" />
	<bean id="greetingSender" class="com.tonyganchev.blog.karaf.c.impl.GreetingSenderImpl">
		<argument ref="greetingService" />
	</bean>
...
</blueprint>

Web Application Bundles

I went through a lot of different samples to try and run the cleanest possible WAB and finally settled on the way it is done in the following example. Essentially you can go through the basic org.apache.karaf.archetypes:karaf-bundle-archetype maven archetype and proceed by adding further instructions to the bundle plugin as shown in karaf-wab/pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
...
	<artifactId>karaf-wab</artifactId>
	<packaging>bundle</packaging>
	<dependencies>
		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>javax.servlet-api</artifactId>
			<scope>provided</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
				<extensions>true</extensions>
				<configuration>
					<instructions>
						<Import-Package>*</Import-Package>
						<Web-ContextPath>wab-test</Web-ContextPath>
						<Webapp-Context>wab-test</Webapp-Context>
						<_wab>src/main/webapp</_wab>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

You need to specify the web context path for the bundle. _wab instruction essentially tells bnd that the bundle is a web one and where it web resources are to be found. The resulting MANIFEST.MF looks like this:

Manifest-Version: 1.0
Bnd-LastModified: 1452687537092
Build-Jdk: 1.8.0_45
Built-By: tony
Bundle-ClassPath: WEB-INF/classes
Bundle-DocURL: http://www.tonyganchev.com/
Bundle-ManifestVersion: 2
Bundle-Name: karaf-wab
Bundle-SymbolicName: karaf-wab
Bundle-Vendor: Tony Ganchev
Bundle-Version: 1.0.0.SNAPSHOT
Created-By: Apache Maven Bundle Plugin
Export-Package: com.tonyganchev.blog.karaf.wab;uses:="javax.servlet,javax.servlet.http";version="1.0.0.SNAPSHOT"
Import-Package: javax.servlet;version="[3.1,4)",javax.servlet.http;version="[3.1,4)"
Private-Package: com.tonyganchev.blog.karaf.wab
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.7))"
Tool: Bnd-3.0.0.201509101326
Web-ContextPath: wab-test
Webapp-Context: wab-test

A single servlet named test is defined. it will serve GET requests to http://localhost:8181/wab-test/test.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="3.1">
	<servlet>
		<servlet-name>test</servlet-name>
		<servlet-class>com.tonyganchev.blog.karaf.wab.DummyServlet</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>test</servlet-name>
		<url-pattern>/test</url-pattern>
	</servlet-mapping>
</web-app>

The actual servlet is a trivial affair:

...
public class DummyServlet extends HttpServlet {
	@Override
	public void doGet(final HttpServletRequest request, final HttpServletResponse response)
			throws ServletException, IOException {
		response.getOutputStream().println("The servlet works as expected.");
	}
...
}

Karaf Archive

All Karaf applications are defined by means of features. Features are defined in feature repositories – simple XML manifests – and list all the bundles comprising the application, its configuration, the capabilities provided by the application and all its dependencies i.e. other features or bundles. All of these elements needs to be discovered / indexed by the Karaf/Felix resolver. This means that before installing the feature, all of its bundles need to be resolved as well. For ease of distribution, Karaf introduces the notion of Karaf Archive or KAR.

Each KAR is a zip file similar to a JAR with a custom layout. It comprises of all feature repositories and a repository of all bundles installed by the feature. You can use the kar packaging to define a maven project building a KAR. Here’s the karaf-kar/pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
...
	<artifactId>karaf-kar</artifactId>
	<packaging>kar</packaging>
	<dependencies>
		<dependency>
			<groupId>com.tonyganchev.blog</groupId>
			<artifactId>karaf-bundle-a</artifactId>
			<version>${project.version}</version>
			<type>bundle</type>
		</dependency>
		<dependency>
			<groupId>com.tonyganchev.blog</groupId>
			<artifactId>karaf-bundle-b</artifactId>
			<version>${project.version}</version>
			<type>bundle</type>
		</dependency>
		<dependency>
			<groupId>com.tonyganchev.blog</groupId>
			<artifactId>karaf-bundle-c</artifactId>
			<version>${project.version}</version>
			<type>bundle</type>
		</dependency>
		<dependency>
			<groupId>com.tonyganchev.blog</groupId>
			<artifactId>karaf-wab</artifactId>
			<version>${project.version}</version>
			<type>bundle</type>
		</dependency>
	</dependencies>
</project>

All bundles we want to include in the KAR are compile-time dependencies to the karaf-kar project.

The sole source of the project is a single feature repository definition – karaf-kar/src/main/feature/feature.xml:

<?xml version="1.0" encoding="UTF-8"?>
<features name="${project.artifactId}-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.3.0">
	<repository>mvn:org.apache.karaf.features/standard/${karaf.version}/xml/features</repository>
	<feature name="${project.artifactId}" description="${project.name}" version="${project.version}">
		<details>Sample feature details...</details>
		<feature version="${karaf.feature.version}" prerequisite="false" dependency="false">aries-blueprint</feature>
		<feature version="${karaf.feature.version}" prerequisite="false" dependency="false">war</feature>
	</feature>
</features>

Note: looks like highlighted line 3 is no longer necessary for Karaf plugin in 4.0.5-SNAPSHOT. Previous to that the karaf-assembly project (discussed later) would complain that it cannot resolve any of the two features aries-blueprint or war.

You can take a look at the following thread for further information on the prerequisite and dependency attributes but for now you can safely leave them set to false.

The Karaf Maven plugin post processes the file and adds all dependencies from the POM:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<features xmlns="http://karaf.apache.org/xmlns/features/v1.4.0" name="karaf-kar-1.0-SNAPSHOT">
	<repository>mvn:org.apache.karaf.features/standard/${karaf.version}/xml/features</repository>
	<feature name="karaf-kar" description="karaf-kar" version="1.0.0.SNAPSHOT">
		<details>Sample feature details...</details>
		<feature version="4.0.5.SNAPSHOT" prerequisite="false" dependency="false">aries-blueprint</feature>
		<feature version="4.0.5.SNAPSHOT" prerequisite="false" dependency="false">war</feature>
		<bundle>mvn:com.tonyganchev.blog/karaf-bundle-a/1.0-SNAPSHOT</bundle>
		<bundle>mvn:com.tonyganchev.blog/karaf-bundle-b/1.0-SNAPSHOT</bundle>
		<bundle>mvn:com.tonyganchev.blog/karaf-bundle-c/1.0-SNAPSHOT</bundle>
		<bundle>mvn:com.tonyganchev.blog/karaf-wab/1.0-SNAPSHOT</bundle>
	</feature>
</features>

Note: older versions of the tooling may try to enforce the addition of resolver attribute to the feature elements that failed on deployment into new Karaf containers. It is an issue of Karaf XML schema validation so pay attention to the used schema – the change I mention gets introduced in version 1.3.0.

The resulting karaf-kar/target/karaf-kar-1.0-SNAPSHOT.kar can be copied to the deploy folder of any Karaf installation and it will be deployed provided that the aries-blueprint and war are discoverable (not necessarily installed).

Custom Karaf Distributions

The last bundle is actually the one that proved to be the most troublesome. Two major issues there. The first was briefly mentioned above – the Karaf Maven plugin can be quite cryptic when reporting its inability to resolve features – thus the solution to add a <repository /> entry to the feature.xml manifest. Beforehand I resorted to enumerating the individual bundles my bundles relied on (aries-related and javax.servlet-api mainly). This worked but it was not clean and meant that due to another bug in Karaf I could not install the features that deliver these bundles if the bundles are installed. Now it seems you don’t need to mention the standard repository as it is always available.

The only thing we need in this project is it’s POM:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
...
	<artifactId>karaf-assembly</artifactId>
	<packaging>karaf-assembly</packaging>
	<dependencies>
		<dependency>
			<groupId>org.apache.karaf.features</groupId>
			<artifactId>framework</artifactId>
			<type>kar</type>
		</dependency>
		<dependency>
			<groupId>org.apache.karaf.features</groupId>
			<artifactId>standard</artifactId>
			<classifier>features</classifier>
			<type>xml</type>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>com.tonyganchev.blog</groupId>
			<artifactId>karaf-kar</artifactId>
			<version>${project.version}</version>
			<type>kar</type>
			<scope>runtime</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.karaf.tooling</groupId>
				<artifactId>karaf-maven-plugin</artifactId>
				<configuration>
					<bootFeatures>
						<feature>bundle</feature>
						<feature>diagnostic</feature>
						<feature>feature</feature>
						<feature>log</feature>
						<feature>package</feature>
						<feature>service</feature>
						<feature>shell</feature>
						<feature>system</feature>
					</bootFeatures>
				</configuration>
			</plugin>
		</plugins>
	</build>

</project>

Lets go though the highlights one by one. Karaf’s Maven plugin introduces additional packaging type – karaf-assembly. This saves us tons of custom (awfully hard to decipher) steps to build a Karaf distribution. All dependencies are taken into account when building the distribution. The first one should always be org.apache.karaf.features:framework:kar and it needs to be a compile-time dependency.

The next dependency tells the plugin to use the standard feature repository to resolve features. Last is our KAR module. Note that it is also runtime-scoped. This is extremely important. The scope will define how the bundles will be started. Runtime scope means that the feature will be installed and started automatically on successful start of Karaf. If you switched to compile-time this would mean that the bundles from the feature would be available on startup without starting the feature. I personally don’t felt comfortable with such behavior which was the second issue I wanted to talk about. The feature is considered uninstalled for the lifetime of the container unless installed manually and event this is not always easy to do. Note: you also have the option of using provided scope which essentially means that the feature is discoverable but not started.

The instructions to the Karaf plugin are left minimal – only the boot features are listed and they are kept to a minimum. Note that the karaf-kar feature is not mentioned neither are the features it depends on – still they are implicitly considered boot features. All boot features eventually make their way to the value of the featuresBoot setting in ${karaf}/etc/org.apache.karaf.features.cfg.

Testing It All Together

Once you’ve build everything successfully you should have a Karaf distribution created under karaf-assembly\target\assembly under the root of the project. I;d refer to this location as ${karaf} from now on. Go ahead and start the bundle.

karaf-assembly\target\assembly\bin\karaf clean

Note: use the clean option to ensure that no state is preserved to ensure that you’re not testing the results of previous karaf-assembly build.

If everything deploys successfully you should see output such as

        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.0.5-SNAPSHOT)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf.

karaf@root()> A: Starting the bundle
C: Starting the bundle
Greeting sender (C) started,
Greeting: test
B: Starting the bundle
Greeting: Bundle B started!

Now, check all of your bundles are deployed successfully:

karaf@root()> bundle:list
START LEVEL 100 , List Threshold: 50
ID | State  | Lvl | Version        | Name
---------------------------------------------------
12 | Active |  80 | 1.0.0.SNAPSHOT | karaf-bundle-a
13 | Active |  80 | 1.0.0.SNAPSHOT | karaf-bundle-b
14 | Active |  80 | 1.0.0.SNAPSHOT | karaf-bundle-c
15 | Active |  80 | 1.0.0.SNAPSHOT | karaf-wab

All bundles start at level 80 since we have not specified a custom start level. The default start level is defined by the value of property karaf.startlevel.bundle defined in ${karaf}etc/config.properties.

Now let’s see what the feature list looks like.

karaf@root()> feature:list -i
Name                | Version          | Required | State   | Repository              | Description
-------------------------------------------------------------------------------------------------------------------------------
pax-jetty           | 9.2.14.v20151106 |          | Started | org.ops4j.pax.web-4.2.4 | Provide Jetty engine support
pax-http-jetty      | 4.2.4            |          | Started | org.ops4j.pax.web-4.2.4 |
pax-http            | 4.2.4            |          | Started | org.ops4j.pax.web-4.2.4 | Implementation of the OSGI HTTP Service
pax-http-whiteboard | 4.2.4            |          | Started | org.ops4j.pax.web-4.2.4 | Provide HTTP Whiteboard pattern support
pax-war             | 4.2.4            |          | Started | org.ops4j.pax.web-4.2.4 | Provide support of a full WebContainer
aries-proxy         | 4.0.5.SNAPSHOT   |          | Started | standard-4.0.5-SNAPSHOT | Aries Proxy
aries-blueprint     | 4.0.5.SNAPSHOT   |          | Started | standard-4.0.5-SNAPSHOT | Aries Blueprint
feature             | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Features Support
shell               | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Karaf Shell
bundle              | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Provide Bundle support
diagnostic          | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Provide Diagnostic support
log                 | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Provide Log support
package             | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Package commands and mbeans
service             | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Provide Service support
system              | 4.0.5.SNAPSHOT   | x        | Started | standard-4.0.5-SNAPSHOT | Provide System support
http                | 4.0.5.SNAPSHOT   |          | Started | standard-4.0.5-SNAPSHOT | Implementation of the OSGI HTTP Service
war                 | 4.0.5.SNAPSHOT   |          | Started | standard-4.0.5-SNAPSHOT | Turn Karaf as a full WebContainer
karaf-kar           | 1.0.0.SNAPSHOT   | x        | Started | karaf-kar-1.0-SNAPSHOT  | karaf-kar

The -i switch specifies that only installed bundles should be shown. Note that the feature karaf-kar is installed together with its two dependencies aries-blueprint and war without having to specify them as boot features.

Now, let’s see if karaf-wab is properly deployed as a web bundle:

karaf@root()> web:list
ID | State       | Web-State   | Level | Web-ContextPath | Name      
-------------------------------------------------------------------------------------
15 | Active      | Deployed    | 70    | /wab-test       | karaf-wab (1.0.0.SNAPSHOT)

We’d also ensure that we have the servlet deployed:

karaf@root()> http:list
ID | Servlet           | Servlet-Name | State       | Alias | Url
--------------------------------------------------------------------------------------------------------------------------
15 | ResourceServlet   | default      | Deployed    | /     | [/]
15 |                   | test         | Deployed    |       | [/test]
15 | JspServletWrapper | jsp          | Deployed    |       | [*.jsp, *.jspx, *.jspf, *.xsp, *.JSP, *.JSPX, *.JSPF, *.XSP]

Listed are all servlets from bundle with ID 15 that is karaf-wab. This includes the implicit JSP- and resource servlets.

To be completely sure everything is working as expected, open http://localhost:8181/wab-test/test and verify that you can see the “The servlet works as expected.” message.

Last – note that although we supplied the kar dependency to karaf-assembly module, no KAR gets installed. If you decided to install the kar feature you’d be able to check this:

karaf@root()> kar:list
KAR Name
--------

The assembly explodes the KAR and moves its bundles and feature repository under ${karaf}/system repository.

Last Words

Up until now I’ve only touched the surface of what Karaf is. I didn’t have to deal with classloader issues and I did not port any existing OSGi application. I’m looking forward to doing this next and share the experience in new posts.

My opinion so far. I quite like Karaf for the abundance of command-line tooling. I hit a few of bugs related to not properly handling unsupported configurations (see KARAF-4254 for example). I have to say the level of support for such issues is quite good and the roll off of minor releases is quite good especially when compared to the dying Eclipse Virgo. The other think I much appreciate is the ease with which Karaf is built – there is only a single repository compared to the gazillion ones coming with Equinox and Virgo and the whole thing gets built with the default Maven commands. This turned out to be quite important since for some of the issues I hit I didn’t find any documentation and had to debug both Maven and Karaf. This is the reason I work with snapshot versions of Karaf.

The whole task took a couple of weeks stretched over a four week period so there were a lot of source I consulted. What I know were instrumental are listed below. If I missed something do not hesitate to correct me using the comments.

トニー

Gredichki and Motichki

Tony's Rudeness and Random Obsessions