Do you know the Apache Karaf Maven plugins ?

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).