svn commit: r1070412 - in /karaf/trunk/manual/src/main/webapp: developers-guide/index.conf users-guide/index.conf users-guide/kar.conf

[jb...@apache.org]

Author: jbonofre
Date: Mon Feb 14 09:04:49 2011
New Revision: 1070412

URL: http://svn.apache.org/viewvc?rev=1070412&view=rev
Log:
[KARAF-433] Add documentation about kar archive and deployer.

Added:
    karaf/trunk/manual/src/main/webapp/users-guide/kar.conf
Modified:
    karaf/trunk/manual/src/main/webapp/developers-guide/index.conf
    karaf/trunk/manual/src/main/webapp/users-guide/index.conf

Modified: karaf/trunk/manual/src/main/webapp/developers-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/developers-guide/index.conf?rev=1070412&r1=1070411&r2=1070412&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/developers-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/developers-guide/index.conf Mon Feb 14 09:04:49 2011
@@ -5,7 +5,7 @@ h1. Developers Guide
 * [Custom Distribution|custom-distribution]
 * [Security Framework|security-framework]
 * [Using the features-maven-plugin|features-maven-plugin]
-* [Troubleshooting, Debugging and Profiling|debugging]
+* [Troubleshooting, Debugging, Profiling, and Monitoring|debugging]
 * [Programmatically connect to the console|connect-console]
 * [Writing integration tests|writing-tests]
 * [Creating bundles|creating-bundles]

Modified: karaf/trunk/manual/src/main/webapp/users-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/index.conf?rev=1070412&r1=1070411&r2=1070412&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/index.conf Mon Feb 14 09:04:49 2011
@@ -13,6 +13,7 @@ h1. Karaf Users Guide
 * [Logging system|logging-system]
 * [Deployer|/users-guide/deployer]
 * [Provisioning|provisioning]
+* [Karaf Archive|kar]
 * [Configuration|configuration]
 * [Web applications|/users-guide/web-applications]
 * [OS integration|/users-guide/wrapper]

Added: 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=1070412&view=auto
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/kar.conf (added)
+++ karaf/trunk/manual/src/main/webapp/users-guide/kar.conf Mon Feb 14 09:04:49 2011
@@ -0,0 +1,112 @@
+
+
+h1. Karaf Archives (KAR)
+
+Karaf provides a specific archive format named the KAR (Karaf ARchive).
+
+Basically, the kar format is a jar (so a zip file) which contains a set of features descriptor and bundles jar files.
+
+For instance, a kar looks like:
+* my-features-1.xml
+* bundle1.jar
+* bundle2.jar
+* bundle3.jar
+
+all packaged in zip format.
+
+h2. Create a kar archive
+
+You can create a kar file by hand, just by zip compressing a directory representing the kar content.
+
+You can also use the Karaf features maven plugin. The features maven plugin provides an archive-kar goal.
+
+The kar-archive goal:
+1. Reads all features specified in the features descriptor.
+2. For each feature, it resolves the bundles defined in the feature.
+3. All bundles are packaged into the kar archive.
+
+For instance, you can use the following POM to create a kar:
+
+{code}
+<?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>pom</packaging>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.karaf.tooling</groupId>
+                <artifactId>features-maven-plugin</artifactId>
+                <version>2.99.99-SNAPSHOT</version>
+                <executions>
+                    <execution>
+                        <id>archive-kar</id>
+                        <goals>
+                            <goal>archive-kar</goal>
+                        </goals>
+                        <configuration>
+                            <featuresFile>src/main/resources/features.xml</featuresFile>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>
+{code}
+
+For the example, the features descriptor is very simple:
+
+{code}
+<?xml version="1.0" encoding="UTF-8"?>
+<features>
+
+   <feature name="my" version="1.0">
+      <bundle>mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.commons-collections/3.2.1_1</bundle>
+   </feature>
+
+</features>
+{code}
+
+To create the kar archive, simply type:
+
+{code}
+mvn install
+{code}
+
+and you will have your kar in the {{target}} directory.
+
+h2. Deploy a kar archive
+
+Karaf provides a KAR deployer:
+
+{code}
+karaf@root> la|grep -i archive
+[  12] [Active     ] [Created     ] [   30] Apache Karaf :: Deployer :: Karaf Archive (.kar) (2.99.99.SNAPSHOT)
+{code}
+
+It's a core deployer (you don't need to install additional features).
+
+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.
+
+The KAR Deployer creates a repository dedicated to your kar (in the ${KARAF_HOME}/local-repo) and register the features
+descriptor. You can now see your feature available for installation:
+
+{code}
+karaf@root> features:list|grep -i my
+[uninstalled] [1.0             ] my                            repo-0
+{code}
+
+Now you can use any commands available on features:
+
+{code}
+karaf@root> features:install my
+{code}
\ No newline at end of file