Archive for: ‘December 2011’

Coming in Karaf 3.0: new KAR service, command, management

December 27, 2011 Posted by jbonofre

We are working hard on Karaf 3.0. This major new version of Karaf will bring a lot of new features and enhancements.

KAR in Karaf 2.2.4

As you may know, Karaf 2.2.x already provides “basic” KAR support.

A KAR (KARaf archive) is a zip file which gathers a features XML and all bundles and configuration files dependencies. It means that a KAR is an atomic artifact which can be deployed without an Internet connection (as all is shipped in the KAR file itself).

In Karaf 2.2.x, the KAR support was:

  • a KAR deployer: you can copy a KAR file into the deploy folder, and KARAF will uncompress the KAR file, and install all features containing in the shipped features XML.
  • a create-kar goal in the features-maven-plugin: this goal reads a features XML and creates a KAR file, ready to be deployed.

So, all KAR logics were in the KAR deployer.

It means that you are not able to deploy a KAR from a remote URL, etc.

What’s coming in Karaf 3.0

The KAR service

In Karaf 3.0, the KAR core bundle provides a org.apache.karaf.kar.KarService OSGi service.

This service allows you to list the installed KAR files, deploy a KAR file from an URL, uninstall a KAR file.

Now the KAR service use a data/kar directory to store the KAR file and uncompress the KAR directly in the system repository (the local-repo directory is no more needed and created).

The KAR shell commands

Now, you have a complete control on the KAR files (including remotely using a SSH connection).

You can list, install, and uninstall KAR files using the kar:* commands:

  • kar:list displays the installed KAR files
  • kar:install installs a KAR file from a given URL. The URL could be a “classic” file: or http:, but, as for all stuff in Karaf, mvn: (for instance mvn:net.nanthrax/test/1.0-SNAPSHOT/kar)
  • kar:uninstall uninstalls a KAR file (identified by the name as displayed by kar:list). This command doesn’t alter the system repository by default, but you have an option -c (–cleanup) to cleanup the system repository.

The KAR MBean

You can also manipulate KAR files using JMX via a new MBean: org.apache.karaf:type=kar,name=root.

This MBean provides quite the same actions that you can do using the commands:

  • getKars()
  • install(url)
  • uninstall(name)
  • uninstall(name, clean)

In progress

It’s still a work in progress. I will add a bunch of unit tests and new features around the KAR files.

Overview on Apache Karaf, Pax Web, and Camel archetypes

December 19, 2011 Posted by jbonofre

In my previous blog post, I introduced the Karaf Maven plugins.
The Karaf Maven plugins are really helpful, starting from an existing POM.

If you can write this POM by hand (it’s my favorite way ;)), we also provide several archetypes which create and pre-configure a Maven project for you.

Karaf Archetypes

The next Karaf release (2.2.5) provides a set of new archetypes:

Assembly Archetype

The karaf-assembly-archetype create a Maven project which create a custom Karaf distribution.

It allows you to create your own Karaf distribution. The project downloads a Karaf standard distribution (in tar.gz and zip formats), unpack it, and create a new distribution.

The easiest way to use it is to use the interactive mode:


mvn archetype:generate -DarchetypeGroupId=org.apache.karaf.archetypes -DarchetypeArtifactId=karaf-assembly-archetype -DarchetypeVersion=2.2.5-SNAPSHOT

Bundle Archetype

If basically a bundle is a jar file with some special statement in the MANIFEST, the easiest way to create a bundle is to use the Felix maven-bundle-plugin.

Karaf provides an archetype which prepare a Maven project and provide a bundle Activator (a special callback class when the bundle start/stop).

To generate this project, simply type:


mvn archetype:generate -DarchetypeGroupId=org.apache.karaf.archetypes -DarchetypeArtifactId=karaf-bundle-archetype -DarchetypeVersion=2.2.5-SNAPSHOT

NB: I think that this archetype should be in Felix (as the same level as maven-bundle-plugin), I will propose a donation to the Felix community.

Blueprint Archetype

Blueprint is IoC approach applied to OSGi (it comes from Spring DM in fact). It allows you to avoid to write bundle Activator, ServiceTracker, etc.

Karaf provides a karaf-blueprint-archetype which prepare a Maven project including the maven-bundle-plugin, and a blueprint descriptor with a sample of OSGi service definition:


mvn archetype:generate -DarchetypeGroupId=org.apache.karaf.archetypes -DarchetypeArtifactId=karaf-blueprint-archetype -DarchetypeVersion=2.2.5-SNAPSHOT

NB: I think that this archetype should be in Aries (as it’s the blueprint implementation used in Karaf), I will propose a donation to the Aries community.

Feature Archetype

In Karaf, a feature is an application descriptor, defining all bundles, configurations/configuration files, others features. This features descriptor could be generated by hand (it’s my favorite way, and I guess the recommended one), we also provide a archetype which prepare a project to generate features file regarding the POM dependencies:


mvn archetype:generate -DarchetypeGroupId=org.apache.karaf.archetypes -DarchetypeArtifactId=karaf-feature-archetype -DarchetypeVersion=2.2.5-SNAPSHOT

Kar Archetype

We saw in my previous post a new goal of the features-maven-plugin to create a kar file starting from a features XML. A KAR file is a zip file containing the features XML and all its dependencies.

We also provide an archetype to prepare a Maven project containing a features XML and generate a KAR file:


mvn archetype:generate -DarchetypeGroupId=org.apache.karaf.archetypes -DarchetypeArtifactId=karaf-kar-archetype -DarchetypeVersion=2.2.5-SNAPSHOT

Pax-Web Archetypes

We also add several archetypes in Pax Web to deal with the web bundle. Charles talk about wab-gwt archetype in his last blog entry (http://cmoulliard.blogspot.com/2011/12/run-google-web-toolkit-2-project-on.html), but I added also two others.

Web Bundle Archetype

The Web Bundle Archetype create a “special” bundle containing web resources and statements. It creates a Maven project with webapp resources and WebApp Context in the POM:


mvn archetype:generate -DarchetypeGroupId=org.ops4j.pax.web.archetypes -DarchetypeArtifactId=wab-archetype -DarchetypeVersion=1.1.2-SNAPSHOT

War Archetype

We also provide an archetype to create a Maven project which generate a standard war (that you can deploy “outside” of OSGi) but including OSGi statements in the MANIFEST (which allows you to use OSGi values):


mvn archetype:generate -DarchetypeGroupId=org.ops4j.pax.web.archetypes -DarchetypeArtifactId=war-archetype -DarchetypeVersion=1.1.2-SNAPSHOT

Camel Archetypes

Camel also provides a set of very useful archetypes, especially:

  • camel-archetype-blueprint to generate a Maven project with a blueprint XML in which you can define your routes
  • camel-archetype-component providing a template to create your own Camel component
  • camel-archetype-dataformat providing a template to create your own Camel data format
  • camel-archetype-java providing a template with a class in which you can define your routes
  • camel-archetype-spring to generate a Maven project with a Spring XML in which you can define your routes

For instance, to create a Camel blueprint Maven project, simply type:


mvn archetype:generate -DarchetypeGroupId=org.apache.camel.archetypes -DarchetypeArtifactId=camel-archetype-blueprint -DarchetypeVersion=2.9-SNAPSHOT

Do you know the Apache Karaf Maven plugins ?

December 12, 2011 Posted by jbonofre

Apache Karaf is not only an OSGi container, it also provides a set of Maven plugins for tooling.

In the next Apache Karaf 2.2.5 release, you will find two Maven plugins:

  • cmdhelp-maven-plugin generates documentation (in DocBook or Scalate format) for Karaf commands
  • features-maven-plugin provides a set of goals to manipulate Karaf features

In this blog post, I will cover the features-maven-plugin as I think it’s the most interesting for your life with Karaf.

Generate a features XML

If I prefer to handle and create the features XML by hand, the features:generate-features-file goal could do it for you.

It takes the dependencies of your project (described in the POM), and create the features XML.

For instance, in the following example, a features XML file will be generated containing the commons-lang bundle:


<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">

  <modelVersion>4.0.0</modelVersion>

  <groupId>net.nanthrax</groupId>
  <artifactId>test-features</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <dependencies>
    <dependency>
      <groupId>org.apache.servicemix.bundles</groupId>
      <artifactId>org.apache.servicemix.bundles.commons-lang</artifactId>
      <version>2.4_4</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>features-maven-plugin</artifactId>
        <version>2.2.5-SNAPSHOT</version>
        <executions>
          <execution>
            <id>generate-features-filelt;/id>
            <goals>
              <goal>generate-features-file</goal>
            </goals>
            <configuration>
              <karafVersion>2.2.4</karafVersion>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

You can find the features XML in the target directory.

Copy features resources in a local directory

The features:add-features-to-repo goal reads a set of features and copy features resources into a target folder. Especially, it allows you to prepare a custom distribution, allowing this distribution to avoid Internet connection to resolve features resources.

The following example will read a features XML and populate the target/system directory with the feature A, B, and C resources (bundles and configuration files):


<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">

  <modelVersion>4.0.0</modelVersion>

  <groupId>net.nanthrax</groupId>
  <artifactId>test-features</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>features-maven-plugin</artifactId>
        <version>2.2.5-SNAPSHOT</version>
        <executions>
          <execution>
            <id>add-features-to-repo</id>
            <goals>
              <goal>features-add-to-repo</goal>
            </goals>
            <configuration>
              <descriptors>
                <descriptor>file:${project.basedir}/src/main/resources/features.xml</descriptor>
              </descriptors>
              <features>
                <feature>A</feature>
                <feature>B/2.0-SNAPSHOT</feature>
              </features>
              <repository>target/system</repository>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

NB: with Karaf 2.2.5, you can define a feature with just its name, or with name/version. It allows to target explicitly with which feature populate the target repository directory.

Create a KAR file

A KAR file (Karaf ARchive) is a zip file which package a features XML with all dependencies (bundles and configuration files).

It allows you to deploy (just by copying the kar file in the Karaf deploy folder) an atomic archive shipping all required resources (so no Internet connection is required).

The features:create-kar goal create a kar file starting from a given features XML.

The following example create a kar file (in the target folder) starting from a src/main/resources/features.xml:


<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">

  <modelVersion>4.0.0</modelVersion>

  <groupId>net.nanthrax</groupId>
  <artifactId>test-features</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>features-maven-plugin</artifactId>
        <version>2.2.5-SNAPSHOT</version>
        <executions>
          <execution>
            <id>create-kar</id>
            <goals>
              <goal>create-kar</goal>
            </goals>
            <configuration>
              <featuresFile>${project.basedir}/src/main/resources/features.xml</featuresFile>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Karaf 3.0 changes

In Karaf 3.0.0, you will find only one Maven plugin: karaf-maven-plugin, gathering the two “old” one.

The KAR support is also extended and give more place to KAR archives (used to construct distributions now).