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 2015/12/20 08:47:12 UTC

svn commit: r1720992 [7/8] - in /karaf/site/production/manual/latest: ./ commands/ developers-guide/ users-guide/

Modified: karaf/site/production/manual/latest/developers-guide/writing-tests.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/developers-guide/writing-tests.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/developers-guide/writing-tests.html (original)
+++ karaf/site/production/manual/latest/developers-guide/writing-tests.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>
@@ -101,7 +101,7 @@
               </td>
               <td height="100%" width="100%">
                 <div class="wiki-content">
-<h1 id="Writingintegrationtests">Writing integration tests</h1><p>We recommend using <a href="http://team.ops4j.org/wiki/display/paxexam/Pax+Exam">PAX Exam</a> to write integration tests when developing applications using Karaf.</p><p>Starting with Karaf 3.0 we've also included a component briding between Karaf and Pax Exam making it easier to write integration tests for Karaf or Karaf based Distributions such as <a href="http://servicemix.apache.org">Servicemix</a> or <a href="http://geronimo.apache.org">Geronimo</a>.</p><h2 id="Introduction">Introduction</h2><p>To make use of this new framework simply add the following dependencies into your integration tests pom.xml:</p><div class="syntax"><div class="highlight"><pre><span class="c">&lt;!-- Karaf Test Framework Version --&gt;</span>&#x000A;<span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.karaf.tooling.exam<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;ar
 tifactId&gt;</span>org.apache.karaf.tooling.exam.container<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;version&gt;</span>4.0.2-SNAPSHOT<span class="nt">&lt;/version&gt;</span>&#x000A;  <span class="nt">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;<span class="c">&lt;!-- Pax Exam version you would like to use. At least 2.2.x is required. --&gt;</span>&#x000A;<span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.ops4j.pax.exam<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>pax-exam-junit4<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;version&gt;</span>4.5.0<span class="nt">&lt;/version&gt;</span>&#x000A;  <span class="nt">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;</pre></div>&#x000A;</div><p>As
  a next step you need to reference the distribution you want to run your tests on. For example, if you want to run your tests on Karaf the following section would be required in the integration tests pom.xml:</p><div class="syntax"><div class="highlight"><pre><span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.karaf<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>apache-karaf<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;version&gt;</span>4.0.2-SNAPSHOT<span class="nt">&lt;/version&gt;</span>&#x000A;  <span class="nt">&lt;type&gt;</span>zip<span class="nt">&lt;/type&gt;</span>&#x000A;  <span class="nt">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;</pre></div>&#x000A;</div><p>If you want to make use of Exams "versionAsInProject" feature you also need to add the following section:</p><div cla
 ss="syntax"><div class="highlight"><pre><span class="nt">&lt;build&gt;</span>&#x000A;  <span class="nt">&lt;plugins&gt;</span>&#x000A;    <span class="nt">&lt;plugin&gt;</span>&#x000A;      <span class="nt">&lt;groupId&gt;</span>org.apache.servicemix.tooling<span class="nt">&lt;/groupId&gt;</span>&#x000A;      <span class="nt">&lt;artifactId&gt;</span>depends-maven-plugin<span class="nt">&lt;/artifactId&gt;</span>&#x000A;      <span class="nt">&lt;version&gt;</span>1.2<span class="nt">&lt;/version&gt;</span>&#x000A;      <span class="nt">&lt;executions&gt;</span>&#x000A;        <span class="nt">&lt;execution&gt;</span>&#x000A;          <span class="nt">&lt;id&gt;</span>generate-depends-file<span class="nt">&lt;/id&gt;</span>&#x000A;          <span class="nt">&lt;goals&gt;</span>&#x000A;            <span class="nt">&lt;goal&gt;</span>generate-depends-file<span class="nt">&lt;/goal&gt;</span>&#x000A;          <span class="nt">&lt;/goals&gt;</span>&#x000A;        <span class="nt">&lt;/
 execution&gt;</span>&#x000A;      <span class="nt">&lt;/executions&gt;</span>&#x000A;    <span class="nt">&lt;/plugin&gt;</span>&#x000A;  <span class="nt">&lt;/plugins&gt;</span>&#x000A;<span class="nt">&lt;/build&gt;</span>&#x000A;</pre></div>&#x000A;</div><p>With this done we can start writing our first test case:</p><div class="syntax"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">static</span> <span class="n">junit</span><span class="o">.</span><span class="na">framework</span><span class="o">.</span><span class="na">Assert</span><span class="o">.</span><span class="na">assertTrue</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">static</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">karaf</span><span class="o">.</span><span class="na">tooling</span><span class="o">.</span><span class="na">exam</span><span class="o">.</span><span class
 ="na">options</span><span class="o">.</span><span class="na">KarafDistributionOption</span><span class="o">.</span><span class="na">karafDistributionConfiguration</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">static</span> <span class="n">org</span><span class="o">.</span><span class="na">ops4j</span><span class="o">.</span><span class="na">pax</span><span class="o">.</span><span class="na">exam</span><span class="o">.</span><span class="na">CoreOptions</span><span class="o">.</span><span class="na">maven</span><span class="o">;</span>&#x000A;&#x000A;<span class="kn">import</span> <span class="nn">org.junit.Test</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.junit.runner.RunWith</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.Option</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.Con
 figuration</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.ExamReactorStrategy</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.JUnit4TestRunner</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.spi.reactors.AllConfinedStagedReactorFactory</span><span class="o">;</span>&#x000A;&#x000A;<span class="nd">@RunWith</span><span class="o">(</span><span class="n">JUnit4TestRunner</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>&#x000A;<span class="nd">@ExamReactorStrategy</span><span class="o">(</span><span class="n">AllConfinedStagedReactorFactory</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>&#x000A;<span class="kd">public</span> <span class="kd">class</span> <span class="nc">VersionAsInProjectKarafTest</span> <span class="o">{</span>&#x000A
 ;&#x000A;    <span class="nd">@Configuration</span>&#x000A;    <span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;        <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">().</span><span class="na">frameworkUrl</span><span class="o">(</span>&#x000A;            <span class="n">maven</span><span class="o">().</span><span class="na">groupId</span><span class="o">(</span><span class="s">&quot;org.apache.karaf&quot;</span><span class="o">).</span><span class="na">artifactId</span><span class="o">(</span><span class="s">&quot;apache-karaf&quot;</span><span class="o">).</span><span class="na">type</span><span class="o">(</span><span class="s">&quot;zip&quot;</span><span class="o">).</span><span class="na">versionAsInProject</span><span cl
 ass="o">())</span>&#x000A;            <span class="o">.</span><span class="na">karafVersion</span><span class="o">(</span><span class="s">&quot;2.2.4&quot;</span><span class="o">).</span><span class="na">name</span><span class="o">(</span><span class="s">&quot;Apache Karaf&quot;</span><span class="o">)};</span>&#x000A;    <span class="o">}</span>&#x000A;&#x000A;    <span class="nd">@Test</span>&#x000A;    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">test</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span>&#x000A;        <span class="n">assertTrue</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>&#x000A;    <span class="o">}</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h2 id="Commands">Commands</h2><p>Basically the Pax Exam - Karaf bridge introduced with 3.0 should support all commands you know from Pax Exam 2.x. In additio
 n we've added various additional commands to make your life easier. Those commands are listed and explained in this sub section.</p><p>As a small remark: All of the Options explained here are also accessible via the static methods in the KarafDistributionOption class in the options package automatically on your classpath when you reference the container package.</p><h3 id="KarafDistributionConfigurationOption">KarafDistributionConfigurationOption</h3><p>The framework itself is non of the typical runtimes you define normally in PAXEXAM. Instead you define a packed distribution as zip or tar.gz. Those distributions have to follow the Karaf packaging style. Therefore instead of Karaf you can also enter Servicemix or Geronimo.</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurationOption</span><span class="o">(</span>&#x000A;  <span class="s">&quot;mvn:org.apache.karaf/apache-karaf/2.2.4/zip&quot;</span><span class="o
 ">,</span> <span class="c1">// artifact to unpack and use</span>&#x000A;  <span class="s">&quot;karaf&quot;</span><span class="o">,</span> <span class="c1">// name; display only</span>&#x000A;  <span class="s">&quot;2.2.4&quot;</span><span class="o">)</span> <span class="c1">// the karaf version; this one is relevant since the startup script differs between versions</span>&#x000A;</pre></div>&#x000A;</div><p>or for Servicemix e.g.</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurationOption</span><span class="o">(</span>&#x000A;  <span class="s">&quot;mvn:org.apache.servicemix/apache-servicemix/4.4.0/zip&quot;</span><span class="o">,</span> <span class="c1">// artifact to unpack and use</span>&#x000A;  <span class="s">&quot;servicemix&quot;</span><span class="o">,</span> <span class="c1">// name; display only</span>&#x000A;  <span class="s">&quot;2.2.4&quot;</span><span class="o">)</span> <span class="c1">// the 
 karaf version; this one is relevant since the startup script differs between versions</span>&#x000A;</pre></div>&#x000A;</div><p>As an alternative you can also use the maven url resolvers. Please keep in mind that this only works starting with karaf-3.0.0 since there will be problems with the pax-url version. In addition, if you want to make use of the versionAsInProject part you also need to define the following maven-plugin in the pom file of your integration tests:</p><div class="syntax"><div class="highlight"><pre>...&#x000A;<span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.karaf<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>apache-karaf<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;type&gt;</span>zip<span class="nt">&lt;/type&gt;</span>&#x000A;  <span class="nt">&lt;classifier&gt;</span>bin<span class="nt">&lt;/classifier&gt;</span>&#x000A;  <span class="n
 t">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;...&#x000A;<span class="nt">&lt;plugin&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.servicemix.tooling<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>depends-maven-plugin<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;executions&gt;</span>&#x000A;    <span class="nt">&lt;execution&gt;</span>&#x000A;      <span class="nt">&lt;id&gt;</span>generate-depends-file<span class="nt">&lt;/id&gt;</span>&#x000A;      <span class="nt">&lt;goals&gt;</span>&#x000A;        <span class="nt">&lt;goal&gt;</span>generate-depends-file<span class="nt">&lt;/goal&gt;</span>&#x000A;      <span class="nt">&lt;/goals&gt;</span>&#x000A;    <span class="nt">&lt;/execution&gt;</span>&#x000A;  <span class="nt">&lt;/executions&gt;</span>&#x000A;<span class="nt">&lt;/plugin&gt;</span>&#x000A;</pre><
 /div>&#x000A;</div><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;    <span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;        <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">().</span><span class="na">frameworkUrl</span><span class="o">(</span>&#x000A;            <span class="n">maven</span><span class="o">().</span><span class="na">groupId</span><span class="o">(</span><span class="s">&quot;org.apache.karaf&quot;</span><span class="o">).</span><span class="na">artifactId</span><span class="o">(</span><span class="s">&quot;apache-karaf&quot;</span><span class="o">).</span><span class="na">type</span><span class="o">(</span><span class="s">&quot;zip&quot;</span><span class="o">)</sp
 an>&#x000A;                <span class="o">.</span><span class="na">classifier</span><span class="o">(</span><span class="s">&quot;bin&quot;</span><span class="o">).</span><span class="na">versionAsInProject</span><span class="o">())</span> <span class="o">};</span>&#x000A;    <span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><p>In addition to the framework specification options this option also includes various additional configuration options. Those options are used to configure the internal properties of the runtime environment.</p><h4 id="UnpackDirectory">Unpack Directory</h4><p>Paxexam-Karaf Testframework extracts the distribution you specify by default into the paxexam config directory. If you would like to unpack them into your target directory simply extend the KarafDistributionConfigurationOption with the unpackDirectoryFile like shown in the next example:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="k
 d">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">)</span>&#x000A;        <span class="o">.</span><span class="na">unpackDirectory</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">&quot;target/paxexam/unpack/&quot;</span><span class="o">))</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h4 id="UseDeployFolder">Use Deploy Folder</h4><p>Karaf distributions come by default with a deploy folder where you can simply drop artifacts to be deployed. In some distributi
 ons this folder might have been removed. To still be able to deploy your additional artifacts using default Pax Exam ProvisionOptions you can configure PaxExam Karaf to use a features.xml (which is directly added to your etc/org.apache.karaf.features.cfg) for those deploys. To use it instead of the deploy folder simply do the following:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">)</span>&#x000A;        <span class="o">.</span><span class="na">useDeployFolder</span><sp
 an class="o">(</span><span class="kc">false</span><span class="o">))</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="KarafDistributionKitConfigurationOption">KarafDistributionKitConfigurationOption</h3><p>The KarafDistributionKitConfigurationOption is almost equal to all variations of the KarafDistributionConfigurationOption with the exception that it requires to have set a platform and optionally the executable and the files which should be made executable additionally. By default it is bin/karaf for nix platforms and bin\karaf.bat for windows platforms. The executable option comes in handy if you like to e.g. embed an own java runtime. You should add a windows AND a linux Kit definition. The framework automatically takes the correct one then. The following shows a simple example for karaf:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span cl
 ass="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span>&#x000A;        <span class="k">new</span> <span class="nf">KarafDistributionKitConfigurationOption</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">,</span>&#x000A;            <span class="n">Platform</span><span class="o">.</span><span class="na">WINDOWS</span><span class="o">).</span><span class="na">executable</span><span class="o">(</span><span class="s">&quot;bin\\karaf.bat&quot;</span><span class="o">).</span><span class="na">filesToMakeExecutable</span><span class="o">(</span><span class="s">&quot;bin\\admin.bat&quot;</span><span class="o">),</span>&#x000A;        <span class="k">new</span> <span class="nf">KarafDistributionKitConfigurationOption
 </span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/tar.gz&quot;</span><span class="o">,</span> <span class="s">&quot;karaf&quot;</span><span class="o">,</span>&#x000A;            <span class="n">Platform</span><span class="o">.</span><span class="na">NIX</span><span class="o">).</span><span class="na">executable</span><span class="o">(</span><span class="s">&quot;bin/karaf&quot;</span><span class="o">).</span><span class="na">filesToMakeExecutable</span><span class="o">(</span><span class="s">&quot;bin/admin&quot;</span><span class="o">)</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="KarafDistributionConfigurationFilePutOption">KarafDistributionConfigurationFilePutOption</h3><p>The option replaces or adds an option to one of Karaf's configuration files:</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurati
 onFilePutOption</span><span class="o">(</span>&#x000A;  <span class="s">&quot;etc/config.properties&quot;</span><span class="o">,</span> <span class="c1">// config file to modify based on karaf.base</span>&#x000A;  <span class="s">&quot;karaf.framework&quot;</span><span class="o">,</span> <span class="c1">// key to add or change</span>&#x000A;  <span class="s">&quot;equinox&quot;</span><span class="o">)</span> <span class="c1">// value to add or change</span>&#x000A;</pre></div>&#x000A;</div><p>This option could also be used in "batch-mode" via a property file. Therefore use the KarafDistributionOption#editConfigurationFilePut(final String configurationFilePath, File source, String... keysToUseFromSource) method. This option allows you to add all properties found in the file as KarafDistributionConfigurationFilePutOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily put an entire range of properties.</p><h3 id="
 KarafDistributionConfigurationFileExtendOption">KarafDistributionConfigurationFileExtendOption</h3><p>This one does the same as the KarafDistributionConfigurationFilePutOption option with the one difference that it either adds or appends a specific property. This is especially useful if you do not want to store the entire configuration in the line in your code.</p><p>This option could also be extended in "batch-mode" via a property file. Therefore use the KarafDistributionOption#editConfigurationFileExtend(final String configurationFilePath, File source, String... keysToUseFromSource) method. This option allows you to extend all properties found in the file as KarafDistributionConfigurationFileExtendOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily extend an entire range of properties.</p><h3 id="KarafDistributionConfigurationFileReplacementOption">KarafDistributionConfigurationFileReplacementOption</h3><p>Th
 e file replacement option allows you to simply replace a file in you Karaf distribution with a different file:</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurationFileReplacementOption</span><span class="o">(</span><span class="s">&quot;etc/tests.cfg&quot;</span><span class="o">,</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span>&#x000A;    <span class="s">&quot;src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey&quot;</span><span class="o">));</span>&#x000A;</pre></div>&#x000A;</div><h3 id="ProvisionOption">ProvisionOption</h3><p>The new test container fully supports the provision option. Feel free to use any option provided here by paxexam itself (e.g. Maven resolver). All those artifacts are copied into the deploy folder of your Karaf distribution before it is started. Therefore they all will be available after startup.</p><h3 id="KarafDistribut
 ionConfigurationConsoleOption">KarafDistributionConfigurationConsoleOption</h3><p>The test container supports options to configure if the localConsole and/or the remote shell should be started. Possible options to do so are shown in the following two examples:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">configureConsole</span><span class="o">().</span><span class="na">ignoreLocalConsole</span><span class="o">().</span><span cla
 ss="na">startRemoteShell</span><span class="o">()</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">configureConsole</span><span class="o">().</span><span class="na">startLocalConsole</span><span class="o">(),</span> <span class="n">configureConsole</span><span class="o">().</span><span class="na">ignoreRemoteShell</span><span class="o">()<
 /span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="VMOption">VMOption</h3><p>The Karaf container passes the vmOptions now through to the Karaf environment. They are directly passed to the startup of the container. In addition the KarafDistributionOption helper has two methods (debugConfiguration() and debugConfiguration(String port, boolean hold)) to activate debugging quickly.</p><h3 id="LogLevelOption">LogLevelOption</h3><p>The Paxexam-Karaf specific log-level option allows an easy way to set a specific log-level for the Karaf based distribution. For example simply add the following to your Option[] array to get TRACE logging:</p><div class="syntax"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">static</span> <span class="n">org</span><span class="o">.</span><span class="na">openengsb</span><span class="o">.</span><span class="na">labs</span><span class="o">.</span><span class="na">paxexam</span><s
 pan class="o">.</span><span class="na">karaf</span><span class="o">.</span><span class="na">options</span><span class="o">.</span><span class="na">KarafDistributionOption</span><span class="o">.</span><span class="na">logLevel</span><span class="o">;</span>&#x000A;<span class="o">...</span>&#x000A;<span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">logLevel</span><span class="o">(</span><span class="n">LogLevel</span><span class="o">.</span><span class="na">TRACE</span><span class="o">
 )</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="DoNotModifyLogOption">DoNotModifyLogOption</h3><p>The option to modify the logging behavior requires that the container automatically modifies the logging configuration file. If you would like to suppress this behavior simply set the doNotModifyLogConfiguration option as shown in the next example:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">),</span> &#x000A;    
     <span class="n">doNotModifyLogConfiguration</span><span class="o">()</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="KeepRuntimeFolderOption">KeepRuntimeFolderOption</h3><p>Per default the test container removes all test runner folders. If you want to keep them for any reasons (e.g. check why a test fails) set the following option:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">),</span> &#x000A;        <span c
 lass="n">keepRuntimeFolder</span><span class="o">()</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="FeaturesScannerProvisionOption">FeaturesScannerProvisionOption</h3><p>The FeaturesScannerProvisionOption (e.g. CoreOption.scanFeature()) are directly supported by the Paxexam Karaf Testframework.</p><h3 id="BootDelegationOption">BootDelegationOption</h3><p>The BootDelegationOption as known from PaxExam is also supported added the boot delegation string directly into the correct property files.</p><h3 id="SystemPackageOption">SystemPackageOption</h3><p>The Standard Exam SystemPackageOption is implemented by adding those packages to "org.osgi.framework.system.packages.extra" of the config.properties file.</p><h3 id="BootClasspathLibraryOption">BootClasspathLibraryOption</h3><p>The BootClasspathLibraryOption is honored by copying the urls into the lib directory where they are automatically taken and worked on.</p><h3 id="ExamBundl
 esStartLevel">ExamBundlesStartLevel</h3><p>The ExamBundlesStartLevel can be used to configure the start lvl of the bundles provided by the test-frameworks features.xml. Simply use it as a new option like:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.2-SNAPSHOT/zip&quot;</span><span class="o">),</span>&#x000A;            <span class="n">useOwnExamBundlesStartLevel</span><span class="o">(</span><span class="mi">4</span><span class="o">)</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre>
 </div>&#x000A;</div><h2 id="Driver">Driver</h2><p>Drivers are the parts of the framework responsible for running the Karaf Based Distribution. By default the already in the overview explained KarafDistributionConfigurationOption uses a JavaRunner starting the distribution platform independent but not using the scripts in the distribution. If you like to test those scripts too an option is to to use the ScriptRunner via the KarafDistributionKitConfigurationOption instead.</p><h3 id="JavaRunner">JavaRunner</h3><p>The JavaRunner builds the entire command itself and executes Karaf in a new JVM. This behavior is more or less exactly what the default runner does. Simply use the KarafDistributionConfigurationOption as explained in the Commands section to use this.</p><h3 id="ScriptRunner">ScriptRunner</h3><p>The script runner has the disadvantage over the java runner that it is also platform dependent. The advantage though is that you can also test your specific scripts. To use it follow t
 he explanation of the KarafDistributionKitConfigurationOption in the Commands section.</p>
+<h1 id="Writingintegrationtests">Writing integration tests</h1><p>We recommend using <a href="http://team.ops4j.org/wiki/display/paxexam/Pax+Exam">PAX Exam</a> to write integration tests when developing applications using Karaf.</p><p>Starting with Karaf 3.0 we've also included a component briding between Karaf and Pax Exam making it easier to write integration tests for Karaf or Karaf based Distributions such as <a href="http://servicemix.apache.org">Servicemix</a> or <a href="http://geronimo.apache.org">Geronimo</a>.</p><h2 id="Introduction">Introduction</h2><p>To make use of this new framework simply add the following dependencies into your integration tests pom.xml:</p><div class="syntax"><div class="highlight"><pre><span class="c">&lt;!-- Karaf Test Framework Version --&gt;</span>&#x000A;<span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.karaf.tooling.exam<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;ar
 tifactId&gt;</span>org.apache.karaf.tooling.exam.container<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;version&gt;</span>4.0.3<span class="nt">&lt;/version&gt;</span>&#x000A;  <span class="nt">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;<span class="c">&lt;!-- Pax Exam version you would like to use. At least 2.2.x is required. --&gt;</span>&#x000A;<span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.ops4j.pax.exam<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>pax-exam-junit4<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;version&gt;</span>4.6.0<span class="nt">&lt;/version&gt;</span>&#x000A;  <span class="nt">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;</pre></div>&#x000A;</div><p>As a next s
 tep you need to reference the distribution you want to run your tests on. For example, if you want to run your tests on Karaf the following section would be required in the integration tests pom.xml:</p><div class="syntax"><div class="highlight"><pre><span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.karaf<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>apache-karaf<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;version&gt;</span>4.0.3<span class="nt">&lt;/version&gt;</span>&#x000A;  <span class="nt">&lt;type&gt;</span>zip<span class="nt">&lt;/type&gt;</span>&#x000A;  <span class="nt">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;</pre></div>&#x000A;</div><p>If you want to make use of Exams "versionAsInProject" feature you also need to add the following section:</p><div class="syntax"><div c
 lass="highlight"><pre><span class="nt">&lt;build&gt;</span>&#x000A;  <span class="nt">&lt;plugins&gt;</span>&#x000A;    <span class="nt">&lt;plugin&gt;</span>&#x000A;      <span class="nt">&lt;groupId&gt;</span>org.apache.servicemix.tooling<span class="nt">&lt;/groupId&gt;</span>&#x000A;      <span class="nt">&lt;artifactId&gt;</span>depends-maven-plugin<span class="nt">&lt;/artifactId&gt;</span>&#x000A;      <span class="nt">&lt;version&gt;</span>1.2<span class="nt">&lt;/version&gt;</span>&#x000A;      <span class="nt">&lt;executions&gt;</span>&#x000A;        <span class="nt">&lt;execution&gt;</span>&#x000A;          <span class="nt">&lt;id&gt;</span>generate-depends-file<span class="nt">&lt;/id&gt;</span>&#x000A;          <span class="nt">&lt;goals&gt;</span>&#x000A;            <span class="nt">&lt;goal&gt;</span>generate-depends-file<span class="nt">&lt;/goal&gt;</span>&#x000A;          <span class="nt">&lt;/goals&gt;</span>&#x000A;        <span class="nt">&lt;/execution&gt;</spa
 n>&#x000A;      <span class="nt">&lt;/executions&gt;</span>&#x000A;    <span class="nt">&lt;/plugin&gt;</span>&#x000A;  <span class="nt">&lt;/plugins&gt;</span>&#x000A;<span class="nt">&lt;/build&gt;</span>&#x000A;</pre></div>&#x000A;</div><p>With this done we can start writing our first test case:</p><div class="syntax"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">static</span> <span class="n">junit</span><span class="o">.</span><span class="na">framework</span><span class="o">.</span><span class="na">Assert</span><span class="o">.</span><span class="na">assertTrue</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">static</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">karaf</span><span class="o">.</span><span class="na">tooling</span><span class="o">.</span><span class="na">exam</span><span class="o">.</span><span class="na">options</spa
 n><span class="o">.</span><span class="na">KarafDistributionOption</span><span class="o">.</span><span class="na">karafDistributionConfiguration</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">static</span> <span class="n">org</span><span class="o">.</span><span class="na">ops4j</span><span class="o">.</span><span class="na">pax</span><span class="o">.</span><span class="na">exam</span><span class="o">.</span><span class="na">CoreOptions</span><span class="o">.</span><span class="na">maven</span><span class="o">;</span>&#x000A;&#x000A;<span class="kn">import</span> <span class="nn">org.junit.Test</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.junit.runner.RunWith</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.Option</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.Configuration</span><
 span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.ExamReactorStrategy</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.JUnit4TestRunner</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.spi.reactors.AllConfinedStagedReactorFactory</span><span class="o">;</span>&#x000A;&#x000A;<span class="nd">@RunWith</span><span class="o">(</span><span class="n">JUnit4TestRunner</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>&#x000A;<span class="nd">@ExamReactorStrategy</span><span class="o">(</span><span class="n">AllConfinedStagedReactorFactory</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>&#x000A;<span class="kd">public</span> <span class="kd">class</span> <span class="nc">VersionAsInProjectKarafTest</span> <span class="o">{</span>&#x000A;&#x000A;    <span
  class="nd">@Configuration</span>&#x000A;    <span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;        <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">().</span><span class="na">frameworkUrl</span><span class="o">(</span>&#x000A;            <span class="n">maven</span><span class="o">().</span><span class="na">groupId</span><span class="o">(</span><span class="s">&quot;org.apache.karaf&quot;</span><span class="o">).</span><span class="na">artifactId</span><span class="o">(</span><span class="s">&quot;apache-karaf&quot;</span><span class="o">).</span><span class="na">type</span><span class="o">(</span><span class="s">&quot;zip&quot;</span><span class="o">).</span><span class="na">versionAsInProject</span><span class="o">())</span>
 &#x000A;            <span class="o">.</span><span class="na">karafVersion</span><span class="o">(</span><span class="s">&quot;2.2.4&quot;</span><span class="o">).</span><span class="na">name</span><span class="o">(</span><span class="s">&quot;Apache Karaf&quot;</span><span class="o">)};</span>&#x000A;    <span class="o">}</span>&#x000A;&#x000A;    <span class="nd">@Test</span>&#x000A;    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">test</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span>&#x000A;        <span class="n">assertTrue</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>&#x000A;    <span class="o">}</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h2 id="Commands">Commands</h2><p>Basically the Pax Exam - Karaf bridge introduced with 3.0 should support all commands you know from Pax Exam 2.x. In addition we've added vari
 ous additional commands to make your life easier. Those commands are listed and explained in this sub section.</p><p>As a small remark: All of the Options explained here are also accessible via the static methods in the KarafDistributionOption class in the options package automatically on your classpath when you reference the container package.</p><h3 id="KarafDistributionConfigurationOption">KarafDistributionConfigurationOption</h3><p>The framework itself is non of the typical runtimes you define normally in PAXEXAM. Instead you define a packed distribution as zip or tar.gz. Those distributions have to follow the Karaf packaging style. Therefore instead of Karaf you can also enter Servicemix or Geronimo.</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurationOption</span><span class="o">(</span>&#x000A;  <span class="s">&quot;mvn:org.apache.karaf/apache-karaf/2.2.4/zip&quot;</span><span class="o">,</span> <span c
 lass="c1">// artifact to unpack and use</span>&#x000A;  <span class="s">&quot;karaf&quot;</span><span class="o">,</span> <span class="c1">// name; display only</span>&#x000A;  <span class="s">&quot;2.2.4&quot;</span><span class="o">)</span> <span class="c1">// the karaf version; this one is relevant since the startup script differs between versions</span>&#x000A;</pre></div>&#x000A;</div><p>or for Servicemix e.g.</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurationOption</span><span class="o">(</span>&#x000A;  <span class="s">&quot;mvn:org.apache.servicemix/apache-servicemix/4.4.0/zip&quot;</span><span class="o">,</span> <span class="c1">// artifact to unpack and use</span>&#x000A;  <span class="s">&quot;servicemix&quot;</span><span class="o">,</span> <span class="c1">// name; display only</span>&#x000A;  <span class="s">&quot;2.2.4&quot;</span><span class="o">)</span> <span class="c1">// the karaf version; thi
 s one is relevant since the startup script differs between versions</span>&#x000A;</pre></div>&#x000A;</div><p>As an alternative you can also use the maven url resolvers. Please keep in mind that this only works starting with karaf-3.0.0 since there will be problems with the pax-url version. In addition, if you want to make use of the versionAsInProject part you also need to define the following maven-plugin in the pom file of your integration tests:</p><div class="syntax"><div class="highlight"><pre>...&#x000A;<span class="nt">&lt;dependency&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.karaf<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>apache-karaf<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;type&gt;</span>zip<span class="nt">&lt;/type&gt;</span>&#x000A;  <span class="nt">&lt;classifier&gt;</span>bin<span class="nt">&lt;/classifier&gt;</span>&#x000A;  <span class="nt">&lt;scope&gt;</
 span>test<span class="nt">&lt;/scope&gt;</span>&#x000A;<span class="nt">&lt;/dependency&gt;</span>&#x000A;...&#x000A;<span class="nt">&lt;plugin&gt;</span>&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.servicemix.tooling<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>depends-maven-plugin<span class="nt">&lt;/artifactId&gt;</span>&#x000A;  <span class="nt">&lt;executions&gt;</span>&#x000A;    <span class="nt">&lt;execution&gt;</span>&#x000A;      <span class="nt">&lt;id&gt;</span>generate-depends-file<span class="nt">&lt;/id&gt;</span>&#x000A;      <span class="nt">&lt;goals&gt;</span>&#x000A;        <span class="nt">&lt;goal&gt;</span>generate-depends-file<span class="nt">&lt;/goal&gt;</span>&#x000A;      <span class="nt">&lt;/goals&gt;</span>&#x000A;    <span class="nt">&lt;/execution&gt;</span>&#x000A;  <span class="nt">&lt;/executions&gt;</span>&#x000A;<span class="nt">&lt;/plugin&gt;</span>&#x000A;</pre></div>&#x000A;</div
 ><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;    <span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;        <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">().</span><span class="na">frameworkUrl</span><span class="o">(</span>&#x000A;            <span class="n">maven</span><span class="o">().</span><span class="na">groupId</span><span class="o">(</span><span class="s">&quot;org.apache.karaf&quot;</span><span class="o">).</span><span class="na">artifactId</span><span class="o">(</span><span class="s">&quot;apache-karaf&quot;</span><span class="o">).</span><span class="na">type</span><span class="o">(</span><span class="s">&quot;zip&quot;</span><span class="o">)</span>&#x000A;       
          <span class="o">.</span><span class="na">classifier</span><span class="o">(</span><span class="s">&quot;bin&quot;</span><span class="o">).</span><span class="na">versionAsInProject</span><span class="o">())</span> <span class="o">};</span>&#x000A;    <span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><p>In addition to the framework specification options this option also includes various additional configuration options. Those options are used to configure the internal properties of the runtime environment.</p><h4 id="UnpackDirectory">Unpack Directory</h4><p>Paxexam-Karaf Testframework extracts the distribution you specify by default into the paxexam config directory. If you would like to unpack them into your target directory simply extend the KarafDistributionConfigurationOption with the unpackDirectoryFile like shown in the next example:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <
 span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">)</span>&#x000A;        <span class="o">.</span><span class="na">unpackDirectory</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">&quot;target/paxexam/unpack/&quot;</span><span class="o">))</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h4 id="UseDeployFolder">Use Deploy Folder</h4><p>Karaf distributions come by default with a deploy folder where you can simply drop artifacts to be deployed. In some distributions this folder might have 
 been removed. To still be able to deploy your additional artifacts using default Pax Exam ProvisionOptions you can configure PaxExam Karaf to use a features.xml (which is directly added to your etc/org.apache.karaf.features.cfg) for those deploys. To use it instead of the deploy folder simply do the following:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">)</span>&#x000A;        <span class="o">.</span><span class="na">useDeployFolder</span><span class="o">(</span><span class="kc
 ">false</span><span class="o">))</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="KarafDistributionKitConfigurationOption">KarafDistributionKitConfigurationOption</h3><p>The KarafDistributionKitConfigurationOption is almost equal to all variations of the KarafDistributionConfigurationOption with the exception that it requires to have set a platform and optionally the executable and the files which should be made executable additionally. By default it is bin/karaf for nix platforms and bin\karaf.bat for windows platforms. The executable option comes in handy if you like to e.g. embed an own java runtime. You should add a windows AND a linux Kit definition. The framework automatically takes the correct one then. The following shows a simple example for karaf:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o"
 >[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span>&#x000A;        <span class="k">new</span> <span class="nf">KarafDistributionKitConfigurationOption</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">,</span>&#x000A;            <span class="n">Platform</span><span class="o">.</span><span class="na">WINDOWS</span><span class="o">).</span><span class="na">executable</span><span class="o">(</span><span class="s">&quot;bin\\karaf.bat&quot;</span><span class="o">).</span><span class="na">filesToMakeExecutable</span><span class="o">(</span><span class="s">&quot;bin\\admin.bat&quot;</span><span class="o">),</span>&#x000A;        <span class="k">new</span> <span class="nf">KarafDistributionKitConfigurationOption</span><span class="o">(</span><span class="s
 ">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/tar.gz&quot;</span><span class="o">,</span> <span class="s">&quot;karaf&quot;</span><span class="o">,</span>&#x000A;            <span class="n">Platform</span><span class="o">.</span><span class="na">NIX</span><span class="o">).</span><span class="na">executable</span><span class="o">(</span><span class="s">&quot;bin/karaf&quot;</span><span class="o">).</span><span class="na">filesToMakeExecutable</span><span class="o">(</span><span class="s">&quot;bin/admin&quot;</span><span class="o">)</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="KarafDistributionConfigurationFilePutOption">KarafDistributionConfigurationFilePutOption</h3><p>The option replaces or adds an option to one of Karaf's configuration files:</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurationFilePutOption</span><span class="o">(</span>&#x000A;
   <span class="s">&quot;etc/config.properties&quot;</span><span class="o">,</span> <span class="c1">// config file to modify based on karaf.base</span>&#x000A;  <span class="s">&quot;karaf.framework&quot;</span><span class="o">,</span> <span class="c1">// key to add or change</span>&#x000A;  <span class="s">&quot;equinox&quot;</span><span class="o">)</span> <span class="c1">// value to add or change</span>&#x000A;</pre></div>&#x000A;</div><p>This option could also be used in "batch-mode" via a property file. Therefore use the KarafDistributionOption#editConfigurationFilePut(final String configurationFilePath, File source, String... keysToUseFromSource) method. This option allows you to add all properties found in the file as KarafDistributionConfigurationFilePutOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily put an entire range of properties.</p><h3 id="KarafDistributionConfigurationFileExtendOption">KarafD
 istributionConfigurationFileExtendOption</h3><p>This one does the same as the KarafDistributionConfigurationFilePutOption option with the one difference that it either adds or appends a specific property. This is especially useful if you do not want to store the entire configuration in the line in your code.</p><p>This option could also be extended in "batch-mode" via a property file. Therefore use the KarafDistributionOption#editConfigurationFileExtend(final String configurationFilePath, File source, String... keysToUseFromSource) method. This option allows you to extend all properties found in the file as KarafDistributionConfigurationFileExtendOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily extend an entire range of properties.</p><h3 id="KarafDistributionConfigurationFileReplacementOption">KarafDistributionConfigurationFileReplacementOption</h3><p>The file replacement option allows you to simply replace
  a file in you Karaf distribution with a different file:</p><div class="syntax"><div class="highlight"><pre><span class="k">new</span> <span class="nf">KarafDistributionConfigurationFileReplacementOption</span><span class="o">(</span><span class="s">&quot;etc/tests.cfg&quot;</span><span class="o">,</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span>&#x000A;    <span class="s">&quot;src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey&quot;</span><span class="o">));</span>&#x000A;</pre></div>&#x000A;</div><h3 id="ProvisionOption">ProvisionOption</h3><p>The new test container fully supports the provision option. Feel free to use any option provided here by paxexam itself (e.g. Maven resolver). All those artifacts are copied into the deploy folder of your Karaf distribution before it is started. Therefore they all will be available after startup.</p><h3 id="KarafDistributionConfigurationConsoleOption">KarafDistributionConfig
 urationConsoleOption</h3><p>The test container supports options to configure if the localConsole and/or the remote shell should be started. Possible options to do so are shown in the following two examples:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">configureConsole</span><span class="o">().</span><span class="na">ignoreLocalConsole</span><span class="o">().</span><span class="na">startRemoteShell</span><span class="o">()</span> <span 
 class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">configureConsole</span><span class="o">().</span><span class="na">startLocalConsole</span><span class="o">(),</span> <span class="n">configureConsole</span><span class="o">().</span><span class="na">ignoreRemoteShell</span><span class="o">()</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;
 </pre></div>&#x000A;</div><h3 id="VMOption">VMOption</h3><p>The Karaf container passes the vmOptions now through to the Karaf environment. They are directly passed to the startup of the container. In addition the KarafDistributionOption helper has two methods (debugConfiguration() and debugConfiguration(String port, boolean hold)) to activate debugging quickly.</p><h3 id="LogLevelOption">LogLevelOption</h3><p>The Paxexam-Karaf specific log-level option allows an easy way to set a specific log-level for the Karaf based distribution. For example simply add the following to your Option[] array to get TRACE logging:</p><div class="syntax"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">static</span> <span class="n">org</span><span class="o">.</span><span class="na">openengsb</span><span class="o">.</span><span class="na">labs</span><span class="o">.</span><span class="na">paxexam</span><span class="o">.</span><span class="na">karaf</span><span class="o">.</sp
 an><span class="na">options</span><span class="o">.</span><span class="na">KarafDistributionOption</span><span class="o">.</span><span class="na">logLevel</span><span class="o">;</span>&#x000A;<span class="o">...</span>&#x000A;<span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">logLevel</span><span class="o">(</span><span class="n">LogLevel</span><span class="o">.</span><span class="na">TRACE</span><span class="o">)</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre><
 /div>&#x000A;</div><h3 id="DoNotModifyLogOption">DoNotModifyLogOption</h3><p>The option to modify the logging behavior requires that the container automatically modifies the logging configuration file. If you would like to suppress this behavior simply set the doNotModifyLogConfiguration option as shown in the next example:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">doNotModifyLogConfiguration</span><span class="o">()</span> <span clas
 s="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="KeepRuntimeFolderOption">KeepRuntimeFolderOption</h3><p>Per default the test container removes all test runner folders. If you want to keep them for any reasons (e.g. check why a test fails) set the following option:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">),</span> &#x000A;        <span class="n">keepRuntimeFolder</span><span class="o">()</span> <span class="o">};</span>&#x000A;<span c
 lass="o">}</span>&#x000A;</pre></div>&#x000A;</div><h3 id="FeaturesScannerProvisionOption">FeaturesScannerProvisionOption</h3><p>The FeaturesScannerProvisionOption (e.g. CoreOption.scanFeature()) are directly supported by the Paxexam Karaf Testframework.</p><h3 id="BootDelegationOption">BootDelegationOption</h3><p>The BootDelegationOption as known from PaxExam is also supported added the boot delegation string directly into the correct property files.</p><h3 id="SystemPackageOption">SystemPackageOption</h3><p>The Standard Exam SystemPackageOption is implemented by adding those packages to "org.osgi.framework.system.packages.extra" of the config.properties file.</p><h3 id="BootClasspathLibraryOption">BootClasspathLibraryOption</h3><p>The BootClasspathLibraryOption is honored by copying the urls into the lib directory where they are automatically taken and worked on.</p><h3 id="ExamBundlesStartLevel">ExamBundlesStartLevel</h3><p>The ExamBundlesStartLevel can be used to configure the s
 tart lvl of the bundles provided by the test-frameworks features.xml. Simply use it as a new option like:</p><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>&#x000A;<span class="kd">public</span> <span class="n">Option</span><span class="o">[]</span> <span class="nf">config</span><span class="o">()</span> <span class="o">{</span>&#x000A;    <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span> <span class="n">karafDistributionConfiguration</span><span class="o">(</span><span class="s">&quot;mvn:org.apache.karaf/apache-karaf/4.0.3/zip&quot;</span><span class="o">),</span>&#x000A;            <span class="n">useOwnExamBundlesStartLevel</span><span class="o">(</span><span class="mi">4</span><span class="o">)</span> <span class="o">};</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h2 id="Driver">Driver</h2><p>Drivers are the parts of the framework responsible for run
 ning the Karaf Based Distribution. By default the already in the overview explained KarafDistributionConfigurationOption uses a JavaRunner starting the distribution platform independent but not using the scripts in the distribution. If you like to test those scripts too an option is to to use the ScriptRunner via the KarafDistributionKitConfigurationOption instead.</p><h3 id="JavaRunner">JavaRunner</h3><p>The JavaRunner builds the entire command itself and executes Karaf in a new JVM. This behavior is more or less exactly what the default runner does. Simply use the KarafDistributionConfigurationOption as explained in the Commands section to use this.</p><h3 id="ScriptRunner">ScriptRunner</h3><p>The script runner has the disadvantage over the java runner that it is also platform dependent. The advantage though is that you can also test your specific scripts. To use it follow the explanation of the KarafDistributionKitConfigurationOption in the Commands section.</p>
                 </div>
               </td>
             </tr>

Modified: karaf/site/production/manual/latest/index.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/index.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/index.html (original)
+++ karaf/site/production/manual/latest/index.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="css/style.css" rel="stylesheet" type="text/css"/>
     <link href="css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/overview.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/overview.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/overview.html (original)
+++ karaf/site/production/manual/latest/overview.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="css/style.css" rel="stylesheet" type="text/css"/>
     <link href="css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/quick-start.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/quick-start.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/quick-start.html (original)
+++ karaf/site/production/manual/latest/quick-start.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="css/style.css" rel="stylesheet" type="text/css"/>
     <link href="css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/update-notes.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/update-notes.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/update-notes.html (original)
+++ karaf/site/production/manual/latest/update-notes.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="css/style.css" rel="stylesheet" type="text/css"/>
     <link href="css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/cdi.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/cdi.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/cdi.html (original)
+++ karaf/site/production/manual/latest/users-guide/cdi.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/configuration.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/configuration.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/configuration.html (original)
+++ karaf/site/production/manual/latest/users-guide/configuration.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/console.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/console.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/console.html (original)
+++ karaf/site/production/manual/latest/users-guide/console.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/deployers.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/deployers.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/deployers.html (original)
+++ karaf/site/production/manual/latest/users-guide/deployers.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/directory-structure.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/directory-structure.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/directory-structure.html (original)
+++ karaf/site/production/manual/latest/users-guide/directory-structure.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/ejb.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/ejb.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/ejb.html (original)
+++ karaf/site/production/manual/latest/users-guide/ejb.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/enterprise.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/enterprise.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/enterprise.html (original)
+++ karaf/site/production/manual/latest/users-guide/enterprise.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/failover.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/failover.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/failover.html (original)
+++ karaf/site/production/manual/latest/users-guide/failover.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/features.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/features.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/features.html (original)
+++ karaf/site/production/manual/latest/users-guide/features.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/http.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/http.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/http.html (original)
+++ karaf/site/production/manual/latest/users-guide/http.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/index.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/index.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/index.html (original)
+++ karaf/site/production/manual/latest/users-guide/index.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/installation.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/installation.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/installation.html (original)
+++ karaf/site/production/manual/latest/users-guide/installation.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/instances.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/instances.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/instances.html (original)
+++ karaf/site/production/manual/latest/users-guide/instances.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>

Modified: karaf/site/production/manual/latest/users-guide/jdbc.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/jdbc.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/jdbc.html (original)
+++ karaf/site/production/manual/latest/users-guide/jdbc.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>
@@ -101,56 +101,50 @@
               </td>
               <td height="100%" width="100%">
                 <div class="wiki-content">
-<h1 id="DataSourcesJDBC">DataSources (JDBC)</h1><p>The Apache Karaf DataSources (JDBC) is an optional enterprise feature.</p><p>You have to install the <tt>jdbc</tt> feature first:</p><pre>
+<h1 id="DataSourcesJDBC">DataSources (JDBC)</h1><p>The Apache Karaf DataSources (JDBC) is an optional enterprise feature.</p><p>You have to install the following features first:</p><pre>
+karaf@root()> feature:repo-add pax-jdbc
+karaf@root()> feature:install pax-jdbc
+karaf@root()> feature:install pax-jdbc-config
 karaf@root()> feature:install jdbc
-</pre><p>This feature provides an OSGi service to create/delete JDBC datasources in the container and perform database operations (SQL queries).</p><p>This JDBC OSGi service can be manipulated programmatically (see the developer guide for details), using the <tt>jdbc:*</tt> commands, or using the JDBC MBean.</p><h2 id="Commands">Commands</h2><h3 id="jdbccreate"><tt>jdbc:create</tt></h3><p>The <tt>jdbc:create</tt> command automatically creates a datasource definition file in the Apache Karaf <tt>deploy</tt> folder.</p><p>The <tt>jdbc:create</tt> accepts a set of options and the name argument:</p><pre>
-karaf@root()> jdbc:create --help
+</pre><p>Pax JDBC provides ready to use adapters for different databases:</p><ul><li>pax-jdbc-derby</li><li>pax-jdbc-derbyclient</li><li>pax-jdbc-h2</li><li>pax-jdbc-mariadb</li><li>pax-jdbc-mysql</li><li>pax-jdbc-oracle</li><li>pax-jdbc-postgresql</li><li>pax-jdbc-sqlite</li><li>pax-jdbc-mssql</li></ul><p>This feature provides an OSGi service to create/delete JDBC datasources in the container and perform database operations (SQL queries).</p><p>This JDBC OSGi service can be manipulated programmatically (see the developer guide for details), using the <tt>jdbc:*</tt> commands, or using the JDBC MBean.</p><h2 id="Commands">Commands</h2><h3 id="jdbcdscreate"><tt>jdbc:ds-create</tt></h3><p>The <tt>jdbc:ds-create</tt> command automatically creates a datasource definition file by leveraging pax-jdbc.</p><p>The <tt>jdbc:ds-create</tt> command requires either:</p><ul><li>the <tt>--driverName</tt> containing the JDBC driver name</li><li>or the <tt>--driverClass</tt> containing the JDBC driv
 er class name</li></ul><p>The <tt>jdbc:ds-create</tt> accepts a set of options and the name argument:</p><pre>
 DESCRIPTION
-        jdbc:create
+        jdbc:ds-create
 
-        Create a JDBC datasource
+        Create a JDBC datasource config for pax-jdbc-config from a DataSourceFactory
 
 SYNTAX
-        jdbc:create [options] name
+        jdbc:ds-create [options] name
 
 ARGUMENTS
         name
                 The JDBC datasource name
 
 OPTIONS
+        -dbName
+                Database name to use
+        --help
+                Display this help message
+        -dn, --driverName
+                org.osgi.driver.name property of the DataSourceFactory
         -u, --username
                 The database username
-        -v, --version
-                The version of the driver to use
-        -t, --type
-                The JDBC datasource type (generic, MySQL, Oracle, Postgres, H2, HSQL, Derby, MSSQL)
-        -url
-                The JDBC URL to use
+        -dc, --driverClass
+                org.osgi.driver.class property  of the DataSourceFactory
         -p, --password
                 The database password
-        -i, --install-bundles
-                Try to install the bundles providing the JDBC driver
-        -d, --driver
-                The classname of the JDBC driver to use. NB: this option is used only the type generic
-        --help
-                Display this help message
+        -url
+                The JDBC URL to use
+</pre><ul><li>the <tt>name</tt> argument is required. It's the name of the datasource. The name is used to identify the datasource, and to create the datasource definition file (<tt>deploy/datasource-<a href="name.html">name</a>.xml</tt>).</li><li>the <tt>-u</tt> option is optional. It defines the database username.</li><li>the <tt>-url</tt> option is optional. It defines the JDBC URL to access to the database.</li><li>the <tt>-p</tt> option is optional. It defines the database password.</li></ul><p>For instance, to create an embedded Apache Derby database in Apache Karaf, you can do:</p><pre>
+karaf@root()> jdbc:ds-create -dn derby -dbName test -url jdbc:derby:test test
+</pre><p>We can see that this command created a configuration PID containing the datasource properties.</p><h2 id="jdbcdsdelete"><tt>jdbc:ds-delete</tt></h2><p>The <tt>jdbc:ds-delete</tt> command deletes a datasource.</p><pre>
+karaf@root()> jdbc:ds-delete test
+</pre><h2 id="jdbcdslist"><tt>jdbc:ds-list</tt></h2><p>The <tt>jdbc:ds-list</tt> command lists the JDBC datasources:</p><pre>
+karaf@root()> jdbc:ds-list
+Name | Product | Version | URL | Status
+---------------------------------------
 
-</pre><ul><li>the <tt>name</tt> argument is required. It's the name of the datasource. The name is used to identify the datasource, and to create the datasource definition file (<tt>deploy/datasource-<a href="name.html">name</a>.xml</tt>).</li><li>the <tt>-u</tt> option is optional. It defines the database username.</li><li>the <tt>-v</tt> option is optional. It "forces" a given JDBC driver version (only used with the <tt>-i</tt> option).</li><li>the <tt>-t</tt> option is required. It defines the JDBC datasource type. Accepted values are: MySQL, Oracle, Postgres, Derby, H2, HSQL, MSSQL, Generic. Generic is a generic configuration file using DBCP to create a pooled datasource. When using generic, it's up to you to install the JDBC driver and configure the <tt>deploy/datasource-<a href="name.html">name</a>.xml</tt> datasource file.</li><li>the <tt>-url</tt> option is optional. It defines the JDBC URL to access to the database.</li><li>the <tt>-p</tt> option is optional. It defines the
  database password.</li><li>the <tt>-d</tt> option is optional. It defines the JDBC driver classname to use (only used with the generic type).</li><li>the <tt>-i</tt> option is optional. If specified, the command will try to automatically install the OSGi bundles providing the JDBC driver (depending of the datasource type specified by the <tt>-t</tt> option).</li></ul><p>For instance, to create an embedded Apache Derby database in Apache Karaf, you can do:</p><pre>
-karaf@root()> jdbc:create -t derby -u test -i test
-</pre><p>We can note that the Derby bundle has been installed automatically, and the datasource has been created:</p><pre>
-karaf@root()> la
-...
-87 | Active   |  80 | 10.8.2000002.1181258  | Apache Derby 10.8
-88 | Active   |  80 | 0.0.0                 | datasource-test.xml
-</pre><p>We can see the <tt>deploy/datasource-test.xml</tt> datasource file.</p><h2 id="jdbcdelete"><tt>jdbc:delete</tt></h2><p>The <tt>jdbc:delete</tt> command deletes a datasource by removing the <tt>deploy/datasource-<a href="name.html">name</a>.xml</tt> datasource file:</p><pre>
-karaf@root()> jdbc:delete test
-</pre><div class="warning" style="border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;"><p>The <tt>jdbc:delete</tt> does not uninstall the JDBC driver bundles and does not remove the files created by the JDBC driver (or the database in case of embedded database).<br/>It's up to you to remove it.</p></div><h2 id="jdbcdatasources"><tt>jdbc:datasources</tt></h2><p>The <tt>jdbc:datasources</tt> command lists the JDBC datasources:</p><pre>
-karaf@root()> jdbc:datasources
-Name       | Product      | Version              | URL
-------------------------------------------------------------------
-/jdbc/test | Apache Derby | 10.8.2.2 - (1181258) | jdbc:derby:test
-</pre><h2 id="jdbcinfo"><tt>jdbc:info</tt></h2><p>The <tt>jdbc:info</tt> command provides details about a JDBC datasource:</p><pre>
-karaf@root()> jdbc:info /jdbc/test
+</pre><h2 id="jdbcdsinfo"><tt>jdbc:ds-info</tt></h2><p>The <tt>jdbc:ds-info</tt> command provides details about a JDBC datasource:</p><pre>
+karaf@root()> jdbc:ds-info test
 Property       | Value
 --------------------------------------------------
 driver.version | 10.8.2.2 - (1181258)
@@ -160,18 +154,18 @@ db.product     | Apache Derby
 driver.name    | Apache Derby Embedded JDBC Driver
 url            | jdbc:derby:test
 </pre><h2 id="jdbcexecute"><tt>jdbc:execute</tt></h2><p>The <tt>jdbc:execute</tt> command executes a SQL query that doesn't return any result on a given JDBC datasource.</p><p>Typically, you can use the <tt>jdbc:execute</tt> command to create tables, insert values into tables, etc.</p><p>For instance, we can create a <tt>person</tt> table on our <tt>test</tt> datasource:</p><pre>
-karaf@root()> jdbc:execute /jdbc/test "create table person(name varchar(100), nick varchar(100))"
+karaf@root()> jdbc:execute test "create table person(name varchar(100), nick varchar(100))"
 </pre><p>And we can insert some records in the <tt>person</tt> table:</p><pre>
-karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('foo','bar')"
-karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('test','test')"
+karaf@root()> jdbc:execute test "insert into person(name, nick) values('foo','bar')"
+karaf@root()> jdbc:execute test "insert into person(name, nick) values('test','test')"
 </pre><h2 id="jdbcquery"><tt>jdbc:query</tt></h2><p>The <tt>jdbc:query</tt> command is similar to the <tt>jdbc:execute</tt> one but it displays the query result.</p><p>For instance, to display the content of the <tt>person</tt> table, we can do:</p><pre>
-karaf@root()> jdbc:query /jdbc/test "select * from person"
+karaf@root()> jdbc:query test "select * from person"
 NICK       | NAME
 --------------------------------
 bar        | foo
 test       | test
 </pre><h2 id="jdbctables"><tt>jdbc:tables</tt></h2><p>The <tt>jdbc:tables</tt> command displays all tables available on a given JDBC datasource:</p><pre>
-karaf@root()> jdbc:tables /jdbc/test
+karaf@root()> jdbc:tables test
 REF_GENERATION | TYPE_NAME | TABLE_NAME       | TYPE_CAT | REMARKS | TYPE_SCHEM | TABLE_TYPE   | TABLE_SCHEM | TABLE_CAT | SELF_REFERENCING_COL_NAME
 ----------------------------------------------------------------------------------------------------------------------------------------------------
                |           | SYSALIASES       |          |         |            | SYSTEM TABLE | SYS         |           |

Modified: karaf/site/production/manual/latest/users-guide/jms.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/users-guide/jms.html?rev=1720992&r1=1720991&r2=1720992&view=diff
==============================================================================
--- karaf/site/production/manual/latest/users-guide/jms.html (original)
+++ karaf/site/production/manual/latest/users-guide/jms.html Sun Dec 20 07:47:05 2015
@@ -8,7 +8,7 @@
     <link href="../css/style.css" rel="stylesheet" type="text/css"/>
     <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
     <title>
-      Apache Karaf 4.0.2-SNAPSHOT Guides
+      Apache Karaf 4.0.3 Guides
     </title>
   </head>
   <body>