A brief introduction to Apache Karaf Archives (Kars)

A relatively new feature to Apache Karaf 2.2.x is the Karaf Archive (Kar). Its purpose is to help make packaging and deploying Karaf features an easier process. A Kar accomplishes this aim by packaging all of a features' bundles and dependencies inside of archive file, which when copied into Karaf's deploy folder will be extracted into a local repo, and any included features files are then automatically registered with the runtime. A feature's bundles, and dependencies can be thought as one  artifact to act upon.

Sounds good, so what are the benefits?

This is a large improvement over having to individually copy jars into the local system repo then reference them via a separate features xml file (generally calling features:addUrl). Production environments benefit as an application deployed as a Kar should not require Maven based resolution at runtime since all its dependencies are already provided. Further more, components built as Kars can be easily referenced as Maven dependencies when building larger solutions (just add Kars as dependencies).

Cool, so what's next?

We've documented using Karaf Archives in the users guide, and will as of version 2.2.5 include a simple demo.

Let's look a little closer at building the Kar demo.

There are two essential components to the Kar demo; the pom file which calls the features-maven-plugin (karaf-maven-plugin on Karaf 3.x), and the features xml file describing the content of the Kar to be generated.

Lets have a look at a sample pom file:

In Apache Karaf version 2.2.x the features-maven-plugin is used to generate Kars via the create-kar goal. When executed it will read all features specified in the features descriptor, then for each feature it'll resolve the bundles defined in the feature, then all bundles are packaged into the Kar archive.

    <groupId>my.groupId</groupId>
    <artifactId>my-kar</artifactId>
    <version>1.0</version>
    <packaging>pom</packaging>

    <dependencies>
        <dependency>
            <groupId>org.apache.servicemix.bundles</groupId>
            <artifactId>org.apache.servicemix.bundles.commons-collections</artifactId>
            <version>3.2.1_1</version>
            <scope>runtime</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.karaf.tooling</groupId>
                <artifactId>features-maven-plugin</artifactId>
                <version>2.2.5</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>

Lets have a look at a sample features xml file:

A features descriptor is a simple xml file that contains the feature's name, version, and list of bundles it depends upon. In this sample the Servicemix commons-collections bundle version 3.2.1_1 is specified.

<?xml version="1.0" encoding="UTF-8"?>
<features>
    <feature name="my-kar" version="1.0">
 <bundle>mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.commons-collections/3.2.1_1</bundle>
    </feature>
</features>

To build the Kar file all that is required is to execute mvn install. The plugin will create the Kar file in the target build directory.

To deploy the KAR the user need only copy the resultant KAR file to the KARAF_HOME/deploy folder. Please note that the Kar deployer is a core part of Karaf, so no additional features need to be installed to use Kars.

You can now see your feature available:

  karaf@root> feature:list | grep -i my-kar
  [installed] [1.0             ] my-kar                        repo-0

Now you can use any commands available on features:

  karaf@root> feature:info my-kar
  Feature my-kar 1.0
  Feature has no configuration
  Feature has no configuration files
  Feature has no dependencies.
  Feature contains followed bundles:
    mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.commons-collections/3.2.1_1


I hope you found the above introduction to Apache Karaf Kars informative. If you have any questions please visit the documentation, see the demo, contact the Karaf user email list, or leave it in comments section below :)