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

You May Also Like

About the Author: jbonofre

ASF Member, PMC for Apache Karaf, PMC for Apache ServiceMix, PMC for Apache Archiva, PMC for Apache Felix, PMC for Apache Camel, PMC for Apache Syncope, PMC for Apache Beam, PMC for Apache CarbonData, PMC for Apache Bahir, PMC for Apache Brooklyn, PMC for Apache Falcon, PMC for Apache Guacamole, PMC for Apache Lens, Committer for Apache ActiveMQ and much more ! Twitter: jbonofre IRC: jbonofre on #servicemix,#karaf,#camel,#cxf on Freenode

Leave a Reply