| // |
| // Licensed 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. |
| // |
| |
| === Deployers |
| |
| The following picture describes the architecture of the deployers. |
| |
| Apache Karaf polls the `deploy` folder for new files. |
| |
| You can configure the location of the `deploy` folder, and the polling behaviour in the `etc/org.apache.felix.fileinstall-deploy.cfg` |
| 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.log.level = 3 |
| ---- |
| |
| * `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 fly". |
| * Optionally, WAR deployer (if you install the war feature) is able to handle WAR files. |
| |
| ==== Blueprint deployer |
| |
| The Blueprint deployer is able to handle plain Blueprint XML configuration files. |
| |
| The Blueprint deployer is able to transform "on the fly" any Blueprint XML file 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 blueprint 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 |
| |
| The Spring deployer is similar to the Blueprint deployer. |
| |
| 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 |
| 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 a 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 |
| |
| See the link:provisioning[Provisioning section] for details. |
| |
| ==== KAR deployer |
| |
| See the link:kar[KAR section] for details. |
| |
| ==== War deployer |
| |
| The installation of the WAR feature enables a WAR deployer. |
| |
| 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). |
| |
| You can install the war feature with: |
| |
| ---- |
| karaf@root()> feature:install war |
| ---- |
| |
| The WAR deployer supports: |
| |
| * WAB files |
| * WAR files |
| * exploded WAR (as a directory named `*.war`). |
| |
| The only requirement of the WAR deployer is that the archive contains the `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. |
| |
| The wrap deployer creates "on the fly" an OSGi bundle with a non-OSGi jar file. |
| |
| 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. |
| |
| The wrap deployer "transforms" non-OSGi jar file into an OSGi bundle. |
| |
| 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 |
| 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: |
| |
| ---- |
| karaf@root()> bundle:headers 80 |
| |
| commons-lang (80) |
| ----------------- |
| Specification-Title = Commons Lang |
| Tool = Bnd-2.1.0.20130426-122213 |
| Specification-Version = 2.3 |
| Specification-Vendor = Apache Software Foundation |
| Implementation-Version = 2.3 |
| Generated-By-Ops4j-Pax-From = wrap:file:/opt/apache-karaf-4.0.0/deploy/commons-lang-2.3.jar$Bundle-SymbolicName=commons-lang&Bundle-Version=2.3 |
| Implementation-Vendor-Id = org.apache |
| Created-By = 1.7.0_21 (Oracle Corporation) |
| Implementation-Title = Commons Lang |
| Manifest-Version = 1.0 |
| 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 |
| 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 |
| |
| Export-Package = |
| 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 can specify some MANIFEST headers by specifying the headers as URL parameters. |
| |
| In the URL parameters, you can specify the headers using the '$' character and '&' to separate the different headers. |
| For instance: |
| |
| ---- |
| 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: |
| |
| ---- |
| <bundle>wrap:mvn:jboss/jbossall-client/4.3.2.GA/$Bundle-SymbolicName=jbossall-client&Bundle-Version=4.3.2.GA&Export-Package=org.jboss.remoting;version="4.3.2.GA",!*</bundle> |
| ---- |