You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/12/06 14:14:19 UTC
svn commit: r1548508 -
/karaf/trunk/manual/src/main/webapp/users-guide/kar.conf
Author: jbonofre
Date: Fri Dec 6 13:14:18 2013
New Revision: 1548508
URL: http://svn.apache.org/r1548508
Log:
[KARAF-2511] Review and update the kar page of the user guide
Modified:
karaf/trunk/manual/src/main/webapp/users-guide/kar.conf
Modified: karaf/trunk/manual/src/main/webapp/users-guide/kar.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/kar.conf?rev=1548508&r1=1548507&r2=1548508&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/kar.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/kar.conf Fri Dec 6 13:14:18 2013
@@ -1,33 +1,98 @@
+h1. KAR
+As described in the [Provisioning section|provisioning], Apache Karaf features describe applications.
-h1. Karaf Archives (KAR)
+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.
-Karaf provides a specific archive format named the KAR (Karaf ARchive).
+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.
-For instance, a kar looks like:
-* my-features-1.xml
-* bundle1.jar
-* bundle2.jar
-* bundle3.jar
+A KAR file contains a {{repository}} folder containing:
-all packaged in zip format.
+* a set of features XML files
+* the artifacts following the Maven directory structure ({{groupId/artifactId/version/artifactId-version.type}}).
-h2. Create a kar archive from the console
+For instance, the {{spring-3.0.0.kar}} contains:
-Example:
-{code}
-feature:repo-add camel 2.10.0
-kar:create camel-2.10.0
{code}
-
-This will create a kar of all camel features and store it in data/kar. It is also possible to specify a list of features to pack into the kar.
-This aproach is ideal if you want to use e.g. camel in an environment without internet connection.
-
-h2. Create a kar archive using maven
-
-You can create a kar file by hand, just by zip compressing a directory representing the kar content.
+~$ unzip -l spring-3.0.0.kar
+Archive: spring-3.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/3.0.0/spring-3.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/3.0.0/org.apache.karaf.deployer.spring-3.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/3.0.0/org.apache.karaf.bundle.springstate-3.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
+{code}
+
+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:
+
+{code}
+~$ 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%)
+{code}
+
+You can create KAR files using Apache Maven, or directly in the Apache Karaf console.
+
+h2. Maven
+
+Apache Karaf provides a Maven plugin: {{karaf-maven-plugin}}.
+
+The Apache Karaf Maven plugin provides the {{features-create-kar}} goal.
+
+The {{features-create-kar}} goal does:
+1. Reads all features specified in the features XML.
+2. For each feature described in the features XML, the goal resolves the bundles described in the feature.
+3. The goal finally packages the features XML, and the resolved bundles in a zip file.
You can also use the Karaf maven plugin. The features maven plugin provides an features-create-kar goal.
@@ -36,9 +101,11 @@ The features-create-kar goal:
2. For each feature, it resolves the bundles defined in the feature.
3. All bundles are packaged into the kar archive.
+For instance, the following Maven POM create {{my-kar.kar}}
+
For instance, you can use the following POM to create a kar:
-{code}
+{code:lang=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">
@@ -54,7 +121,7 @@ For instance, you can use the following
<plugin>
<groupId>org.apache.karaf.tooling</groupId>
<artifactId>karaf-maven-plugin</artifactId>
- <version>${project.version}</version>
+ <version>3.0.0</version>
<executions>
<execution>
<id>features-create-kar</id>
@@ -73,48 +140,158 @@ For instance, you can use the following
</project>
{code}
-For the example, the features descriptor is very simple:
+To create the KAR file, simply type:
{code}
-<?xml version="1.0" encoding="UTF-8"?>
-<features>
+~$ mvn install
+{code}
+
+Uou will have your kar in the {{target}} directory.
+
+h2. Commands
+
+Apache Karaf provides {{kar:*}} commands to manage KAR archives.
- <feature name="my" version="1.0">
- <bundle>mvn:commons-collections/commons-collections/3.2.1</bundle>
- </feature>
+h3. {{kar:list}}
-</features>
+The {{kar:list}} command lists the installed KAR archives.
+
+{code}
+karaf@root()> kar:list
+KAR Name
+-------------------
+my-kar-1.0-SNAPSHOT
+{code}
+
+A KAR is identified by its name.
+
+h3. {{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:
+
+{code}
+karaf@root()> feature:repo-list
+Repository | URL
+-------------------------------------------------------------------------------------------------------
+standard-3.0.0 | mvn:org.apache.karaf.features/standard/3.0.0/xml/features
+enterprise-3.0.0 | mvn:org.apache.karaf.features/enterprise/3.0.0/xml/features
+spring-3.0.0 | mvn:org.apache.karaf.features/spring/3.0.0/xml/features
+org.ops4j.pax.web-3.0.5 | mvn:org.ops4j.pax.web/pax-web-features/3.0.5/xml/features
{code}
-To create the kar archive, simply type:
+You can use one of these features repositories to create the kar file:
{code}
-mvn install
+karaf@root()> kar:create org.ops4j.pax.web-3.0.5
+Adding feature pax-war
+Adding feature pax-http-whiteboard
+Adding feature pax-jetty
+Adding feature pax-tomcat
+Adding feature pax-http
+Kar file created : /opt/apache-karaf-3.0.0/data/kar/org.ops4j.pax.web-3.0.5.kar
{code}
-and you will have your kar in the {{target}} directory.
+You can see that the KAR file has been created in the {{KARAF_DATA/kar}} folder.
-h2. Deploy a kar archive
+By default, the {{kar:create}} command creates a KAR file, packaging all features in the features descriptor.
-Karaf provides a KAR deployer:
+You can provide the list of features that you want to package into the KAR file:
{code}
-karaf@root> la|grep -i archive
-[ 12] [Active ] [Created ] [ 30] Apache Karaf :: Deployer :: Karaf Archive (.kar) (3.0.0.SNAPSHOT)
+karaf@root()> kar:create org.ops4j.pax.web-3.0.5 pax-jetty pax-tomcat
+Adding feature pax-jetty
+Adding feature pax-tomcat
+Kar file created : /opt/apache-karaf-3.0.0/data/kar/org.ops4j.pax.web-3.0.5.kar
{code}
-It's a core deployer (you don't need to install additional features).
+h3. {{kar:install}}
-To deploy a kar, simply drop the kar into the deploy directory. The KAR Deployer will deploy all the kar content starting
-from the features descriptor.
+You can deploy a KAR file using {{kar:install}} command.
-The KAR Deployer uncompress KAR archives in the system repository, automatically register features descriptors contained
-in the KAR, and automatically installs all features:
+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:
{code}
-karaf@root> feature:list|grep -i my
-[ installed] [1.0 ] my repo-0
+karaf@root()> kar:install file:/tmp/my-kar-1.0-SNAPSHOT.kar
{code}
-h2. Kar structure
+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.
+
+h3. {{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/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:
+
+{code}
+karaf@root()> kar:uninstall my-kar-1.0-SNAPSHOT
+{code}
+
+h2. 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}}:
+
+{code}
+################################################################################
+#
+# 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
+{code}
+
+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}}.
+
+h2. 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=*}}.
+
+h3. Attributes
+
+The {{Kars}} attributes provides the list of KAR files (name) installed.
+
+h3. Operations
+* {{install(url)}} installs the KAR file at the given {{url}}.
+* {{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}}.
\ No newline at end of file