Modified: karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html (original) +++ karaf/site/production/manual/latest-2.3.x/developers-guide/writing-tests.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> @@ -101,164 +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 2.3.0 and 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"><pre name='code' class='brush: xml; gutter: false;'><code> -<!-- Karaf Test Framework Version --> -<dependency> - <groupId>org.apache.karaf.tooling.exam</groupId> - <artifactId>org.apache.karaf.tooling.exam.container</artifactId> - <version>2.3.2</version> - <scope>test</scope> -</dependency> -<!-- Pax Exam version you would like to use. At least 2.2.x is required. --> -<dependency> - <groupId>org.ops4j.pax.exam</groupId> - <artifactId>pax-exam-junit4</artifactId> - <version>2.6.0</version> - <scope>test</scope> -</dependency></code></pre></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"><pre name='code' class='brush: xml; gutter: false;'><code> -<dependency> - <groupId>org.apache.karaf</groupId> - <artifactId>apache-karaf</artifactId> - <version>2.3.2</version> - <type>zip</type> - <scope>test</scope> -</dependency></code></pre></div><p>If you want to make use of Exams "versionAsInProject" feature you also need to add the following section:</p><div class="syntax"><pre name='code' class='brush: xml; gutter: false;'><code> -<build> - <plugins> - <plugin> - <groupId>org.apache.servicemix.tooling</groupId> - <artifactId>depends-maven-plugin</artifactId> - <version>${plugin.depends.version}</version> - <executions> - <execution> - <id>generate-depends-file</id> - <goals> - <goal>generate-depends-file</goal> - </goals> - </execution> - </executions> - </plugin> - </plugins> -</build></code></pre></div><p>With this done we can start writing our first test case:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code> -import static junit.framework.Assert.assertTrue; -import static org.apache.karaf.tooling.exam.options.KarafDistributionOption.karafDistributionConfiguration; -import static org.ops4j.pax.exam.CoreOptions.maven; - -import org.junit.Test; -import org.junit.runner.RunWith; -import org.ops4j.pax.exam.Option; -import org.ops4j.pax.exam.junit.Configuration; -import org.ops4j.pax.exam.junit.ExamReactorStrategy; -import org.ops4j.pax.exam.junit.JUnit4TestRunner; -import org.ops4j.pax.exam.spi.reactors.AllConfinedStagedReactorFactory; - -@RunWith(JUnit4TestRunner.class) -@ExamReactorStrategy(AllConfinedStagedReactorFactory.class) -public class VersionAsInProjectKarafTest { - - @Configuration - public Option[] config() { - return new Option[]{ karafDistributionConfiguration().frameworkUrl( - maven().groupId("org.apache.karaf").artifactId("apache-karaf").type("zip").versionAsInProject()) - .karafVersion("2.2.4").name("Apache Karaf")}; - } - - @Test - public void test() throws Exception { - assertTrue(true); - } -}</code></pre></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 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"><pre name='code' class='brush: java; gutter: false;'><code> -new KarafDistributionConfigurationOption( - "mvn:org.apache.karaf/apache-karaf/2.2.4/zip", // artifact to unpack and use - "karaf", // name; display only - "2.2.4") // the karaf version; this one is relevant since the startup script differs between versions</code></pre></div><p>or for Servicemix e.g.</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code> -new KarafDistributionConfigurationOption( - "mvn:org.apache.servicemix/apache-servicemix/4.4.0/zip", // artifact to unpack and use - "servicemix", // name; display only - "2.2.4") // the karaf version; this one is relevant since the startup script differs between versions</code></pre></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"><pre name='code' class='brush: xml; gutter: false;'><code> -... -<dependency> - <groupId>org.apache.karaf</groupId> - <artifactId>apache-karaf</artifactId> - <type>zip</type> - <classifier>bin</classifier> - <scope>test</scope> -</dependency> -... -<plugin> - <groupId>org.apache.servicemix.tooling</groupId> - <artifactId>depends-maven-plugin</artifactId> - <executions> - <execution> - <id>generate-depends-file</id> - <goals> - <goal>generate-depends-file</goal> - </goals> - </execution> - </executions> -</plugin></code></pre></div><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration - public Option[] config() { - return new Option[]{ karafDistributionConfiguration().frameworkUrl( - maven().groupId("org.apache.karaf").artifactId("apache-karaf").type("zip") - .classifier("bin").versionAsInProject()) }; - }</code></pre></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"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip") - .unpackDirectory(new File("target/paxexam/unpack/")) }; -}</code></pre></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"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip") - .useDeployFolder(false)) }; -}</code></pre></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"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ - new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/2.3.2/zip", - Platform.WINDOWS).executable("bin\\karaf.bat").filesToMakeExecutable("bin\\admin.bat"), - new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/2.3.2/tar.gz", "karaf", - Platform.NIX).executable("bin/karaf").filesToMakeExecutable("bin/admin") }; -}</code></pre></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"><pre name='code' class='brush: java; gutter: false;'><code> -new KarafDistributionConfigurationFilePutOption( - "etc/config.properties", // config file to modify based on karaf.base - "karaf.framework", // key to add or change - "equinox") // value to add or change</code></pre></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 pro perty 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"><pre name='code' class='brush: java; gutter: false;'><code> -new KarafDistributionConfigurationFileReplacementOption("etc/tests.cfg", new File( - "src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey"));</code></pre></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">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"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip"), - configureConsole().ignoreLocalConsole().startRemoteShell() }; -}</code></pre></div><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip"), - configureConsole().startLocalConsole(), configureConsole().ignoreRemoteShell() }; -}</code></pre></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"><pre name='code' class='brush: java; gutter: false;'><code> -import static org.openengsb.labs.paxexam.karaf.options.KarafDistributionOption.logLevel; -... -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip"), - logLevel(LogLevel.TRACE) }; -}</code></pre></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"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip"), - doNotModifyLogConfiguration() }; -}</code></pre></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"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip"), - keepRuntimeFolder() }; -}</code></pre></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 start lvl of the bundles provide d by the test-frameworks features.xml. Simply use it as a new option like:</p><div class="syntax"><pre name='code' class='brush: java; gutter: false;'><code> -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/2.3.2/zip"), - useOwnExamBundlesStartLevel(4) }; -}</code></pre></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 2.3.0 and 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"><!-- Karaf Test Framework Version --></span>
<span class="nt"><dependency></span>
 <span class="nt"><groupId></span>org.apache.karaf.tooling.exam<span class="nt"></groupId></span>
 <span class=" nt"><artifactId></span>org.apache.karaf.tooling.exam.container<span class="nt"></artifactId></span>
 <span class="nt"><version></span>2.3.7-SNAPSHOT<span class="nt"></version></span>
 <span class="nt"><scope></span>test<span class="nt"></scope></span>
<span class="nt"></dependency></span>
<span class="c"><!-- Pax Exam version you would like to use. At least 2.2.x is required. --></span>
<span class="nt"><dependency></span>
 <span class="nt"><groupId></span>org.ops4j.pax.exam<span class="nt"></groupId></span>
 <span class="nt"><artifactId></span>pax-exam-junit4<span class="nt"></artifactId></span>
 <span class="nt"><version></span>2.6.0<span class="nt"></version></span>
 <span class="nt"><scope></span>test<span class="nt"></scope></span>
<span class="nt"></dependency></span>
</pre></div>
< /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"><dependency></span>
 <span class="nt"><groupId></span>org.apache.karaf<span class="nt"></groupId></span>
 <span class="nt"><artifactId></span>apache-karaf<span class="nt"></artifactId></span>
 <span class="nt"><version></span>2.3.7-SNAPSHOT<span class="nt"></version></span>
 <span class="nt"><type></span>zip<span class="nt"></type></span>
 <span class="nt"><scope></span>test<span class="nt"></scope></span>
<span class="nt"></dependency></span>
</pre></div>
</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 class="highlight"><pre><span class="nt"><build></span>
 <span class="nt"><plugins></span>
 <span class="nt"><plugin></span>
 <span class="nt"><groupId></span>org.apache.servicemix.tooling<span class="nt"></groupId></span>
 <span class="nt"><artifactId></span>depends-maven-plugin<span class="nt"></artifactId></span>
 <span class="nt"><version></span>${plugin.depends.version}<span class="nt"></version></span>
 <span class="nt"><executions></span>
 <span class="nt"><execution></span>
 <span class="nt"><id></span>generate-depends-file<span class="nt"></id></span>
 <span class="nt"><goals></span>
 <span class="nt"><goal></span>generate-depends-file<span class="nt"></goal></span>
 <span class="nt"></goals></span>� A; <span class="nt"></execution></span>
 <span class="nt"></executions></span>
 <span class="nt"></plugin></span>
 <span class="nt"></plugins></span>
<span class="nt"></build></span>
</pre></div>
</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>
<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><sp an 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>
<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>

<span class="kn">import</span> <span class="nn">org.junit.Test</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.junit.runner.RunWith</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.Option</span><span class="o">;</span>
<span class="kn">import</span> <span class=" nn">org.ops4j.pax.exam.junit.Configuration</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.ExamReactorStrategy</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.junit.JUnit4TestRunner</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.ops4j.pax.exam.spi.reactors.AllConfinedStagedReactorFactory</span><span class="o">;</span>

<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>
<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>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">VersionAsInProjectKarafTest</span> <span class="o">{</span>

 <span class="nd">@Configuration</span>
 <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>
 <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>
 <span class="n">maven</span><span class="o">().</span><span class="na">groupId</span><span class="o">(</span><span class="s">"org.apache.karaf"</span><span class="o">).</span><span class="na">artifactId</span><span class="o">(</span><span class="s">"apache-karaf"</span><span class="o">).</span><span class="na">type</span><span class="o">(</span><span class="s">"zip"</span><span class="o">).</span><span class="na">v ersionAsInProject</span><span class="o">())</span>
 <span class="o">.</span><span class="na">karafVersion</span><span class="o">(</span><span class="s">"2.2.4"</span><span class="o">).</span><span class="na">name</span><span class="o">(</span><span class="s">"Apache Karaf"</span><span class="o">)};</span>
 <span class="o">}</span>

 <span class="nd">@Test</span>
 <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>
 <span class="n">assertTrue</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
 <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div><h2 id="Commands">Commands</h2><p>Basically the Pax Exam - Karaf bridge introduced with 3.0 should support all commands you kn ow from Pax Exam 2.x. In addition 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>
 <span class="s">"mvn:org.apache.karaf/apache-karaf/2.2. 4/zip"</span><span class="o">,</span> <span class="c1">// artifact to unpack and use</span>
 <span class="s">"karaf"</span><span class="o">,</span> <span class="c1">// name; display only</span>
 <span class="s">"2.2.4"</span><span class="o">)</span> <span class="c1">// the karaf version; this one is relevant since the startup script differs between versions</span>
</pre></div>
</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>
 <span class="s">"mvn:org.apache.servicemix/apache-servicemix/4.4.0/zip"</span><span class="o">,</span> <span class="c1">// artifact to unpack and use</span>
 <span class="s">"servicemix"</span><span class="o">,</span> <span class="c1">// name; display only</span>
 <span class="s">"2.2.4"</span><span class="o">) </span> <span class="c1">// the karaf version; this one is relevant since the startup script differs between versions</span>
</pre></div>
</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>...
<span class="nt"><dependency></span>
 <span class="nt"><groupId></span>org.apache.karaf<span class="nt"></groupId></span>
 <span class="nt"><artifactId></span>apache-karaf<span class="nt"></artifactId></span>
 <span class="nt"><type></span>zip<span class="nt"></type></span>
 <span class="nt"><classifier></span>bin<span class="nt"></classifier> ;</span>
 <span class="nt"><scope></span>test<span class="nt"></scope></span>
<span class="nt"></dependency></span>
...
<span class="nt"><plugin></span>
 <span class="nt"><groupId></span>org.apache.servicemix.tooling<span class="nt"></groupId></span>
 <span class="nt"><artifactId></span>depends-maven-plugin<span class="nt"></artifactId></span>
 <span class="nt"><executions></span>
 <span class="nt"><execution></span>
 <span class="nt"><id></span>generate-depends-file<span class="nt"></id></span>
 <span class="nt"><goals></span>
 <span class="nt"><goal></span>generate-depends-file<span class="nt"></goal></span>
 <span class="nt"></goals></span>
 <span class="nt"></execution></span>
 <span class="nt"></executions></span>
<span class="nt"></ plugin></span>
</pre></div>
</div><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>
 <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>
 <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>
 <span class="n">maven</span><span class="o">().</span><span class="na">groupId</span><span class="o">(</span><span class="s">"org.apache.karaf"</span><span class="o">).</span><span class="na">artifactId</span><span class="o">(</span><span class="s">"apache-karaf"</span><span class="o">).</span><span class="na">type</span><span class="o">(</span><span class="s">"zip&q uot;</span><span class="o">)</span>
 <span class="o">.</span><span class="na">classifier</span><span class="o">(</span><span class="s">"bin"</span><span class="o">).</span><span class="na">versionAsInProject</span><span class="o">())</span> <span class="o">};</span>
 <span class="o">}</span>
</pre></div>
</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">@Configurat ion</span>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">)</span>
 <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">"target/paxexam/unpack/"</span><span class="o">))</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</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>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">)</span>
 <span class="o">.</span><span clas s="na">useDeployFolder</span><span class="o">(</span><span class="kc">false</span><span class="o">))</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</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>
<span c lass="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>
 <span class="k">return</span> <span class="k">new</span> <span class="n">Option</span><span class="o">[]{</span>
 <span class="k">new</span> <span class="nf">KarafDistributionKitConfigurationOption</span><span class="o">(</span><span class="s">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">,</span>
 <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">"bin\\karaf.bat"</span><span class="o">).</span><span class="na">filesToMakeExecutable</span><span class="o">(</span><span class="s">"bin\\admin.bat"</span><span class="o">),</span>
 <span class="k">new</span> <span class="nf">KarafDi stributionKitConfigurationOption</span><span class="o">(</span><span class="s">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/tar.gz"</span><span class="o">,</span> <span class="s">"karaf"</span><span class="o">,</span>
 <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">"bin/karaf"</span><span class="o">).</span><span class="na">filesToMakeExecutable</span><span class="o">(</span><span class="s">"bin/admin"</span><span class="o">)</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</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>
 <span class="s">"etc/config.properties"</span><span class="o">,</span> <span class="c1">// config file to modify based on karaf.base</span>
 <span class="s">"karaf.framework"</span><span class="o">,</span> <span class="c1">// key to add or change</span>
 <span class="s">"equinox"</span><span class="o">)</span> <span class="c1">// value to add or change</span>
</pre></div>
</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">KarafDistributionConfiguratio nFileReplacementOption</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">"etc/tests.cfg"</span><span class="o">,</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span>
 <span class="s">"src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey"</span><span class="o">));</span>
</pre></div>
</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 st artup.</p><h3 id="KarafDistributionConfigurationConsoleOption">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>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">),</span> 
 <span class="n">configureConsole</span><span class="o">().</span><span class="na">ignoreLocalConsole</span><sp an class="o">().</span><span class="na">startRemoteShell</span><span class="o">()</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</div><div class="syntax"><div class="highlight"><pre><span class="nd">@Configuration</span>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">),</span> 
 <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">ignoreRemot eShell</span><span class="o">()</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</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">.</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>
<span class="o">...</span>
<span class="nd">@Configuration</span>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">),</span> 
 <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>
<span class="o">}</span>
</pre></div>
</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>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">),</span> 
 <span class="n">doNotModifyLogConfiguration</span><span class="o">()</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</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>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">) ,</span> 
 <span class="n">keepRuntimeFolder</span><span class="o">()</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</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 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>
<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>
 <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">"mvn:org.apache.karaf/apache-karaf/2.3.7-SNAPSHOT/zip"</span><span class="o">),</span>
 <span class="n">useOwnExamBundlesStartLevel</span><span class="o">(</span><span class="mi">4</span><span class="o">)</span> <span class="o">};</span>
<span class="o">}</span>
</pre></div>
</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 spec ific scripts. To use it follow the explanation of the KarafDistributionKitConfigurationOption in the Commands section.</p> </div> </td> </tr>
Modified: karaf/site/production/manual/latest-2.3.x/index.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/index.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/index.html (original) +++ karaf/site/production/manual/latest-2.3.x/index.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/overview.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/overview.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/overview.html (original) +++ karaf/site/production/manual/latest-2.3.x/overview.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/quick-start.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/quick-start.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/quick-start.html (original) +++ karaf/site/production/manual/latest-2.3.x/quick-start.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/child-instances.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/child-instances.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/child-instances.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/child-instances.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/configuration.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/configuration.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/configuration.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/configuration.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/deployer.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/deployer.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/deployer.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/deployer.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/directory-structure.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/directory-structure.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/directory-structure.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/directory-structure.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/failover.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/failover.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/failover.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/failover.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> @@ -116,7 +116,7 @@ karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30 -</pre><p><strong>Note</strong>:</p><ul><li>This process will fail if a JDBC driver is not on the classpath.</li><li>The "sample" database referred to above will be created if it does not exist.</li><li>The first Karaf instance to acquire the locking table is the master instance.</li><li>If the connection to the database is lost, the master instance tries to gracefully shutdown, allowing a slave instance to become master when the database service is restored. The former master will require a manual restart.</li></ul><h3 id="JDBClockingonOracle">JDBC locking on Oracle</h3><p>If you are using Oracle as your database for JDBC locking, the <tt>karaf.lock.class</tt> property in the <tt>$KARAF_HOME/etc/system.properties</tt> file must point to <tt>org.apache.karaf.main.OracleJDBCLock</tt>.</p><p>Otherwise, configure the system.properties file as normal for your setup, for example:</p><pre>karaf.lock=true +</pre><p><strong>Note</strong>:</p><ul><li>This process will fail if a JDBC driver is not on the classpath.</li><li>The "sample" database referred to above will be created if it does not exist.</li><li>The first Karaf instance to acquire the locking table is the master instance.</li><li>If the connection to the database is lost, the master instance tries to gracefully shutdown, allowing a slave instance to become master when the database service is restored. The former master will require a manual restart.</li></ul><div class="warning" style="border: 1px solid #c00;background-color: #fcc;margin: 20px;padding: 0px 6px 0px 6px;"><p>Apache Karaf won't start if the JDBC driver is not present in the <tt>lib/ext</tt> folder.</p></div><h3 id="JDBClockingonOracle">JDBC locking on Oracle</h3><p>If you are using Oracle as your database for JDBC locking, the <tt>karaf.lock.class</tt> property in the <tt>$KARAF_HOME/etc/system.properties</tt> file must point to <tt>org.apache.karaf.main.OracleJ DBCLock</tt>.</p><p>Otherwise, configure the system.properties file as normal for your setup, for example:</p><pre>karaf.lock=true karaf.lock.class=org.apache.karaf.main.OracleJDBCLock karaf.lock.jdbc.url=jdbc:oracle:thin:@hostname:1521:XE karaf.lock.jdbc.driver=oracle.jdbc.OracleDriver @@ -125,7 +125,7 @@ karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30 -</pre><p>As with the default JDBC locking setup, the Oracle JDBC driver JAR file must be in your classpath. You can ensure this by copying the <tt>ojdbc14.jar</tt> into Karaf's <tt>lib</tt> folder before starting Karaf.</p><p><strong>Note</strong>: The <tt>karaf.lock.jdbc.url</tt> requires an active SID, which means you must manually create a database instance before using this particular lock.</p><h3 id="Derby">Derby</h3><p>The same rules apply when using derby. Make sure you have the driver jar file in the Karaf <tt>lib</tt> folder before starting Karaf.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true +</pre><p>Make sure you have the Oracle JDBC driver in the <tt>lib/ext</tt> folder.</p><p><strong>Note</strong>: The <tt>karaf.lock.jdbc.url</tt> requires an active SID, which means you must manually create a database instance before using this particular lock.</p><h3 id="Derby">Derby</h3><p>Make sure you have the driver jar file in the Karaf <tt>lib/ext</tt> folder.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true karaf.lock.class=org.apache.karaf.main.DerbyJDBCLock karaf.lock.jdbc.url=jdbc:derby://127.0.0.1:1527/dbname karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver @@ -134,7 +134,7 @@ karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30 -</pre><h3 id="MySQL">MySQL</h3><p>Make sure you have the MySQL driver jar file in the Karaf <tt>lib</tt> folder before starting Karaf.</p><p><strong>NOTE</strong>: for 2.2.x, 2.3.x you need to rename the MySQL Driver jar to prefix with 'karaf-' in order for karaf to pick it up, otherwise you will see karaf just hang on startup and the log will show you that it could not find the driver.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true +</pre><h3 id="MySQL">MySQL</h3><p>Make sure you have the MySQL driver jar file in the Karaf <tt>lib/ext</tt> folder.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true karaf.lock.class=org.apache.karaf.main.MySQLJDBCLock karaf.lock.jdbc.url=jdbc:mysql://127.0.0.1:3306/dbname karaf.lock.jdbc.driver=com.mysql.jdbc.Driver @@ -143,7 +143,7 @@ karaf.lock.jdbc.password=password karaf.lock.jdbc.table=KARAF_LOCK karaf.lock.jdbc.clustername=karaf karaf.lock.jdbc.timeout=30 -</pre><h3 id="PostgreSQL">PostgreSQL</h3><p>Make sure you have the PostgreSQL driver jar file in the Karaf <tt>lib</tt> folder before starting Karaf.</p><p><strong>NOTE</strong>: for 2.2.x, 2.3.x you need to rename the PostgreSQL Driver jar to prefix with 'karaf-' in order for karaf to pick it up, otherwise you will see karaf just hang on startup and the log will show you that it could not find the driver.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true +</pre><h3 id="PostgreSQL">PostgreSQL</h3><p>Make sure you have the PostgreSQL driver jar file in the Karaf <tt>lib/ext</tt> folder.</p><p>Then make you update the properties in <tt>$KARAF_HOME/etc/system.properties</tt> to look something like this example:</p><pre>karaf.lock=true karaf.lock.class=org.apache.karaf.main.PostgreSQLJDBCLock karaf.lock.jdbc.url=jdbc:postgresql://127.0.0.1:5432/dbname karaf.lock.jdbc.driver=org.postgresql.Driver Modified: karaf/site/production/manual/latest-2.3.x/users-guide/http.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/http.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/http.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/http.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/index.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/index.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/index.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/index.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/installation.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/installation.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/installation.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/installation.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> @@ -101,13 +101,13 @@ </td> <td height="100%" width="100%"> <div class="wiki-content"> -<h1 id="Installation">Installation</h1><p>This chapter describes how to install Apache Karaf for both Unix and Windows platforms, including<br/>prerequisite software and necessary download links.</p><h2 id="PreInstallationRequirements">Pre-Installation Requirements</h2><p><strong>Hardware:</strong></p><ul><li>20 MB of free disk space for the Apache Karaf x.y binary distribution.</li></ul><p><strong>Operating Systems:</strong></p><ul><li>Windows: Windows Vista, Windows XP SP2, Windows 2000.</li><li>Unix: Ubuntu Linux, Powerdog Linux, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.</li></ul><p><strong>Environment:</strong></p><ul><li>Java SE Development Kit 1.5.x or greater (<a href="http://www.oracle.com/technetwork/java/javase/";>http://www.oracle.com/technetwork/java/javase/</a>).</li><li>The JAVA_HOME environment variable must be set to the directory where the Java runtime is installed, e.g., <tt>c:\Program Files\jdk.1.5.0_06</tt>. To accomplish that, press Window s key and Break key together, switch to "Advanced" tab and click on "Environment Variables". Here, check for the variable and, if necessary, add it.</li></ul><h2 id="BuildingfromSources">Building from Sources</h2><p>If you intend to build Karaf from the sources, the requirements are a bit different:</p><p><strong>Hardware:</strong></p><ul><li>200 MB of free disk space for the Apache Karaf x.y source distributions or SVN checkout, the Maven build and the dependencies Maven downloads.</li></ul><p><strong>Environment:</strong></p><ul><li>Java SE Developement Kit 1.5.x or greater (<a href="http://www.oracle.com/technetwork/java/javase/";>http://www.oracle.com/technetwork/java/javase/</a>).</li><li>Apache Maven 2.2.1 (<a href="http://maven.apache.org/download.html";>http://maven.apache.org/download.html</a>).</li></ul><h3 id="BuildingonWindows">Building on Windows</h3><p>This procedure explains how to download and install the source distribution on a Windows system. <strong>NOTE:</strong> Karaf requires Java 5 is compile, build and run.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/index/community/download.html";>http://karaf.apache.org/index/community/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a source distribution, the filename will be similar to: <tt>apache-karaf-x.y-src.zip</tt>.</p></li><li>Extract Karaf from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</li><li><span id="WindowsSourceInstallation"></span> Build Karaf using Maven 2.2.1 or greater and Java 5.<p>The recommended method of building Karaf is the following:</p><pre> +<h1 id="Installation">Installation</h1><p>This chapter describes how to install Apache Karaf for both Unix and Windows platforms, including<br/>prerequisite software and necessary download links.</p><h2 id="PreInstallationRequirements">Pre-Installation Requirements</h2><p><strong>Hardware:</strong></p><ul><li>20 MB of free disk space for the Apache Karaf x.y binary distribution.</li></ul><p><strong>Operating Systems:</strong></p><ul><li>Windows: Windows Vista, Windows XP SP2, Windows 2000.</li><li>Unix: Ubuntu Linux, Powerdog Linux, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.</li></ul><p><strong>Environment:</strong></p><ul><li>Java SE Development Kit 1.5.x or greater (<a href="http://www.oracle.com/technetwork/java/javase/";>http://www.oracle.com/technetwork/java/javase/</a>).</li><li>The JAVA_HOME environment variable must be set to the directory where the Java runtime is installed, e.g., <tt>c:\Program Files\jdk.1.5.0_06</tt>. To accomplish that, press Window s key and Break key together, switch to "Advanced" tab and click on "Environment Variables". Here, check for the variable and, if necessary, add it.</li></ul><h2 id="BuildingfromSources">Building from Sources</h2><p>If you intend to build Karaf from the sources, the requirements are a bit different:</p><p><strong>Hardware:</strong></p><ul><li>200 MB of free disk space for the Apache Karaf x.y source distributions or git clone, the Maven build and the dependencies Maven downloads.</li></ul><p><strong>Environment:</strong></p><ul><li>Java SE Developement Kit 1.5.x or greater (<a href="http://www.oracle.com/technetwork/java/javase/";>http://www.oracle.com/technetwork/java/javase/</a>).</li><li>Apache Maven 2.2.1 (<a href="http://maven.apache.org/download.html";>http://maven.apache.org/download.html</a>).</li></ul><h3 id="BuildingonWindows">Building on Windows</h3><p>This procedure explains how to download and install the source distribution on a Windows system. <strong>NOTE:</strong> Kar af requires Java 5 is compile, build and run.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/index/community/download.html";>http://karaf.apache.org/index/community/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a source distribution, the filename will be similar to: <tt>apache-karaf-x.y-src.zip</tt>.</p></li><li>Extract Karaf from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</li><li><span id="WindowsSourceInstallation"></span> Build Karaf using Maven 2.2.1 or greater and Java 5.<p>The recommended method of building Karaf is the following:</p><pre> cd [karaf_install_dir]\src </pre><p> where <tt>karaf_install_dir</tt> is the directory in which Karaf was installed.</p><pre> mvn </pre><p>Both steps take around 10 to 15 minutes.</p></li><li>Unzip the distribution using your favorite zip tool. The windows distribution is available at<pre> [karaf_install_dir]\assembly\target\apache-karaf-x.y.zip -</pre></li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><h3 id="BuildingonUnix">Building on Unix</h3><p>This procedure explains how to download and install the source distribution on a Unix system. This procedure assumes the Unix machine has a browser. Please see the previous <a href="#UnixBinaryInstallation.html">Unix Binary Installation</a> section for ideas on how to install Karaf without a browser. <strong>NOTE:</strong> Karaf requires Java 5 to compile, build and run.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/download.html";>http://karaf.apache.org/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a source distribution, the filename will be similar to: <tt>apache-karaf-x.y-src.tar.gz</tt>.</p></li><li>Extract the files from the ZIP file into a directory of your choice. For example:<pre> +</pre></li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><h3 id="BuildingonUnix">Building on Unix</h3><p>This procedure explains how to download and install the source distribution on a Unix system. This procedure assumes the Unix machine has a browser. Please see the previous <a href="#UnixBinaryInstallation.html">Unix Binary Installation</a> section for ideas on how to install Karaf without a browser. <strong>NOTE:</strong> Karaf requires Java 5 to compile, build and run.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/index/community/download.html";>http://karaf.apache.org/index/community/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a source distribution, the filename will be similar to: <tt>apache-karaf-x.y-src.tar.gz</tt>.</p></li><li>Extract the files from the ZIP file into a directory of your choice. For example:<pre> gunzip apache-karaf-x.y-src.tar.gz tar xvf apache-karaf-x.y-src.tar </pre><p>Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</p></li><li>Build Karaf using Maven:<p>The preferred method of building Karaf is the following:</p><pre> @@ -119,7 +119,7 @@ cd [karaf_install_dir]/assembly/target gunzip apache-karaf-x.y.tar.gz tar xvf apache-karaf-x.y.tar </pre></li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><h2 id="InstallationProcedureforWindows">Installation Procedure for Windows</h2><p>This procedure explains how to download and install the binary distribution on a Windows system.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/index/community/download.html";>http://karaf.apache.org/index/community/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a binary distribution, the filename will be similar to: <tt>apache-karaf-x.y.zip</tt>.</p></li><li>Extract the files from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li><li>Optional: see <a href="colorized-console.html">enabling Colorized Console Output On Windows</ a></li></ol><div class="tip" style="border: 1px solid #090;background-color: #dfd;margin: 20px;padding: 0px 6px 0px 6px;"><p><b>Handy Hint</b></p><p>In case you have to install Karaf into a very deep path or a path containing illegal characters for Java paths, e.g. !, % etc., you may add a bat file to <em>start \-> startup</em> that executes</p><pre>subst S: "C:\your very % problematic path!\KARAF" -</pre><p>so your Karaf root directory is S: <del>-</del> which works for sure and is short to type.</p></div><h2 id="InstallationProcedureForUnix">Installation Procedure For Unix</h2><p>This procedure explains how to download and install the binary distribution on a Unix system.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/download.html";>http://karaf.apache.org/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a binary Unix distribution, the filename will be similar to: apache-karaf-x.y.tar.gz.</p></li><li>Extract the files from the gzip file into a directory of your choice. For example:<pre> +</pre><p>so your Karaf root directory is S: <del>-</del> which works for sure and is short to type.</p></div><h2 id="InstallationProcedureForUnix">Installation Procedure For Unix</h2><p>This procedure explains how to download and install the binary distribution on a Unix system.</p><ol><li>From a browser, navigate to <a href="http://karaf.apache.org/index/community/download.html";>http://karaf.apache.org/index/community/download.html</a>.</li><li>Scroll down to the "Apache Karaf" section and select the desired distribution.<p>For a binary Unix distribution, the filename will be similar to: apache-karaf-x.y.tar.gz.</p></li><li>Extract the files from the gzip file into a directory of your choice. For example:<pre> gunzip apache-karaf-x.y.tar.gz tar xvf apache-karaf-x.y.tar </pre><p>Please remember the restrictions concerning illegal characters in Java paths, e.g. !, % etc.</p></li><li>Proceed to the <a href="start-stop#Starting Karaf.html">Starting Karaf</a> chapter.</li></ol><h2 id="PostInstallationsteps">Post-Installation steps</h2><p>Thought it is not always required, it is strongly advised to set up the <tt>JAVA_HOME</tt> environment property to point to the JDK you want Karaf to use before starting it.<br/>This property is used to locate the <tt>java</tt> executable and should be configured to point to the home directory of the Java SE 5 or 6 installation.</p> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/jmx.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/jmx.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/jmx.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/jmx.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/jre-tuning.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/jre-tuning.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/jre-tuning.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/jre-tuning.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body> Modified: karaf/site/production/manual/latest-2.3.x/users-guide/kar.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.3.x/users-guide/kar.html?rev=1615948&r1=1615947&r2=1615948&view=diff ============================================================================== --- karaf/site/production/manual/latest-2.3.x/users-guide/kar.html (original) +++ karaf/site/production/manual/latest-2.3.x/users-guide/kar.html Tue Aug 5 15:46:54 2014 @@ -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 2.3.2 Guides + Apache Karaf 2.3.7-SNAPSHOT Guides </title> </head> <body>
