• User's Guide
  • Installation
  • Directory structure
  • Starting and stopping Karaf
  • Using the console
  • Web console
  • Remote console
  • Child instances
  • Security
  • Failover deployments
  • Logging system
  • Deployer
  • Configuration

Deployer

The following picture describes the architecture of the deployer.

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 generated OSGi manifest will contain the following headers:

Manifest-Version: 2
Bundle-SymbolicName: [name of the file]
Bundle-Version: [version of the file]
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 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:

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  <manifest xmlns="http://karaf.apache.org/xmlns/deployer/blueprint/v1.0.0">
    Require-Bundle= my-bundle
  </manifest>

Spring deployer

Similar to the blueprint deployer, you can deploy spring-dm configuration files.

The generated OSGi manifest will contain the following headers:

Manifest-Version: 2
Bundle-SymbolicName: [name of the file]
Bundle-Version: [version of the file]
Spring-Context: *;publish-context:=false;create-asynchronously:=true
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:

<spring:beans ...>
  <manifest xmlns="http://karaf.apache.org/xmlns/deployer/spring/v1.0.0">
    Require-Bundle= my-bundle
  </manifest>

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:

<features>
  <repository>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0/xml/features</repository>
  <feature name="nmr-only">
    <feature>nmr</feature>
  </feature>
</features>

For more informations about features, see the provisioning section.

War deployer

To be able to hot deploy web application (war) from the deploy folder, you have to install the war feature:

karaf@root> features:install war

NB: you can use the -v or --verbose option to see exactly what is performed by the feature deployer.

karaf@root> features:install -v war
Installing feature war 2.1.99-SNAPSHOT
Installing feature http 2.1.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.1.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.shell/org.apache.karaf.shell.web/2.1.99-SNAPSHOT
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.

You should now be able to see the PAX Web war deployer:

karaf@root> osgi: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.

Wrap deployer

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):

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 (2.1.99.SNAPSHOT)

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 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.

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)

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:

karaf@root> osgi:headers 41

commons-lang (41)
-----------------
Specification-Title = Commons Lang
Tool = Bnd-0.0.357
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
Implementation-Vendor-Id = org.apache
Created-By = 1.6.0_21 (Sun Microsystems Inc.)
Implementation-Title = Commons Lang
Manifest-Version = 1.0
Bnd-LastModified = 1297248243231
X-Compile-Target-JDK = 1.1
Originally-Created-By = 1.3.1_09-85 ("Apple Computer, Inc.")
Ant-Version = Apache Ant 1.6.5
Package = org.apache.commons.lang
X-Compile-Source-JDK = 1.3
Extension-Name = commons-lang
Implementation-Vendor = Apache Software Foundation

Bundle-Name = commons-lang
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

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 '&'.

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.

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.

<bundle>wrap:mvn:jboss/jbossall-client/4.3.2.GA/$Bundle-SymbolicName=jbossall-client&undle-Version=4.3.2.GA&xport-Package=org.jboss.remoting;version=".3.2.GA"!*</bundle>