karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1548538 - in /karaf/trunk/manual/src/main/webapp: _navigation.conf manual.conf users-guide/deployers.conf users-guide/index.conf users-guide/kar.conf users-guide/provisioning.conf
Date Fri, 06 Dec 2013 14:37:45 GMT
Author: jbonofre
Date: Fri Dec  6 14:37:44 2013
New Revision: 1548538

URL: http://svn.apache.org/r1548538
[KARAF-2511] Review and udpdate the deployers page of the user guide


Modified: karaf/trunk/manual/src/main/webapp/_navigation.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/_navigation.conf?rev=1548538&r1=1548537&r2=1548538&view=diff
--- karaf/trunk/manual/src/main/webapp/_navigation.conf (original)
+++ karaf/trunk/manual/src/main/webapp/_navigation.conf Fri Dec  6 14:37:44 2013
@@ -15,8 +15,8 @@ h3. [Users Guide|/users-guide/index]
 - [Configuration|/users-guide/configuration]
 - [Artifacts repositories and URLs|/users-guide/urls]
 - [Provisioning and features|/users-guide/provisioning]
-- [KAR|/users-guide/kar]
 - [Deployers|/users-guide/deployers]
+- [KAR|/users-guide/kar]
 - [Instances|/users-guide/instances]
 - [Security|/users-guide/security]
 - OBR

Modified: karaf/trunk/manual/src/main/webapp/manual.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/manual.conf?rev=1548538&r1=1548537&r2=1548538&view=diff
--- karaf/trunk/manual/src/main/webapp/manual.conf (original)
+++ karaf/trunk/manual/src/main/webapp/manual.conf Fri Dec  6 14:37:44 2013
@@ -44,8 +44,8 @@ h1. Users Guide

Modified: karaf/trunk/manual/src/main/webapp/users-guide/deployers.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/deployers.conf?rev=1548538&r1=1548537&r2=1548538&view=diff
--- karaf/trunk/manual/src/main/webapp/users-guide/deployers.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/deployers.conf Fri Dec  6 14:37:44 2013
@@ -1,17 +1,63 @@
+h1. Deployers
+The following picture describes the architecture of the deployers.
-h1. Deployer
-The following picture describes the architecture of the deployer.
+Apache Karaf polls the {{deploy}} folder for new files.
+You can configure the location of the {{deploy}} folder, and the polling behaviour in the
+configuration file:
+#    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.
+felix.fileinstall.dir           = ${karaf.base}/deploy
+felix.fileinstall.tmpdir        = ${karaf.data}/generated-bundles
+felix.fileinstall.poll          = 1000
+felix.fileinstall.start.level   = 80
+felix.fileinstall.active.level  = 80
+* {{felix.fileinstall.dir}} defines the location of the {{deploy}} folder. Default value
is {{KARAF_BASE/deploy}}.
+* {{felix.fileinstall.tmpdir}} defines a temporary folder where the deployers store their
files. Default value is {{KARAF_DATA/generated-bundles}}.
+* {{felix.fileinstall.poll}} defines the polling interval (in milliseconds). Default value
is 1 second.
+When Apache Karaf polls a file from the {{deploy}} folder, it "delegates" the file handling
to a deployer.
+By default, Apache Karaf provides a set of deployers:
+* Blueprint deployer is able to handle Blueprint XML files.
+* Spring deployer is able to handle Spring XML files.
+* Features deployer is able to handle Apache Karaf features XML files (see [Provisioning
section|provisioning] for details).
+* KAR deployer is able to handle KAR files (see [KAR section|kar] for details).
+* Wrap deployer is able to handle non-OSGi jar files and turns it as OSGi bundles "on the
+* Optionally, WAR deployer (if you install the war feature) is able to handle WAR files.
 h2. Blueprint deployer
-Karaf includes a deployer that is able to deploy plain blueprint configuration files.
-The deployer will transform on the fly any spring configuration file dropped into the {{deploy}}
folder into a valid OSGi bundle.
+The Blueprint deployer is able to handle plain Blueprint XML configuration files.
-The generated OSGi manifest will contain the following headers:
+The Blueprint deployer is able to transform "on the fly" any Blueprint XML file into valid
OSGi bundle.
+The generated OSGi MANIFEST will contain the following headers:
 Manifest-Version: 2
@@ -21,7 +67,10 @@ Import-Package: [required packages]
 DynamicImport-Package: *
-The {{name}} and {{version}} of the file are extracted using a heuristic that will match
common patterns.  For example {{my-config-1.0.1.xml}} will lead to {{name = my-config}} and
{{version = 1.0.1}}.
+The {{name}} and {{version}} of the file are extracted using a heuristic that will match
common patterns.
+For example {{my-config-1.0.1.xml}} will lead to {{name = my-config}} and {{version = 1.0.1}}.
 The default imported packages are extracted from the spring file definition and includes
all classes referenced directly.
 If you need to customize the generated manifest, you can do so by including an xml element
in your blueprint configuration:
@@ -35,9 +84,11 @@ If you need to customize the generated m
 h2. Spring deployer
-Similar to the blueprint deployer, you can deploy spring-dm configuration files.
+The Spring deployer is similar to the Blueprint deployer.
-The generated OSGi manifest will contain the following headers:
+The Spring deployer is able to deploy Spring XML files.
+Like the Blueprint deployer, the generated OSGi MANIFEST will contain the following headers:
 Manifest-Version: 2
@@ -48,7 +99,7 @@ Import-Package: [required packages]
 DynamicImport-Package: *
-If you need to customize the generated manifest, you can do so by including an xml element
in your spring configuration:
+If you need to customize the generated manifest, you can do so by including a XML element
in your Spring configuration:
 <spring:beans ...>
@@ -59,119 +110,123 @@ If you need to customize the generated m
 h2. Features deployer
-To be able to hot deploy features from the deploy folder, you can just drop a feature descriptor
on that folder.  A bundle will be created and its installation (automatic) will trigger the
installation of all features contained in the descriptor.  Removing the file from the deploy
folder will uninstall the features.
-If you want to install a single feature, you can do so by writing a feature descriptor like
the following:
+See the [Provisioning section|provisioning] for details.
-  <repository>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0/xml/features</repository>
-  <feature name="nmr-only">
-    <feature>nmr</feature>
-  </feature>
+h2. KAR deployer
-For more informations about features, see the [provisioning section|provisioning].
+See the [KAR section|kar] for details.
 h2. War deployer
-To be able to hot deploy web application (war) from the deploy folder, you have to install
the war feature:
+The installation of the WAR feature enables a WAR deployer.
-karaf@root> features:install war
+It means that with the war feature installed, Apache Karaf is a complete OSGi WebContainer
(like Tomcat) where
+you can deploy WAB (WebApplication Bundle) or pure WAR (WebApplication aRchive).
-NB: you can use the -v or --verbose option to see exactly what is performed by the feature
+You can install the war feature with:
-karaf@root> features:install -v war
-Installing feature war 2.99.99-SNAPSHOT
-Installing feature http 2.99.99-SNAPSHOT
-Installing feature jetty 7.2.2.v20101205
-Installing bundle mvn:org.apache.geronimo.specs/geronimo-servlet_2.5_spec/1.1.2
-Found installed bundle: org.apache.servicemix.bundles.asm [9]
-Installing bundle mvn:org.eclipse.jetty/jetty-util/7.2.2.v20101205
-Installing bundle mvn:org.eclipse.jetty/jetty-io/7.2.2.v20101205
-Installing bundle mvn:org.eclipse.jetty/jetty-http/7.2.2.v20101205
-Installing bundle mvn:org.eclipse.jetty/jetty-continuation/7.2.2.v20101205
-Installing bundle mvn:org.eclipse.jetty/jetty-server/7.2.2.v20101205
-Installing bundle mvn:org.eclipse.jetty/jetty-security/7.2.2.v20101205
-Installing bundle mvn:org.eclipse.jetty/jetty-servlet/7.2.2.v20101205
-Installing bundle mvn:org.eclipse.jetty/jetty-xml/7.2.2.v20101205
-Checking configuration file mvn:org.apache.karaf/apache-karaf/2.99.99-SNAPSHOT/xml/jettyconfig
-Installing bundle mvn:org.ops4j.pax.web/pax-web-api/1.0.0
-Installing bundle mvn:org.ops4j.pax.web/pax-web-spi/1.0.0
-Installing bundle mvn:org.ops4j.pax.web/pax-web-runtime/1.0.0
-Installing bundle mvn:org.ops4j.pax.web/pax-web-jetty/1.0.0
-Installing bundle mvn:org.apache.karaf.web/org.apache.karaf.web.core/${project.version}
-Installing bundle mvn:org.apache.karaf.web/org.apache.karaf.web.command/${project.version}
-Installing bundle mvn:org.ops4j.pax.web/pax-web-jsp/1.0.0
-Installing bundle mvn:org.ops4j.pax.web/pax-web-extender-war/1.0.0
-Installing bundle mvn:org.ops4j.pax.web/pax-web-extender-whiteboard/1.0.0
-Installing bundle mvn:org.ops4j.pax.web/pax-web-deployer/1.0.0
-Installing bundle mvn:org.ops4j.pax.url/pax-url-war/1.2.5
-As you can see, the war feature uses PAX Web as war deployer.
+karaf@root()> feature:install -v war
+Installing feature war 3.0.0
+Installing feature pax-war 3.0.5
+Installing feature pax-http-whiteboard 3.0.5
+Installing feature pax-http 3.0.5
+Installing feature pax-jetty 8.1.14.v20131031
+Found installed bundle: org.apache.servicemix.specs.activation-api-1.1 [81]
+Found installed bundle: org.apache.geronimo.specs.geronimo-servlet_3.0_spec [82]
+Found installed bundle: javax.mail [83]
+Found installed bundle: org.apache.geronimo.specs.geronimo-jta_1.1_spec [84]
+Found installed bundle: org.apache.geronimo.specs.geronimo-annotation_1.1_spec [85]
+Found installed bundle: org.apache.geronimo.specs.geronimo-jaspic_1.0_spec [86]
+Found installed bundle: org.apache.servicemix.bundles.asm [87]
+Found installed bundle: org.eclipse.jetty.aggregate.jetty-all-server [88]
+Checking configuration file mvn:org.ops4j.pax.web/pax-web-features/3.0.5/xml/jettyconfig
+Installing bundle mvn:org.ops4j.base/ops4j-base-lang/1.4.0
+Found installed bundle: org.ops4j.pax.swissbox.core [89]
+Found installed bundle: org.ops4j.pax.swissbox.optional.jcl [90]
+Found installed bundle: org.apache.xbean.bundleutils [91]
+Found installed bundle: org.apache.xbean.asm-shaded [92]
+Found installed bundle: org.apache.xbean.reflect [93]
+Found installed bundle: org.apache.xbean.finder-shaded [94]
+Found installed bundle: org.ops4j.pax.web.pax-web-api [95]
+Found installed bundle: org.ops4j.pax.web.pax-web-spi [96]
+Found installed bundle: org.ops4j.pax.web.pax-web-runtime [97]
+Found installed bundle: org.ops4j.pax.web.pax-web-jetty [98]
+Found installed bundle: org.ops4j.pax.web.pax-web-jsp [99]
+Found installed bundle: org.ops4j.pax.web.pax-web-extender-whiteboard [100]
+Installing bundle mvn:org.ops4j.pax.web/pax-web-jsp/3.0.5
+Found installed bundle: org.ops4j.pax.web.pax-web-extender-war [101]
+Installing bundle mvn:org.ops4j.pax.web/pax-web-extender-whiteboard/3.0.5
+Found installed bundle: org.ops4j.pax.web.pax-web-deployer [102]
+Found installed bundle: org.ops4j.pax.url.war [103]
+Found installed bundle: org.ops4j.pax.url.commons [104]
+Found installed bundle: org.ops4j.pax.swissbox.pax-swissbox-bnd [105]
+Found installed bundle: org.ops4j.pax.swissbox.property [106]
+Installing bundle mvn:org.ops4j.base/ops4j-base-net/1.4.0
+Installing bundle mvn:org.ops4j.base/ops4j-base-lang/1.4.0
+Installing bundle mvn:org.ops4j.base/ops4j-base-monitors/1.4.0
+Installing bundle mvn:org.ops4j.base/ops4j-base-util-property/1.4.0
+Found installed bundle: biz.aQute.bndlib [107]
+Found installed bundle: org.apache.karaf.web.core [108]
+Found installed bundle: org.apache.karaf.web.command [109]
+We can note that the Pax Web deployer (WAR deployer) has been started:
+Found installed bundle: org.ops4j.pax.web.pax-web-deployer [102]
+The WAR deployer supports:
+* WAB files
+* WAR files
+* exploded WAR (as a directory named {{*.war}}).
-You should now be able to see the PAX Web war deployer:
-karaf@root> bundles:list |grep -i war
-[  57] [Active     ] [            ] [   60] OPS4J Pax Web - Extender - WAR (1.0.0)
-[  60] [Active     ] [            ] [   60] OPS4J Pax Url - war:, war-i: (1.2.5)
-You can deploy a web application packaged in war or exploded in a directory.
-Your web application should at least contain a WEB-INF/web.xml file.
+The only requirement of the WAR deployer is that the archive contains the {{WEB-INF/web.xml}}
 h2. Wrap deployer
-The wrap deployer allows you to hot deploy non-OSGi jar files ("classical" jar files) from
the deploy folder.
+The wrap deployer allows you to "hot deploy" non-OSGi jar files ("classical" jar files) from
the deploy folder.
-It's a standard deployer (you don't need to install additional Karaf features):
+The wrap deployer creates "on the fly" an OSGi bundle with a non-OSGi jar file.
-karaf@root> la|grep -i wrap
-[   1] [Active     ] [            ] [    5] OPS4J Pax Url - wrap: (1.2.5)
-[  32] [Active     ] [Created     ] [   30] Apache Karaf :: Deployer :: Wrap Non OSGi Jar
+The wrap deployer looks for jar files in the deploy folder. A jar file is considered as non-OSGi
if the MANIFEST doesn't
+contain the {{Bundle-SymbolicName}} and {{Bundle-Version}} attributes, or if there is no
MANIFEST at all.
-Karaf wrap deployer looks for jar files in the deploy folder. The jar files is considered
as non-OSGi if the MANIFEST
-doesn't contain the Bundle-SymbolicName and Bundle-Version attributes, or if there is no
MANIFEST at all.
+The wrap deployer "transforms" non-OSGi jar file into an OSGi bundle.
-The non-OSGi jar file is transformed into an OSGi bundle.
-The deployer tries to populate the Bundle-SymbolicName and Bundle-Version extracted from
the jar file path.
+The wrap deployer tries to populate the Bundle-SymbolicName and Bundle-Version extracted
from the jar file path.
 For example, if you simply copy commons-lang-2.3.jar (which is not an OSGi bundle) into the
deploy folder, you
 will see:
-karaf@root> la|grep -i commons-lang
-[  41] [Active     ] [            ] [   60] commons-lang (2.3)
+karaf@root()> la|grep -i commons-lang
+80 | Active   |  80 | 2.3                   | commons-lang
 If you take a look on the commons-lang headers, you can see that the bundle exports all packages
with optional resolution
-and that Bundle-SymbolicName and Bundle-Version have been populated:
+and that {{Bundle-SymbolicName}} and {{Bundle-Version}} have been populated:
-karaf@root> bundles:headers 41
+karaf@root()> bundle:headers 80
-commons-lang (41)
+commons-lang (80)
 Specification-Title = Commons Lang
-Tool = Bnd-0.0.357
+Tool = Bnd-
 Specification-Version = 2.3
 Specification-Vendor = Apache Software Foundation
 Implementation-Version = 2.3
-Generated-By-Ops4j-Pax-From = wrap:file:/home/onofreje/workspace/karaf/assembly/target/apache-karaf-2.99.99-SNAPSHOT/deploy/commons-lang-2.3.jar$Bundle-SymbolicName=commons-lang&Bundle-Version=2.3
+Generated-By-Ops4j-Pax-From = wrap:file:/opt/apache-karaf-3.0.0/deploy/commons-lang-2.3.jar$Bundle-SymbolicName=commons-lang&Bundle-Version=2.3
 Implementation-Vendor-Id = org.apache
-Created-By = 1.6.0_21 (Sun Microsystems Inc.)
+Created-By = 1.7.0_21 (Oracle Corporation)
 Implementation-Title = Commons Lang
 Manifest-Version = 1.0
-Bnd-LastModified = 1297248243231
+Bnd-LastModified = 1386339925753
 X-Compile-Target-JDK = 1.1
 Originally-Created-By = 1.3.1_09-85 ("Apple Computer, Inc.")
 Ant-Version = Apache Ant 1.6.5
@@ -185,45 +240,33 @@ Bundle-SymbolicName = commons-lang
 Bundle-Version = 2.3
 Bundle-ManifestVersion = 2
-Import-Package =
-        org.apache.commons.lang;resolution:=optional,
-        org.apache.commons.lang.builder;resolution:=optional,
-        org.apache.commons.lang.enum;resolution:=optional,
-        org.apache.commons.lang.enums;resolution:=optional,
-        org.apache.commons.lang.exception;resolution:=optional,
-        org.apache.commons.lang.math;resolution:=optional,
-        org.apache.commons.lang.mutable;resolution:=optional,
-        org.apache.commons.lang.text;resolution:=optional,
-        org.apache.commons.lang.time;resolution:=optional
 Export-Package =
-        org.apache.commons.lang;uses:="org.apache.commons.lang.builder,org.apache.commons.lang.math,org.apache.commons.lang.exception",
-        org.apache.commons.lang.builder;uses:="org.apache.commons.lang.math,org.apache.commons.lang",
-        org.apache.commons.lang.enum;uses:=org.apache.commons.lang,
-        org.apache.commons.lang.enums;uses:=org.apache.commons.lang,
-        org.apache.commons.lang.exception;uses:=org.apache.commons.lang,
-        org.apache.commons.lang.math;uses:=org.apache.commons.lang,
-        org.apache.commons.lang.mutable;uses:="org.apache.commons.lang,org.apache.commons.lang.math",
-        org.apache.commons.lang.text;uses:=org.apache.commons.lang,
-        org.apache.commons.lang.time;uses:=org.apache.commons.lang
+        org.apache.commons.lang;uses:=org.apache.commons.lang.exception,
+        org.apache.commons.lang.builder,
+        org.apache.commons.lang.enum,
+        org.apache.commons.lang.enums,
+        org.apache.commons.lang.exception,
+        org.apache.commons.lang.math,
+        org.apache.commons.lang.mutable,
+        org.apache.commons.lang.text,
+        org.apache.commons.lang.time,
+        org,
+        org.apache,
+        org.apache.commons
-You may set the manifest headers by specifying them as URL parameters, '$' is used separate
the hierarch path and query parts of the URL, with standard URL syntax for query parameters
of key=value pairs joined by '&'.
+You can specify some MANIFEST headers by specifying the headers as URL parameters.
-On the command line you must use single quotes around the URL to prevent the shell from attempting
variable expansion, and if present, you must escape exclamation marks with a backslash.
+In the URL parameters, you can specify the headers using the '$' character and '&' to
separate the different headers.
+For instance:
-install -s 'wrap:mvn:jboss/jbossall-client/4.2.3.GA/$Bundle-SymbolicName=jbossall-client&Bundle-Version=4.2.3.GA&Export-Package=org.jboss.remoting;version="4.2.3.GA",\!*'
+karaf@root()> bundle:install -s 'wrap:mvn:jboss/jbossall-client/4.2.3.GA/$Bundle-SymbolicName=jbossall-client&Bundle-Version=4.2.3.GA&Export-Package=org.jboss.remoting;version="4.2.3.GA",\!*'
-When defined in a features.xml file, it's necessary to escape any ampersands and quotes,
or use a CDATA tag.
+When defined in a features.xml file, it's necessary to escape any ampersands and quotes,
or use a CDATA tag:
-h2. Kar deployer
-The Kar deploy allows you to deploy KAR archive (Karaf ARchive). See the {kar} section of
this user guide.
\ No newline at end of file

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=1548538&r1=1548537&r2=1548538&view=diff
--- karaf/trunk/manual/src/main/webapp/users-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/index.conf Fri Dec  6 14:37:44 2013
@@ -10,8 +10,8 @@ h1. Users Guide
 * [Configuration|configuration]
 * [Artifacts repositories and URLs|urls]
 * [Provisioning and features|provisioning]
-* [KAR|kar]
 * [Deployers|deployers]
+* [KAR|kar]
 * [Instances|instances]
 * [Security|security]
 * OBR

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=1548538&r1=1548537&r2=1548538&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 14:37:44 2013
@@ -8,7 +8,7 @@ configuration files, ...) in the artifac
 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).
+of this XML. This artifact is named a KAR (KAraf aRchive).
 A KAR file is a zip archive containing the

Modified: karaf/trunk/manual/src/main/webapp/users-guide/provisioning.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/provisioning.conf?rev=1548538&r1=1548537&r2=1548538&view=diff
--- karaf/trunk/manual/src/main/webapp/users-guide/provisioning.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/provisioning.conf Fri Dec  6 14:37:44 2013
@@ -500,6 +500,26 @@ If only the name of the feature is provi
 karaf@root()> feature:uninstall eventadmin
+h2. Deployer
+You can "hot deploy" a features XML by dropping the file directly in the {{deploy}} folder.
+Apache Karaf provides a features deployer.
+The features deployer handles the features XML files dropped into the {{deploy}} folder and
automatically register and
+install all features described in the features XML.
+If you want to install a single feature, you can do so by writing a feature descriptor like
the following:
+  <repository>mvn:groupId/artifactId/1.0.0/xml/features</repository>
+  <feature name="target">
+    <feature>target</feature>
+  </feature>
 h2. JMX FeatureMBean
 On the JMX layer, you have a MBean dedicated to the management of the features and features
repositories: the FeatureMBean.

View raw message