manual/src/main/asciidoc/user-guide/kar.adoc

//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

=== KAR

As described in the link:provisioning[Provisioning section], Apache Karaf features describe applications.

A feature defines different resources to resolve using URLs (for instance, bundles URLs, or configuration files URLs).
As described in the [Artifacts repositories and URLs section|urls], Apache Karaf looks for artifacts (bundles,
configuration files, ...) in the artifact repositories.
Apache Karaf may have to download artifacts from remote repositories.

Apache Karaf provides a special type of artifact that package a features XML and all resources described in the features
of this XML. This artifact is named a KAR (KAraf aRchive).

A KAR file is essentially a jar (so a zip file) which contains a set of feature descriptor and bundle jar files.

A KAR file contains a `repository` folder containing:

* a set of features XML files
* the artifacts following the Maven directory structure (`groupId/artifactId/version/artifactId-version.type`).

For instance, the `spring-4.0.0.kar` contains:

----
~$ unzip -l spring-4.0.0.kar
Archive:  spring-4.0.0.kar
  Length      Date    Time    Name
---------  ---------- -----   ----
      143  2013-12-06 10:52   META-INF/MANIFEST.MF
    12186  2013-12-06 10:52   repository/org/apache/karaf/features/spring/4.0.0/spring-4.0.0-features.xml
   575389  2013-12-06 10:52   repository/commons-collections/commons-collections/3.2.1/commons-collections-3.2.1.jar
   232019  2013-12-06 10:52   repository/commons-beanutils/commons-beanutils/1.8.3/commons-beanutils-1.8.3.jar
   673109  2013-12-06 10:52   repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.struts/1.3.10_1/org.apache.servicemix.bundles.struts-1.3.10_1.jar
    37084  2013-12-06 10:52   repository/org/springframework/org.springframework.web.struts/3.2.4.RELEASE/org.springframework.web.struts-3.2.4.RELEASE.jar
     7411  2013-12-06 10:52   repository/org/springframework/org.springframework.instrument/3.2.4.RELEASE/org.springframework.instrument-3.2.4.RELEASE.jar
   246881  2013-12-06 10:52   repository/org/springframework/org.springframework.transaction/3.2.4.RELEASE/org.springframework.transaction-3.2.4.RELEASE.jar
    16513  2013-12-06 10:52   repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.aopalliance/1.0_6/org.apache.servicemix.bundles.aopalliance-1.0_6.jar
   881124  2013-12-06 10:52   repository/org/springframework/org.springframework.core/3.2.4.RELEASE/org.springframework.core-3.2.4.RELEASE.jar
   199240  2013-12-06 10:52   repository/org/springframework/org.springframework.expression/3.2.4.RELEASE/org.springframework.expression-3.2.4.RELEASE.jar
   614646  2013-12-06 10:52   repository/org/springframework/org.springframework.beans/3.2.4.RELEASE/org.springframework.beans-3.2.4.RELEASE.jar
   340841  2013-12-06 10:52   repository/org/springframework/org.springframework.aop/3.2.4.RELEASE/org.springframework.aop-3.2.4.RELEASE.jar
   877369  2013-12-06 10:52   repository/org/springframework/org.springframework.context/3.2.4.RELEASE/org.springframework.context-3.2.4.RELEASE.jar
   130224  2013-12-06 10:52   repository/org/springframework/org.springframework.context.support/3.2.4.RELEASE/org.springframework.context.support-3.2.4.RELEASE.jar
    30640  2013-12-06 10:52   repository/org/apache/karaf/deployer/org.apache.karaf.deployer.spring/4.0.0/org.apache.karaf.deployer.spring-4.0.0.jar
    51951  2013-12-06 10:52   repository/org/springframework/org.springframework.aspects/3.2.4.RELEASE/org.springframework.aspects-3.2.4.RELEASE.jar
   411175  2013-12-06 10:52   repository/org/springframework/org.springframework.jdbc/3.2.4.RELEASE/org.springframework.jdbc-3.2.4.RELEASE.jar
    48049  2013-12-06 10:52   repository/javax/portlet/portlet-api/2.0/portlet-api-2.0.jar
   190883  2013-12-06 10:52   repository/org/springframework/org.springframework.web.portlet/3.2.4.RELEASE/org.springframework.web.portlet-3.2.4.RELEASE.jar
   635680  2013-12-06 10:52   repository/org/springframework/org.springframework.web/3.2.4.RELEASE/org.springframework.web-3.2.4.RELEASE.jar
   645946  2013-12-06 10:52   repository/org/springframework/org.springframework.web.servlet/3.2.4.RELEASE/org.springframework.web.servlet-3.2.4.RELEASE.jar
   464911  2013-12-06 10:52   repository/org/springframework/org.springframework.test/3.2.4.RELEASE/org.springframework.test-3.2.4.RELEASE.jar
    69784  2013-12-06 10:52   repository/org/springframework/osgi/spring-osgi-web/1.2.1/spring-osgi-web-1.2.1.jar
    16030  2013-12-06 10:52   repository/org/apache/geronimo/specs/geronimo-jta_1.1_spec/1.1.1/geronimo-jta_1.1_spec-1.1.1.jar
    32359  2013-12-06 10:52   repository/org/apache/geronimo/specs/geronimo-jms_1.1_spec/1.1.1/geronimo-jms_1.1_spec-1.1.1.jar
   208684  2013-12-06 10:52   repository/org/springframework/org.springframework.jms/3.2.4.RELEASE/org.springframework.jms-3.2.4.RELEASE.jar
    75672  2013-12-06 10:52   repository/org/springframework/org.springframework.oxm/3.2.4.RELEASE/org.springframework.oxm-3.2.4.RELEASE.jar
   393607  2013-12-06 10:52   repository/org/springframework/org.springframework.orm/3.2.4.RELEASE/org.springframework.orm-3.2.4.RELEASE.jar
   338559  2013-12-06 10:52   repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.cglib/3.0_1/org.apache.servicemix.bundles.cglib-3.0_1.jar
    35859  2013-12-06 10:52   repository/org/springframework/osgi/spring-osgi-io/1.2.1/spring-osgi-io-1.2.1.jar
   362889  2013-12-06 10:52   repository/org/springframework/osgi/spring-osgi-core/1.2.1/spring-osgi-core-1.2.1.jar
   120822  2013-12-06 10:52   repository/org/springframework/osgi/spring-osgi-extender/1.2.1/spring-osgi-extender-1.2.1.jar
    24231  2013-12-06 10:52   repository/org/springframework/osgi/spring-osgi-annotation/1.2.1/spring-osgi-annotation-1.2.1.jar
    12597  2013-12-06 10:52   repository/org/apache/karaf/bundle/org.apache.karaf.bundle.springstate/4.0.0/org.apache.karaf.bundle.springstate-4.0.0.jar
    31903  2013-12-06 10:52   repository/org/eclipse/gemini/blueprint/gemini-blueprint-io/1.0.0.RELEASE/gemini-blueprint-io-1.0.0.RELEASE.jar
   578205  2013-12-06 10:52   repository/org/eclipse/gemini/blueprint/gemini-blueprint-core/1.0.0.RELEASE/gemini-blueprint-core-1.0.0.RELEASE.jar
   178525  2013-12-06 10:52   repository/org/eclipse/gemini/blueprint/gemini-blueprint-extender/1.0.0.RELEASE/gemini-blueprint-extender-1.0.0.RELEASE.jar
---------                     -------
  9803140                     38 files
----

As a KAR file is a simple zip file, you can create the KAR file by hand.

For instance, the following Unix commands create a very simple KAR file:

----
~$ mkdir repository
~$ cp /path/to/features.xml repository/features.xml
~$ cp /path/to/my.jar repository/my/project/my/1.0.0/my-1.0.0.jar
~$ zip -r my.kar repository
updating: repository/ (stored 0%)
  adding: repository/my/project/my/1.0.0/my-1.0.0.jar (deflated 0%)
----

You can create KAR files using Apache Maven, or directly in the Apache Karaf console.

==== Maven

Apache Karaf provides a Maven plugin: `karaf-maven-plugin`.

The Apache Karaf Maven plugin provides the `kar` goal.

The `kar` goal does:

. Reads all features specified in the features XML.
. For each feature described in the features XML, the goal resolves the bundles described in the feature.
. The goal finally packages the features XML, and the resolved bundles in a zip file.

For instance, you can use the following POM to create `my-kar.kar`:

----
<?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>my.groupId</groupId>
    <artifactId>my-kar</artifactId>
    <version>1.0</version>
    <packaging>kar</packaging>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.karaf.tooling</groupId>
                <artifactId>karaf-maven-plugin</artifactId>
                <version>4.0.0</version>
                <extensions>true</extensions>
            </plugin>
        </plugins>
    </build>

</project>
----

To create the KAR file, simply type:

----
~$ mvn install
----

The kar will be installed in the `target` directory.

==== Commands

Apache Karaf provides `kar:*` commands to manage KAR archives.

===== `kar:list`

The `kar:list` command lists the installed KAR archives.

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

A KAR is identified by its name.

===== `kar:create`

Instead of using the `karaf-maven-plugin` or create the KAR archive by hand, you can use the `kar:create` command.

The `kar:create` command creates a KAR file using a registered features repository.

For instance, you want to create a KAR file for the Pax Web repository.

The `feature:repo-list` command gives you the list of registered features repositories:

----
karaf@root()> feature:repo-list
Repository                       | URL
-------------------------------------------------------------------------------------------------------
standard-4.0.0                   | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
enterprise-4.0.0                 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
spring-4.0.0                     | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
org.ops4j.pax.web-4.1.4          | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
----

You can use one of these features repositories to create the kar file:

----
karaf@root()> kar:create org.ops4j.pax.web-4.1.4
Adding feature pax-jetty
Adding feature pax-http-whiteboard
Adding feature pax-war
Adding feature pax-http-tomcat
Adding feature pax-war-tomcat
Adding feature pax-http
Adding feature pax-http-jetty
Adding feature pax-jsf-support
Adding feature pax-jetty-spdy
Kar file created : /home/jbonofre/Downloads/apache-karaf-4.0.0/data/kar/org.ops4j.pax.web-4.1.4.kar
----

You can see that the KAR file has been created in the `KARAF_DATA/kar` folder.

By default, the `kar:create` command creates a KAR file, packaging all features in the features descriptor.

You can provide the list of features that you want to package into the KAR file:

----
karaf@root()> kar:create org.ops4j.pax.web-4.1.4 pax-jetty pax-tomcat
Adding feature pax-jetty
Adding feature pax-tomcat
Kar file created : /opt/apache-karaf-4.1.4/data/kar/org.ops4j.pax.web-4.1.4.kar
----

===== `kar:install`

You can deploy a KAR file using `kar:install` command.

The `kar:install` command expects the KAR URL. Any URL described in the [Artifacts repositories and URLs section|urls]
is supported by the `kar:install` command:

----
karaf@root()> kar:install file:/tmp/my-kar-1.0-SNAPSHOT.kar
----

The KAR file is uncompressed and used to populate the `KARAF_BASE/system` folder.

The Apache Karaf KAR service is looking for features XML files in the KAR file, registers the features XML and automatically
installs all features described in the features repositories present in the KAR file.

Optionally, you can control if the bundles should be automatically started or not using `--no-start` option.

===== `kar:uninstall`

The `kar:uninstall` command uninstalls a KAR file (identified by a name).

By uninstall, it means that:

* the features previously installed by the KAR file are uninstalled
* delete (from the `KARAF_DATA/system` repository) all files previously "populated" by the KAR file

For instance, to uninstall the previously installed `my-kar-1.0-SNAPSHOT.kar` KAR file:

----
karaf@root()> kar:uninstall my-kar-1.0-SNAPSHOT
----

==== Deployer

Apache Karaf also provides a KAR deployer. It means that you can drop a KAR file directly in the `deploy` folder.

Apache Karaf will automatically install KAR files from the `deploy` folder.

You can change the behaviours of the KAR deployer in the `etc/org.apache.karaf.kar.cfg`:

----
################################################################################
#
#    Licensed to the Apache Software Foundation (ASF) under one or more
#    contributor license agreements.  See the NOTICE file distributed with
#    this work for additional information regarding copyright ownership.
#    The ASF licenses this file to You under the Apache License, Version 2.0
#    (the "License"); you may not use this file except in compliance with
#    the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#
################################################################################

#
# Enable or disable the refresh of the bundles when installing
# the features contained in a KAR file
#
noAutoRefreshBundles=false

#
# Enable or disable the automatic start of the bundles when installing
# the features contained in a KAR file
#
noAutoStartBundles=false

#
# Directory where the kar are stored (when downloaded from Maven for instance)
#
#karStorage=${karaf.data}/kar
----

By default, when the KAR deployer installs features, it refreshes the bundles already installed.
You can disable the automatic bundles refresh by setting the `noAutoRefreshBundles` property to `false`.

==== JMX KarMBean

On the JMX layer, you have a MBean dedicated to the management of the KAR files.

The ObjectName to use is `org.apache.karaf:type=kar,name=*`.

===== Attributes

The `Kars` attributes provides the list of KAR files (name) installed.

===== Operations

* `install(url)` installs the KAR file at the given `url`.
* `install(url, noAutoStartBundles)` installs the KAR file at the given `url`, deciding if you want to automatically start the bundles or not.
* `create(repository, features)` creates a KAR file using the given features `repository` name, and optionally the
list of `features` to include in the KAR file.
* `uninstall(name)` uninstalls a KAR file with the given `name`.