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/07/01 21:43:38 UTC

svn commit: r1688715 [18/23] - 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=1688715&r1=1688714&r2=1688715&view=diff
==============================================================================
--- karaf/site/production/manual/latest/developers-guide/writing-tests.html (original)
+++ karaf/site/production/manual/latest/developers-guide/writing-tests.html Wed Jul  1 19:43:35 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 3.0.3-SNAPSHOT Guides
+      Apache Karaf 4.0.1-SNAPSHOT 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>3.0.3-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.2.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>3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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/3.0.3-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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>
                 </div>
               </td>
             </tr>
@@ -121,7 +121,7 @@
         <td id="cell-3-2">
           <div id="footer">
             <div id="site-footer">
-              &copy; 2008-2011 The Apache Software Foundation
+              &copy; 2008-2014 The Apache Software Foundation
               <br/>
               Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
             </div>

Modified: karaf/site/production/manual/latest/index.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/index.html?rev=1688715&r1=1688714&r2=1688715&view=diff
==============================================================================
--- karaf/site/production/manual/latest/index.html (original)
+++ karaf/site/production/manual/latest/index.html Wed Jul  1 19:43:35 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 3.0.3-SNAPSHOT Guides
+      Apache Karaf 4.0.1-SNAPSHOT Guides
     </title>
   </head>
   <body>
@@ -121,7 +121,7 @@
         <td id="cell-3-2">
           <div id="footer">
             <div id="site-footer">
-              &copy; 2008-2011 The Apache Software Foundation
+              &copy; 2008-2014 The Apache Software Foundation
               <br/>
               Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
             </div>

Modified: karaf/site/production/manual/latest/overview.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/overview.html?rev=1688715&r1=1688714&r2=1688715&view=diff
==============================================================================
--- karaf/site/production/manual/latest/overview.html (original)
+++ karaf/site/production/manual/latest/overview.html Wed Jul  1 19:43:35 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 3.0.3-SNAPSHOT Guides
+      Apache Karaf 4.0.1-SNAPSHOT Guides
     </title>
   </head>
   <body>
@@ -101,7 +101,7 @@
               </td>
               <td height="100%" width="100%">
                 <div class="wiki-content">
-<h1 id="ApacheKarafOverview">Apache Karaf Overview</h1><p>Apache Karaf is a OSGi-based runtime which provides a lightweight container onto which various components and applications can be deployed.</p><p>Apache Karaf uses either Apache Felix Framework or Eclipse Equinox OSGi frameworks, and provide additional features on top of the framework.</p><p>Apache Karaf can be scaled from a very lightweight container to a fully features enterprise service: it's a very flexible and extensible container, covering all the major needs.</p><p>Here is a short list of provided features:</p><ul><li><strong>Hot deployment</strong>: simply drop a file in the <tt>deploy</tt> directory, Apache Karaf will detect the type of the file and<p> try to deploy it.</p></li><li><strong>Complete Console</strong>: Apache Karaf provides a complete Unix-like console where you can completely manage the container.</li><li><strong>Dynamic Configuration</strong>: Apache Karaf provides a set of command dedicated for the m
 anagement of the configuration files.<p> All configuration files are centralized in the <tt>etc</tt> folder. Any change in a configuration file is taken on the fly.</p></li><li><strong>Advanced Logging System</strong>: Apache Karaf supports a large set of Logging framework (slf4j, log4j, etc). Whatever the<p> logging framework you use, Apache Karaf centralizes the configuration in one file.</p></li><li><strong>Provisioning</strong>: Apache Karaf supports a large set of URL where you can install your application (Maven repository, HTTP,<p> file, etc). It also provides the concept of "Karaf Feature" which is a way to describe your application.</p></li><li><strong>Management</strong>: Apache Karaf is an enterprise-ready container, providing a lot of management indicators and operations<p> via JMX.</p></li><li><strong>Remote</strong>: Apache Karaf embeds an SSHd server allowing you to use the console remotely. The management layer is also<p> accessible remotely.</p></li><li><strong>Secu
 rity</strong>: Apache Karaf provides a complete security framework (based on JAAS), and providing RBAC (Role-Based Access<p> Control) mechanism for console and JMX.</p></li><li><strong>Instances</strong>: multiple instances of Apache Karaf can be managed directly from a main instance (root).</li><li><strong>OSGi frameworks</strong>: Apache Karaf is not tight to one OSGi framework. By default, Apache Karaf runs with Apache Felix<p> Framework, but you can easily switch to Equinox (just change on property in a configuration file).</p><p><img border="0" src="images/karaf.png"/></p></li></ul>
+<h1 id="ApacheKarafOverview">Apache Karaf Overview</h1><p>Apache Karaf is a modern and polymorphic container.</p><p>It's a lightweight, powerful, and enterprise ready container powered by OSGi.<br/>You can deploy different kind of applications in Karaf, OSGi or non-OSGi.</p><p>Thanks to his flexibility, Karaf is the perfect container for micro services architecture, integration platform, big data platform, and much more.</p><p>Apache Karaf uses either Apache Felix Framework or Eclipse Equinox OSGi frameworks, providing additional features on top of the framework.</p><p>Apache Karaf can be scaled from a very lightweight container to a fully features enterprise service: it's a very flexible and extensible container, covering all the major needs.</p><p>Here is a short list of provided features:</p><ul><li><strong>Hot deployment</strong>: simply drop a file in the <tt>deploy</tt> directory, Apache Karaf will detect the type of the file and<p> try to deploy it.</p></li><li><strong>Comple
 te Console</strong>: Apache Karaf provides a complete Unix-like console where you can completely manage the container.</li><li><strong>Dynamic Configuration</strong>: Apache Karaf provides a set of command dedicated for the management of the configuration files.<p> All configuration files are centralized in the <tt>etc</tt> folder. Any change in a configuration file is taken on the fly.</p></li><li><strong>Advanced Logging System</strong>: Apache Karaf supports a large set of Logging framework (slf4j, log4j, etc). Whatever the<p> logging framework you use, Apache Karaf centralizes the configuration in one file.</p></li><li><strong>Provisioning</strong>: Apache Karaf supports a large set of URL where you can install your application (Maven repository, HTTP,<p> file, etc). It also provides the concept of "Karaf Features" which is a way to describe your application.</p></li><li><strong>Management</strong>: Apache Karaf is an enterprise-ready container, providing a lot of management ind
 icators and operations<p> via JMX.</p></li><li><strong>Remote</strong>: Apache Karaf embeds an SSHd server allowing you to use the console remotely. The management layer is also<p> accessible remotely.</p></li><li><strong>Security</strong>: Apache Karaf provides a complete security framework (based on JAAS), and providing RBAC (Role-Based Access<p> Control) mechanism for console and JMX.</p></li><li><strong>Instances</strong>: multiple instances of Apache Karaf can be managed directly from a main instance (root).</li><li><strong>OSGi frameworks</strong>: Apache Karaf is not tight to one OSGi framework. By default, Apache Karaf runs with Apache Felix<p> Framework, but you can easily switch to Equinox (just change on property in a configuration file).</p><p><img border="0" src="images/karaf.png"/></p></li></ul>
                 </div>
               </td>
             </tr>
@@ -121,7 +121,7 @@
         <td id="cell-3-2">
           <div id="footer">
             <div id="site-footer">
-              &copy; 2008-2011 The Apache Software Foundation
+              &copy; 2008-2014 The Apache Software Foundation
               <br/>
               Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
             </div>

Modified: karaf/site/production/manual/latest/quick-start.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/quick-start.html?rev=1688715&r1=1688714&r2=1688715&view=diff
==============================================================================
--- karaf/site/production/manual/latest/quick-start.html (original)
+++ karaf/site/production/manual/latest/quick-start.html Wed Jul  1 19:43:35 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 3.0.3-SNAPSHOT Guides
+      Apache Karaf 4.0.1-SNAPSHOT Guides
     </title>
   </head>
   <body>
@@ -101,7 +101,7 @@
               </td>
               <td height="100%" width="100%">
                 <div class="wiki-content">
-<h1 id="QuickStart">Quick Start</h1><p>This instructions should help you get Apache Karaf up and running in 5 to 15 minutes.</p><h2 id="Prerequisites">Prerequisites</h2><p>Karaf requires a Java SE 7 environment to run. Refer to <a href="http://www.oracle.com/technetwork/java/javase/">http://www.oracle.com/technetwork/java/javase/</a> for details on how to download and install Java SE 1.7 or greater.</p><ul><li>Open a Web browser and access the following URL: <a href="http://karaf.apache.org/index/community/download.html">http://karaf.apache.org/index/community/download.html</a></li><li>Download the binary distribution that matches your system (zip for windows, tar.gz for unixes) </li><li>Extract the archive a new folder on your hard drive; for example in c:\karaf - from now on this directory will be referenced as &lt;KARAF_HOME>.</li></ul><h2 id="Starttheserver">Start the server</h2><p>Open a command line console and change the directory to &lt;KARAF_HOME>. </p><p>To start the serve
 r, run the following command in Windows:</p><pre>
+<h1 id="QuickStart">Quick Start</h1><p>This instructions should help you get Apache Karaf up and running in 5 to 15 minutes.</p><h2 id="Prerequisites">Prerequisites</h2><p>Karaf requires a Java SE 7 or Java SE 8 environment to run. Refer to <a href="http://www.oracle.com/technetwork/java/javase/">http://www.oracle.com/technetwork/java/javase/</a> for details on how to download and install Java SE 1.7 or greater.</p><ul><li>Open a Web browser and access the following URL: <a href="http://karaf.apache.org/index/community/download.html">http://karaf.apache.org/index/community/download.html</a></li><li>Download the binary distribution that matches your system (zip for windows, tar.gz for unixes) </li><li>Extract the archive a new folder on your hard drive; for example in c:\karaf - from now on this directory will be referenced as &lt;KARAF_HOME>.</li></ul><h2 id="Starttheserver">Start the server</h2><p>Open a command line console and change the directory to &lt;KARAF_HOME>. </p><p>To st
 art the server, run the following command in Windows:</p><pre>
 bin\karaf.bat
 </pre><p>respectively on Unix:</p><pre>
 bin/karaf
@@ -112,7 +112,7 @@ bin/karaf
      / /| |/ /_/ / /  / /_/ / __/
     /_/ |_|\__,_/_/   \__,_/_/
 
-  Apache Karaf (3.0.0)
+  Apache Karaf (4.0.0)
 
 Hit '&lt;tab>' for a list of available commands
 and '[cmd] --help' for help on a specific command.
@@ -121,13 +121,16 @@ Hit '&lt;ctrl-d>' or type 'system:shutdo
 karaf@root()>
 
 </pre><h2 id="SomeshellBasics">Some shell Basics</h2><p>You can now run your first command.  Simply type the <tt>&lt;tab></tt> key in the console.</p><pre>
-karaf@root> Display all 183 possibilities? (y or n)
-*:config                            *:dev                               *:feature                           *:instance                          *:jaas                              *:kar                               *:log                               *:package
-*:region                            *:service                           *:shell                             *:ssh                               addbundle                           addfilter                           addregion                           alias
-cancel                              cl                                  clear                               clone                               config                              config:cancel                       config:delete                       config:edit
-config:list                         config:property-append              config:property-delete              config:property-list                config:property-set                 config:update                       connect                             create
-date                                delete                              destroy                             dev                                 dev:dump-create                     display                             dump-create                         each
+karaf@root()> Display all 294 possibilities? (y or n)
 ...
+shell:logout                        shell:more                          shell:new                           shell:printf                        shell:sleep                         shell:sort                          shell:source
+shell:stack-traces-print            shell:tac                           shell:tail                          shell:threads                       shell:watch                         shell:wc                            shell:while
+shutdown                            sleep                               sort                                source                              ssh                                 ssh                                 ssh-host-change
+ssh-port-change                     ssh:ssh                             stack-traces-print                  start                               start-level                         status                              stop
+su                                  sudo                                system                              system:framework                    system:name                         system:property                     system:shutdown
+system:start-level                  system:version                      tac                                 tail                                threads                             tree-show                           uninstall
+update                              user-add                            user-delete                         user-list                           version                             version-list                        wait
+watch                               wc                                  while
 </pre><p>You can then grab more specific help for a given command using the <tt>--help</tt> option for this command:</p><pre>
 karaf@root()> bundle:list --help
 DESCRIPTION
@@ -136,38 +139,55 @@ DESCRIPTION
         Lists all installed bundles.
 
 SYNTAX
-        bundle:list [options]
+        bundle:list [options] [ids]
+
+ARGUMENTS
+        ids
+                The list of bundle (identified by IDs or name or name/version) separated by whitespaces
 
 OPTIONS
-        -u
-                Shows the update locations
-        --help
-                Display this help message
-        --table
-                Show bundles using a shell table
         -t
                 Specifies the bundle threshold; bundles with a start-level less than this value will not get printed out.
-        -l
-                Show the locations
+        --no-format
+                Disable table rendered output
         -s
                 Shows the symbolic name
+        -l
+                Show the locations
+        --no-ellipsis
 
+        --help
+                Display this help message
+        -u
+                Shows the update locations
+        --context, -c
+                Use the given bundle context
+                (defaults to 0)
+        -r
+                Shows the bundle revisions
 </pre><p>Note that the console supports tab completion so if your start typing a command it will show possible completions and also auto complete if there is only one completion.</p><h2 id="Deployasampleapplication">Deploy a sample application</h2><p>While you will learn in the Karaf user's guide how to fully use and leverage Apache Karaf, let's install a sample <a href="http://camel.apache.org">Apache Camel</a> application for now:</p><p>In the console, run the following commands:</p><pre>
-karaf@root()> feature:repo-add camel 2.10.0
-Adding feature url mvn:org.apache.camel.karaf/apache-camel/2.10.0/xml/features
+karaf@root()> feature:repo-add camel 2.15.2
+Adding feature url mvn:org.apache.camel.karaf/apache-camel/2.15.2/xml/features
 karaf@root()> feature:install camel-spring
-karaf@root()> bundle:install -s mvn:org.apache.camel/camel-example-osgi/2.10.1
-</pre><p>The example installed is using Camel to start a timer every 2 seconds and output a message on the console.<br/>The previous commands download the Camel features descriptor and install the example feature.</p><pre>
->>>> SpringDSL set body:  Fri Jan 07 11:59:51 CET 2011
->>>> SpringDSL set body:  Fri Jan 07 11:59:53 CET 2011
->>>> SpringDSL set body:  Fri Jan 07 11:59:55 CET 2011
-
-</pre><h3 id="Stoppinganduninstallingthesampleapplication">Stopping and uninstalling the sample application</h3><p>To stop this demo, run the following command:</p><pre>
-karaf@root()> bundle:stop org.apache.camel.camel-example-osgi
+karaf@root()> bundle:install -s mvn:org.apache.camel/camel-example-osgi/2.15.2
+Bundle ID: 82
+</pre><p>The example installed is using Camel to start a timer every 2 seconds and output a message in the log.<br/>The previous commands download the Camel features descriptor and install the example feature.</p><p>You can display the log in the shell:</p><pre>
+karaf@root()> log:display 
+...
+2015-06-30 13:39:44,731 | INFO  |  timer://myTimer | ExampleRouter                    | 53 - org.apache.camel.camel-core - 2.15.2 | Exchange[ExchangePattern: InOnly, BodyType: String, Body: SpringDSL set body:  Tue Jun 30 13:39:44 CEST 2015]
+2015-06-30 13:39:46,730 | INFO  |  timer://myTimer | MyTransform                      | 82 - camel-example-osgi - 2.15.2 | >>>> SpringDSL set body:  Tue Jun 30 13:39:46 CEST 2015
+2015-06-30 13:39:46,731 | INFO  |  timer://myTimer | ExampleRouter                    | 53 - org.apache.camel.camel-core - 2.15.2 | Exchange[ExchangePattern: InOnly, BodyType: String, Body: SpringDSL set body:  Tue Jun 30 13:39:46 CEST 2015]
+2015-06-30 13:39:48,730 | INFO  |  timer://myTimer | MyTransform                      | 82 - camel-example-osgi - 2.15.2 | >>>> SpringDSL set body:  Tue Jun 30 13:39:48 CEST 2015
+2015-06-30 13:39:48,730 | INFO  |  timer://myTimer | ExampleRouter                    | 53 - org.apache.camel.camel-core - 2.15.2 | Exchange[ExchangePattern: InOnly, BodyType: String, Body: SpringDSL set body:  Tue Jun 30 13:39:48 CEST 2015]
+</pre><h3 id="Stoppinganduninstallingthesampleapplication">Stopping and uninstalling the sample application</h3><p>To stop and uninstall the demo, run the following command:</p><pre>
+karaf@root()> bundle:stop camel-example-osgi
+karaf@root()> bundle:uninstall camel-example-osgi
 </pre><h2 id="StoppingKaraf">Stopping Karaf</h2><p>To stop Karaf from the console, enter <tt>^D</tt> in the console:</p><pre>
 ^D
 </pre><p>Alternatively, you can also run the following command:</p><pre>
-system:shutdown
+karaf@root()> system:shutdown
+</pre><p>halt is also an alias to system:shutdown:</p><pre>
+karaf@root()> halt
 </pre><h3 id="CleaningtheKarafstate">Cleaning the Karaf state</h3><p>Normally Karaf remembers the features and bundles you installed and started. The reset Karaf into a clean state just delete the data directory when karaf is not running.</p><h2 id="Summary">Summary</h2><p>This document showed how simple it is to have Apache Karaf up and running and install a simple Apache Camel application.</p>
                 </div>
               </td>
@@ -188,7 +208,7 @@ system:shutdown
         <td id="cell-3-2">
           <div id="footer">
             <div id="site-footer">
-              &copy; 2008-2011 The Apache Software Foundation
+              &copy; 2008-2014 The Apache Software Foundation
               <br/>
               Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
             </div>