KAR
As described in the Provisioning section, Apache Karaf features describe applications.
A feature defines different resources to resolve using URL (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 require 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 a zip archive containing the
Basically, the kar format is 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, the following Maven POM create my-kar.kar
For instance, you can use the following POM to create a 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
Uou will have your kar 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 populated 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 uninstall 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/systemrepository) 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 install features, by default, it refresh 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 givenurl. -
install(url, noAutoStartBundles)installs the KAR file at the givenurl, deciding if you want to automatically start the bundles or not. -
create(repository, features)creates a KAR file using the given featuresrepositoryname, and optionally the list offeaturesto include in the KAR file. -
uninstall(name)uninstalls a KAR file with the givenname.