karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1742536 [16/23] - in /karaf/site/production/manual/latest-2.x: ./ commands/ css/ css/scalate/ developers-guide/ images/ users-guide/
Date Fri, 06 May 2016 12:23:18 GMT
Added: karaf/site/production/manual/latest-2.x/developers-guide/creating-bundles.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.x/developers-guide/creating-bundles.html?rev=1742536&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.x/developers-guide/creating-bundles.html (added)
+++ karaf/site/production/manual/latest-2.x/developers-guide/creating-bundles.html Fri May  6 12:23:15 2016
@@ -0,0 +1,292 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> 
+<html lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <meta name="description" content="description goes here"/>
+    <meta name="keywords" content="keywords,goes,here"/>
+    <meta name="author" content="The Apache Karaf Team"/>
+    <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+    <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+    <title>
+      Apache Karaf 2.4.5-SNAPSHOT Guides
+    </title>
+  </head>
+  <body>
+    <table width="100%" cellpadding="0" cellspacing="0">
+      <tr width="100%">
+        <td id="cell-0-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-0-1">
+          &nbsp;
+        </td>
+        <td id="cell-0-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-1-0">
+          &nbsp;
+        </td>
+        <td id="cell-1-1">
+          &nbsp;
+        </td>
+        <td id="cell-1-2">
+          <div style="padding: 5px;">
+            <div id="banner">
+                    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+        <tr>
+          <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+            <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+          </td>
+          <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+            <img border="0" src="../images/asf-logo.png">
+</a>
+          </td>
+        </tr>
+      </table>
+
+            </div>
+            <div id="top-menu">
+              <table border="0" cellpadding="1" cellspacing="0" width="100%">
+                <tr>
+                  <td>
+                    <div align="left"></div>
+                  </td>
+                  <td>
+                    <div align="right">
+                      <p>
+<a href="../index.html" title="Home">Home</a>
+&#124;
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+&#124;
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+                    </div>
+                  </td>
+                </tr>
+              </table>
+            </div>
+          </div>
+        </td>
+        <td id="cell-1-3">
+          &nbsp;
+        </td>
+        <td id="cell-1-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-2-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-2-1">
+          <table>
+            <tr height="100%" valign="top">
+              <td height="100%">
+                <div id="wrapper-menu-page-right">
+                  <div id="wrapper-menu-page-top">
+                    <div id="wrapper-menu-page-bottom">
+                      <div id="menu-page">
+                        <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li><a href
 ="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a></li><li><a hre
 f="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </td>
+              <td height="100%" width="100%">
+                <div class="wiki-content">
+<h1 id="Addextendedinformationtobundles">Add extended information to bundles</h1><p>Karaf supports a OSGI-INF/bundle.info file in a bundle.</p><p>This file is extended description of the bundle. It supports ASCII character declarations (for adding color, formatting, etc).</p><p>For instance, you can define a bundle like this (using Apache Felix maven-bundle-plugin):</p><pre>
+&lt;?xml version="1.0" encoding="UTF-8"?>
+&lt;project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+    &lt;modelVersion>4.0.0&lt;/modelVersion>
+
+    &lt;groupId>my.groupId&lt;/groupId>
+    &lt;artifactId>my.bundle&lt;/artifactId>
+    &lt;version>1.0-SNAPSHOT&lt;/version>
+    &lt;name>My Bundle&lt;/name>
+    &lt;description>My bundle short description&lt;/description>
+
+    &lt;build>
+        &lt;resources>
+            &lt;resource>
+                &lt;directory>/home/jbonofre/Workspace/karaf/manual/src/main/resources&lt;/directory>
+                &lt;filtering>true&lt;/filtering>
+                &lt;includes>
+                    &lt;include>**/*&lt;/include>
+                &lt;/includes>
+            &lt;/resource>
+        &lt;/resources>
+        &lt;plugins>
+            &lt;plugin>
+                &lt;groupId>org.apache.felix&lt;/groupId>
+                &lt;artifactId>maven-bundle-plugin&lt;/artifactId>
+                &lt;version>2.2.0&lt;/version>
+                &lt;extensions>true&lt;/extensions>
+                &lt;configuration>
+                    &lt;instructions>
+                        &lt;Bundle-SymbolicName>manual&lt;/Bundle-SymbolicName>
+                        ...
+                    &lt;/instructions>
+                &lt;/configuration>
+            &lt;/plugin>
+        &lt;/plugins>
+    &lt;/build>
+
+&lt;/project>
+</pre><p>And simply add a src/main/resources/OSGI-INF/bundle.info file containing, for instance:</p><pre>
+\u001B[1mSYNOPSIS\u001B[0m
+    The Apache Software Foundation provides support for the Apache community of open-source software projects.
+    The Apache projects are characterized by a collaborative, consensus based development process, an open and
+    pragmatic software license, and a desire to create high quality software that leads the way in its field.
+    We consider ourselves not simply a group of projects sharing a server, but rather a community of developers
+    and users.
+
+\u001B[1mDESCRIPTION\u001B[0m
+    Long description of your bundle, including usage, etc.
+
+\u001B[1mSEE ALSO\u001B[0m
+    \u001B[36mhttp://yourside\u001B[0m
+    \u001B[36mhttp://yourside/docs\u001B[0m
+
+</pre><p>You can display this extended information using:</p><pre>
+root@karaf> osgi:info
+</pre><h1 id="Creatingbundlesforthirdpartydependencies">Creating bundles for third party dependencies</h1><p>Karaf supports the wrap: protocol execution.</p><p>It allows for directly deploying third party dependencies, like Apache Commons Lang:</p><pre>
+root@karaf> osgi:install wrap:mvn:commons-lang/commons-lang/2.4
+</pre><p>You can specify OSGi statements in the wrap URL:</p><p>from the shell</p><pre>
+root@karaf> osgi:install -s 'wrap:mvn:commons-lang/commons-lang/2.4$Bundle-SymbolicName=commons-lang&amp;Bundle-Version=2.4'
+</pre><p>from features.xml</p><pre>
+&lt;bundle>wrap:mvn:commons-lang/commons-lang/2.4$Bundle-SymbolicName=commons-lang&amp;undle-Version=2.4&lt;/bundle>
+</pre><p>You can also create a wrap bundle for a third party dependency.<br/>This bundle is simply a Maven POM that shades an existing jar and package into a jar bundle.</p><p>For instance, to create an OSGi bundle that wraps Apache Commons Lang, you can simply define the following Maven POM:</p><pre>
+&lt;?xml version="1.0" encoding="UTF-8"?>
+&lt;project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+    &lt;modelVersion>4.0.0&lt;/modelVersion>
+
+    &lt;groupId>osgi.commons-lang&lt;/groupId>
+    &lt;artifactId>osgi.commons-lang&lt;/artifactId>
+    &lt;version>2.4&lt;/version>
+    &lt;packaging>bundle&lt;/packaging>
+    &lt;name>commons-lang OSGi Bundle&lt;/name>
+    &lt;description>This OSGi bundle simply wraps commons-lang-2.4.jar artifact.&lt;/description>
+
+    &lt;dependencies>
+        &lt;dependency>
+            &lt;groupId>commons-lang&lt;/groupId>
+            &lt;artifactId>commons-lang&lt;/artifactId>
+            &lt;version>2.4&lt;/version>
+            &lt;optional>true&lt;/optional>
+        &lt;/dependency>
+    &lt;/dependencies>
+
+    &lt;build>
+        &lt;defaultGoal>install&lt;/defaultGoal>
+
+        &lt;plugin>
+            &lt;groupId>org.apache.maven.plugins&lt;/groupId>
+            &lt;artifactId>maven-shade-plugin&lt;/artifactId>
+            &lt;version>1.1&lt;/version>
+            &lt;executions>
+                &lt;execution>
+                    &lt;phase>package&lt;/phase>
+                    &lt;goals>
+                        &lt;goal>shade&lt;/goal>
+                    &lt;/goals>
+                    &lt;configuration>
+                        &lt;artifactSet>
+                            &lt;includes>
+                                &lt;include>commons-lang:commons-lang&lt;/include>
+                            &lt;/includes>
+                        &lt;/artifactSet>
+                        &lt;filters>
+                            &lt;filter>
+                                &lt;artifact>commons-lang:commons-lang&lt;/artifact>
+                                &lt;excludes>
+                                    &lt;exclude>**&lt;/exclude>
+                                &lt;/excludes>
+                            &lt;/filter>
+                        &lt;/filters>
+                        &lt;promoteTransitiveDependencies>true&lt;/promoteTransitiveDependencies>
+                        &lt;createDependencyReducedPom>true&lt;/createDependencyReducedPom>
+                    &lt;/configuration>
+                &lt;/execution>
+            &lt;/executions>
+        &lt;/plugin>
+        &lt;plugin>
+            &lt;groupId>org.apache.felix&lt;/groupId>
+            &lt;artifactId>maven-bundle-plugin&lt;/artifactId>
+            &lt;version>2.1.0&lt;/version>
+            &lt;extensions>true&lt;/extensions>
+            &lt;configuration>
+                &lt;instructions>
+                    &lt;Bundle-SymbolicName>manual&lt;/Bundle-SymbolicName>
+                    &lt;Export-Package>*&lt;/Export-Package>
+                    &lt;Import-Package>&lt;/Import-Package>
+                    &lt;_versionpolicy>[$(version;==;$(@)),$(version;+;$(@)))&lt;/_versionpolicy>
+                    &lt;_removeheaders>Ignore-Package,Include-Resource,Private-Package,Embed-Dependency&lt;/_removeheaders>
+                &lt;/instructions>
+                &lt;unpackBundle>true&lt;/unpackBundle>
+            &lt;/configuration>
+        &lt;/plugin>
+    &lt;/build>
+
+&lt;/project>
+</pre><p>You have now a OSGi bundle for commons-lang that you can deploy directly:</p><pre>
+root@karaf> osgi:install -s mvn:osgi.commons-lang/osgi.commons-lang/2.4
+</pre><p>Some more information is available at <a href="http://gnodet.blogspot.com/2008/09/id-like-to-talk-bit-about-third-party.html">http://gnodet.blogspot.com/2008/09/id-like-to-talk-bit-about-third-party.html</a>, <a href="http://blog.springsource.com/2008/02/18/creating-osgi-bundles/">http://blog.springsource.com/2008/02/18/creating-osgi-bundles/</a> and <a href="http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html">http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html</a>.</p>
+                </div>
+              </td>
+            </tr>
+          </table>
+        </td>
+        <td id="cell-2-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-3-0">
+          &nbsp;
+        </td>
+        <td id="cell-3-1">
+          &nbsp;
+        </td>
+        <td id="cell-3-2">
+          <div id="footer">
+            <div id="site-footer">
+              &copy; 2008-2011 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>
+          </div>
+        </td>
+        <td id="cell-3-3">
+          &nbsp;
+        </td>
+        <td id="cell-3-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-4-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-4-1">
+          &nbsp;
+        </td>
+        <td id="cell-4-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
\ No newline at end of file

Added: karaf/site/production/manual/latest-2.x/developers-guide/custom-distribution.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.x/developers-guide/custom-distribution.html?rev=1742536&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.x/developers-guide/custom-distribution.html (added)
+++ karaf/site/production/manual/latest-2.x/developers-guide/custom-distribution.html Fri May  6 12:23:15 2016
@@ -0,0 +1,489 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> 
+<html lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <meta name="description" content="description goes here"/>
+    <meta name="keywords" content="keywords,goes,here"/>
+    <meta name="author" content="The Apache Karaf Team"/>
+    <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+    <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+    <title>
+      Apache Karaf 2.4.5-SNAPSHOT Guides
+    </title>
+  </head>
+  <body>
+    <table width="100%" cellpadding="0" cellspacing="0">
+      <tr width="100%">
+        <td id="cell-0-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-0-1">
+          &nbsp;
+        </td>
+        <td id="cell-0-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-1-0">
+          &nbsp;
+        </td>
+        <td id="cell-1-1">
+          &nbsp;
+        </td>
+        <td id="cell-1-2">
+          <div style="padding: 5px;">
+            <div id="banner">
+                    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+        <tr>
+          <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+            <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+          </td>
+          <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+            <img border="0" src="../images/asf-logo.png">
+</a>
+          </td>
+        </tr>
+      </table>
+
+            </div>
+            <div id="top-menu">
+              <table border="0" cellpadding="1" cellspacing="0" width="100%">
+                <tr>
+                  <td>
+                    <div align="left"></div>
+                  </td>
+                  <td>
+                    <div align="right">
+                      <p>
+<a href="../index.html" title="Home">Home</a>
+&#124;
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+&#124;
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+                    </div>
+                  </td>
+                </tr>
+              </table>
+            </div>
+          </div>
+        </td>
+        <td id="cell-1-3">
+          &nbsp;
+        </td>
+        <td id="cell-1-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-2-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-2-1">
+          <table>
+            <tr height="100%" valign="top">
+              <td height="100%">
+                <div id="wrapper-menu-page-right">
+                  <div id="wrapper-menu-page-top">
+                    <div id="wrapper-menu-page-bottom">
+                      <div id="menu-page">
+                        <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li><a href
 ="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a></li><li><a hre
 f="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </td>
+              <td height="100%" width="100%">
+                <div class="wiki-content">
+<h1 id="Customdistributions">Custom distributions</h1><p>As Karaf is an OSGi container, it's heavily used as an application and middleware kernel.</p><p>You may wish to construct your own Karaf distribution preconfigured to your requirements.<br/>This custom distribution could contain:</p><ul style="list-style: square"><li>branding to change the Karaf console look-and-feel</li><li>configuration files (in the etc folder) altered to your requirements</li><li>pre-packaged artifacts in the deploy folder</li><li>a pre-populated system repository (containing your own bundle and features descriptor)</li><li>renamed or specific scripts in the bin folder</li><li>system documentation files</li></ul><h2 id="Mavenassembly">Maven assembly</h2><p>Basically a Karaf custom distribution involves:<br/>1. Uncompressing a standard Karaf distribution in a given directory.<br/>2. Populating the system repo with your features.<br/>3. Populating the lib directory with your branding or other system bundle j
 ar files.<br/>4. Overriding the configuration files in the etc folder.</p><p>These tasks could be performed using scripting, or more easily and portable, using Apache Maven and a set of Maven plugins.</p><p>For instance, the Maven POM could look like:</p><pre>
+&lt;?xml version="1.0" encoding="UTF-8"?>
+&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  &lt;groupId>my.company&lt;/groupId>
+  &lt;artifactId>mycustom-karaf&lt;/artifactId>
+  &lt;version>1.0&lt;/version>
+  &lt;packaging>pom&lt;/packaging>
+  &lt;name>My Unix Custom Karaf Distribution&lt;/name>
+
+  &lt;properties>
+    &lt;karaf.version>2.2.2&lt;/karaf.version>
+  &lt;/properties>
+
+  &lt;dependencies>
+    &lt;dependency>
+      &lt;groupId>org.apache.karaf&lt;/groupId>
+      &lt;artifactId>apache-karaf&lt;/artifactId>
+      &lt;version>2.4.5-SNAPSHOT&lt;/version>
+      &lt;type>tar.gz&lt;/type>
+    &lt;/dependency>
+    &lt;dependency>
+      &lt;groupId>org.apache.karaf.assemblies.features&lt;/groupId>
+      &lt;artifactId>standard&lt;/artifactId>
+      &lt;version>2.4.5-SNAPSHOT&lt;/version>
+      &lt;type>xml&lt;/type>
+      &lt;classifier>features&lt;/classifier>
+    &lt;/dependency>
+  &lt;/dependencies>
+
+  &lt;build>
+    &lt;resources>
+      &lt;resource>
+        &lt;directory>/home/jbonofre/Workspace/karaf/manual/src/main/filtered-resources&lt;/directory>
+        &lt;filtering>true&lt;/filtering>
+        &lt;includes>
+          &lt;include>**/*&lt;/include>
+        &lt;/includes>
+      &lt;/resource>
+    &lt;/resources>
+    &lt;plugins>
+      &lt;plugin>
+        &lt;groupId>org.apache.maven.plugins&lt;/groupId>
+        &lt;artifactId>maven-resources-plugin&lt;/artifactId>
+        &lt;executions>
+          &lt;execution>
+            &lt;id>filter&lt;/id>
+            &lt;phase>generate-resources&lt;/phase>
+            &lt;goals>
+              &lt;goal>resources&lt;/goal>
+            &lt;/goals>
+          &lt;/execution>
+        &lt;/executions>
+      &lt;/plugin>
+      &lt;plugin>
+        &lt;groupId>org.apache.karaf.tooling&lt;/groupId>
+        &lt;artifactId>features-maven-plugin&lt;/artifactId>
+        &lt;version>2.4.5-SNAPSHOT&lt;/version>
+        &lt;executions>
+          &lt;execution>
+           &lt;id>add-features-to-repo&lt;/id>
+           &lt;phase>generate-resources&lt;/phase>
+           &lt;goals>
+             &lt;goal>add-features-to-repo&lt;/goal>
+           &lt;/goals>
+           &lt;configuration>
+              &lt;descriptors>
+                &lt;descriptor>mvn:org.apache.karaf.assemblies.features/standard/2.4.5-SNAPSHOT/xml/features&lt;/descriptor>
+                &lt;descriptor>file:/home/jbonofre/Workspace/karaf/manual/target/classes/my-features.xml&lt;/descriptor>
+              &lt;/descriptors>
+              &lt;features>
+                &lt;feature>my-feature&lt;/feature>
+              &lt;/features>
+           &lt;/configuration>
+          &lt;/execution>
+        &lt;/executions>
+      &lt;/plugin>
+      &lt;plugin>
+        &lt;groupId>org.apache.maven.plugins&lt;/groupId>
+        &lt;artifactId>maven-dependency-plugin&lt;/artifactId>
+        &lt;executions>
+          &lt;execution>
+            &lt;id>copy&lt;/id>
+            &lt;phase>generate-resources&lt;/phase>
+            &lt;goals>
+              &lt;goal>copy&lt;/goal>
+            &lt;/goals>
+            &lt;configuration>
+               &lt;!-- Define here the artifacts which should be considered in the assembly -->
+               &lt;!-- For instance, the branding jar -->
+               &lt;artifactItems>
+                 &lt;artifactItem>
+                    &lt;groupId>my.groupId&lt;/groupId>
+                    &lt;artifactId>my.branding.id&lt;/artifactId>
+                    &lt;version>1.0&lt;/version>
+                    &lt;outputDirectory>target/dependencies&lt;/outputDirectory>
+                    &lt;destFileName>mybranding.jar&lt;/destFileName>
+                 &lt;/artifactItem>
+               &lt;/artifactItems>
+            &lt;/configuration>
+          &lt;/execution>
+          &lt;execution>
+            &lt;!-- Uncompress the standard Karaf distribution -->
+            &lt;id>unpack&lt;/id>
+            &lt;phase>generate-resources&lt;/phase>
+            &lt;goals>
+              &lt;goal>unpack&lt;/goal>
+            &lt;/goals>
+            &lt;configuration>
+              &lt;artifactItems>
+                &lt;artifactItem>
+                  &lt;groupId>org.apache.karaf&lt;/groupId>
+                  &lt;artifactId>apache-karaf&lt;/artifactId>
+                  &lt;type>tar.gz&lt;/type>
+                  &lt;outputDirectory>target/dependencies&lt;/outputDirectory>
+                &lt;/artifactItem>
+              &lt;/artifactItems>
+            &lt;/configuration>
+          &lt;/execution>
+        &lt;/executions>
+      &lt;/plugin>
+      &lt;plugin>
+        &lt;groupId>org.apache.maven.plugins&lt;/groupId>
+        &lt;artifactId>maven-assembly-plugin&lt;/artifactId>
+        &lt;executions>
+          &lt;execution>
+            &lt;id>bin&lt;/id>
+            &lt;phase>package&lt;/phase>
+            &lt;goals>
+              &lt;goal>single&lt;/goal>
+            &lt;/goals>
+            &lt;configuration>
+              &lt;descriptors>
+                &lt;descriptor>src/main/descriptors/bin.xml&lt;/descriptor>
+              &lt;/descriptors>
+              &lt;appendAssemblyId>false&lt;/appendAssemblyId>
+              &lt;tarLongFileMode>gnu&lt;/tarLongFileMode>
+            &lt;/configuration>
+          &lt;/execution>
+        &lt;/executions>
+      &lt;/plugin>
+    &lt;/plugins>
+  &lt;/build>
+
+&lt;/project>
+</pre><p>The Maven POM will download the Karaf standard distribution and prepare resources to be processed by the Maven assembly plugin.</p><p>Your Maven project structure should look like:</p><ul><li>pom.xml: the previous POM file</li><li>src/main/descriptors/bin.xml: the assembly maven plugin descriptor (see below)</li><li>src/main/filtered-resources: contains all resource files that have Maven property values to be filtered/replaced. Typically, this will include features descriptor and configuration files.</li><li>src/main/distribution: contains all raw files which will be copied as-is into your custom distribution.</li></ul><p>For instance, <tt>src/main/filtered-resources</tt> could contain:</p><ul><li><tt>my-features.xml</tt> where maven properties will be replaced</li><li><tt>etc/org.apache.karaf.features.cfg</tt> file containing your my-features descriptor:<pre>
+#
+# Comma separated list of features repositories to register by default
+#
+featuresRepositories=mvn:org.apache.karaf/apache-karaf/2.4.5-SNAPSHOT/xml/features,mvn:my.groupId/my-features/2.4.5-SNAPSHOT/xml/features
+
+#
+# Comma separated list of features to install at startup
+#
+featuresBoot=config,ssh,management,my-feature
+</pre></li></ul><p>The <tt>src/main/distribution</tt> contains all your custom Karaf configuration files and scripts, as, for examples:</p><ul><li>etc/org.ops4j.pax.logging.cfg<pre>
+# Root logger
+log4j.rootLogger=INFO, out, osgi:VmLogAppender
+log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer
+
+# CONSOLE appender not used by default
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32C %4L | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+
+# File appender
+log4j.appender.out=org.apache.log4j.RollingFileAppender
+log4j.appender.out.layout=org.apache.log4j.PatternLayout
+log4j.appender.out.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32C %4L | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
+log4j.appender.out.file=${karaf.home}/log/my-customer-distribution.log
+log4j.appender.out.append=true
+log4j.appender.out.maxFileSize=1MB
+log4j.appender.out.maxBackupIndex=10
+
+# Sift appender
+log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender
+log4j.appender.sift.key=bundle.name
+log4j.appender.sift.default=my-custom
+log4j.appender.sift.appender=org.apache.log4j.FileAppender
+log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout
+log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n
+log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log
+log4j.appender.sift.appender.append=true
+</pre></li><li>etc/system.properties<pre>
+#
+# The properties defined in this file will be made available through system
+# properties at the very beginning of the FAS boot process.
+#
+
+# Log level when the pax-logging service is not available
+# This level will only be used while the pax-logging service bundle
+# is not fully available.
+# To change log levels, please refer to the org.ops4j.pax.logging.cfg file
+# instead.
+org.ops4j.pax.logging.DefaultServiceLog.level=ERROR
+
+#
+# Name of this custom instance.
+#
+karaf.name=my-custom
+
+#
+# Default repository where bundles will be loaded from before using
+# other maven repositories. For the full Maven configuration, see the
+# org.ops4j.pax.url.mvn.cfg file.
+#
+karaf.default.repository=system
+
+#
+# Location of a shell script that will be run when starting a shell
+# session. This script can be used to create aliases and define
+# additional commands.
+#
+karaf.shell.init.script=${karaf.home}/etc/shell.init.script
+
+#
+# Set this empty property to avoid errors when validating xml documents.
+#
+xml.catalog.files=
+
+#
+# Suppress the bell in the console when hitting backspace to many times
+# for example
+#
+jline.nobell=true
+
+#
+# Default port for the OSGi HTTP Service
+#
+org.osgi.service.http.port=8181
+
+#
+# Allow usage of ${custom.home} as an alias for ${karaf.home}
+#
+custom.home=${karaf.home}
+</pre></li><li>etc/users.properties<pre>
+admin=admin,admin
+</pre></li><li>You can add a <tt>etc/custom.properties</tt>, it's a placeholder for any override you may need. For instance:<pre>
+karaf.systemBundlesStartLevel=50
+obr.repository.url=http://svn.apache.org/repos/asf/servicemix/smx4/obr-repo/repository.xml
+org.osgi.framework.system.packages.extra = \
+  org.apache.karaf.branding; \
+  com.sun.org.apache.xalan.internal.xsltc.trax; \
+  com.sun.org.apache.xerces.internal.dom; \
+  com.sun.org.apache.xerces.internal.jaxp; \
+  com.sun.org.apache.xerces.internal.xni; \
+  com.sun.jndi.ldap
+</pre></li></ul><p>Now, we can "assemble" our custom distribution using the Maven assembly plugin. The Maven assembly plugin uses an assembly descriptor, configured in POM above to be <tt>src/main/descriptors/bin.xml</tt>:</p><pre>
+&lt;assembly>
+
+    &lt;id>bin&lt;/id>
+
+    &lt;formats>
+        &lt;format>tar.gz&lt;/format>
+    &lt;/formats>
+
+    &lt;fileSets>
+
+        &lt;!-- Expanded Karaf Standard Distribution -->
+        &lt;fileSet>
+            &lt;directory>target/dependencies/apache-karaf-2.4.5-SNAPSHOT&lt;/directory>
+            &lt;outputDirectory>/&lt;/outputDirectory>
+            &lt;excludes>
+                &lt;exclude>**/demos/**&lt;/exclude>
+                &lt;exclude>bin/**&lt;/exclude>
+                &lt;exclude>etc/system.properties&lt;/exclude>
+                &lt;exclude>etc/users.properties&lt;/exclude>
+                &lt;exclude>etc/org.apache.karaf.features.cfg&lt;/exclude>
+                &lt;exclude>etc/org.ops4j.pax.logging.cfg&lt;/exclude>
+                &lt;exclude>LICENSE&lt;/exclude>
+                &lt;exclude>NOTICE&lt;/exclude>
+                &lt;exclude>README&lt;/exclude>
+                &lt;exclude>RELEASE-NOTES&lt;/exclude>
+                &lt;exclude>karaf-manual*.html&lt;/exclude>
+                &lt;exclude>karaf-manual*.pdf&lt;/exclude>
+            &lt;/excludes>
+        &lt;/fileSet>
+
+        &lt;!-- Copy over bin/* separately to get the correct file mode -->
+        &lt;fileSet>
+            &lt;directory>target/dependencies/apache-karaf-2.4.5-SNAPSHOT&lt;/directory>
+            &lt;outputDirectory>/&lt;/outputDirectory>
+            &lt;includes>
+                &lt;include>bin/admin&lt;/include>
+                &lt;include>bin/karaf&lt;/include>
+                &lt;include>bin/start&lt;/include>
+                &lt;include>bin/stop&lt;/include>
+            &lt;/includes>
+            &lt;fileMode>0755&lt;/fileMode>
+        &lt;/fileSet>
+
+        &lt;!-- Copy over jar files -->
+        &lt;fileSet>
+            &lt;directory>target/dependencies&lt;/directory>
+            &lt;includes>
+                &lt;include>my-custom.jar&lt;/include>
+            &lt;/includes>
+            &lt;outputDirectory>/lib/&lt;/outputDirectory>
+        &lt;/fileSet>
+
+        &lt;fileSet>
+            &lt;directory>src/main/distribution&lt;/directory>
+            &lt;outputDirectory>/&lt;/outputDirectory>
+            &lt;fileMode>0644&lt;/fileMode>
+        &lt;/fileSet>
+        &lt;fileSet>
+            &lt;directory>target/classes/etc&lt;/directory>
+            &lt;outputDirectory>/etc/&lt;/outputDirectory>
+            &lt;lineEnding>unix&lt;/lineEnding>
+            &lt;fileMode>0644&lt;/fileMode>
+        &lt;/fileSet>
+
+        &lt;fileSet>
+            &lt;directory>target/features-repo&lt;/directory>
+            &lt;outputDirectory>/system&lt;/outputDirectory>
+        &lt;/fileSet>
+
+    &lt;/fileSets>
+
+    &lt;files>
+        &lt;file>
+            &lt;source>/home/jbonofre/Workspace/karaf/manual/target/dependencies/apache-karaf-2.4.5-SNAPSHOT/bin/karaf&lt;/source>
+            &lt;outputDirectory>/bin/&lt;/outputDirectory>
+            &lt;destName>my-custom&lt;/destName>
+            &lt;fileMode>0755&lt;/fileMode>
+            &lt;lineEnding>unix&lt;/lineEnding>
+        &lt;/file>
+        &lt;file>
+            &lt;source>/home/jbonofre/Workspace/karaf/manual/target/classes/features.xml&lt;/source>
+            &lt;outputDirectory>/system/my.groupid/my-features/2.4.5-SNAPSHOT&lt;/outputDirectory>
+            &lt;destName>my-features-2.4.5-SNAPSHOT-features.xml&lt;/destName>
+            &lt;fileMode>0644&lt;/fileMode>
+            &lt;lineEnding>unix&lt;/lineEnding>
+        &lt;/file>
+    &lt;/files>
+
+&lt;/assembly>
+</pre><p>To build your custom Karaf distribution, just run:</p><pre>
+mvn install
+</pre><p>You will find your Karaf custom distribution tar.gz in the target directory.</p><h2 id="Roadmap">Roadmap</h2><p>A distribution goal is in preparation in the next Karaf</p><h2 id="Customdistributionexamples">Custom distribution examples</h2><ul><li><a href="http://svn.apache.org/repos/asf/servicemix/smx4/features/trunk/assemblies/">Apache ServiceMix 4</a></li><li><a href="http://svn.apache.org/repos/asf/servicemix/smx4/nmr/trunk/bundle/">Apache ServiceMix NMR</a></li><li><a href="http://buildprocess.svn.sourceforge.net/viewvc/buildprocess/builderaser/trunk/assembly/">BuildProcess BuildEraser</a></li></ul>
+                </div>
+              </td>
+            </tr>
+          </table>
+        </td>
+        <td id="cell-2-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-3-0">
+          &nbsp;
+        </td>
+        <td id="cell-3-1">
+          &nbsp;
+        </td>
+        <td id="cell-3-2">
+          <div id="footer">
+            <div id="site-footer">
+              &copy; 2008-2011 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>
+          </div>
+        </td>
+        <td id="cell-3-3">
+          &nbsp;
+        </td>
+        <td id="cell-3-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-4-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-4-1">
+          &nbsp;
+        </td>
+        <td id="cell-4-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
\ No newline at end of file

Added: karaf/site/production/manual/latest-2.x/developers-guide/debugging.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.x/developers-guide/debugging.html?rev=1742536&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.x/developers-guide/debugging.html (added)
+++ karaf/site/production/manual/latest-2.x/developers-guide/debugging.html Fri May  6 12:23:15 2016
@@ -0,0 +1,174 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> 
+<html lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <meta name="description" content="description goes here"/>
+    <meta name="keywords" content="keywords,goes,here"/>
+    <meta name="author" content="The Apache Karaf Team"/>
+    <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+    <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+    <title>
+      Apache Karaf 2.4.5-SNAPSHOT Guides
+    </title>
+  </head>
+  <body>
+    <table width="100%" cellpadding="0" cellspacing="0">
+      <tr width="100%">
+        <td id="cell-0-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-0-1">
+          &nbsp;
+        </td>
+        <td id="cell-0-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-1-0">
+          &nbsp;
+        </td>
+        <td id="cell-1-1">
+          &nbsp;
+        </td>
+        <td id="cell-1-2">
+          <div style="padding: 5px;">
+            <div id="banner">
+                    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+        <tr>
+          <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+            <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+          </td>
+          <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+            <img border="0" src="../images/asf-logo.png">
+</a>
+          </td>
+        </tr>
+      </table>
+
+            </div>
+            <div id="top-menu">
+              <table border="0" cellpadding="1" cellspacing="0" width="100%">
+                <tr>
+                  <td>
+                    <div align="left"></div>
+                  </td>
+                  <td>
+                    <div align="right">
+                      <p>
+<a href="../index.html" title="Home">Home</a>
+&#124;
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+&#124;
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+                    </div>
+                  </td>
+                </tr>
+              </table>
+            </div>
+          </div>
+        </td>
+        <td id="cell-1-3">
+          &nbsp;
+        </td>
+        <td id="cell-1-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-2-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-2-1">
+          <table>
+            <tr height="100%" valign="top">
+              <td height="100%">
+                <div id="wrapper-menu-page-right">
+                  <div id="wrapper-menu-page-top">
+                    <div id="wrapper-menu-page-bottom">
+                      <div id="menu-page">
+                        <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li><a href
 ="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a></li><li><a hre
 f="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </td>
+              <td height="100%" width="100%">
+                <div class="wiki-content">
+<h1 id="TroubleshootingDebuggingProfilingandMonitoring">Troubleshooting, Debugging, Profiling, and Monitoring</h1><h2 id="Troubleshooting">Troubleshooting</h2><h3 id="Logging">Logging</h3><p>Logging is easy to control through the console, with commands grouped under <em>log</em> shell. To learn about the available logging commands type:</p><pre>
+karaf@root> log&lt;tab>
+
+log:display              log:display-exception    log:get                  log:set
+karaf@root>
+</pre><p>Typical usage is:</p> <p> # Use <tt>log:set</tt> to dynamically change the global log level<br/> # Execute the problematic operation<br/> # Use <tt>log:display</tt> (or <tt>log:display-exception</tt> to display the log </p> <h3 id="WorstCaseScenario">Worst Case Scenario</h3><p>If you end up with a Karaf in a really bad state (i.e. you can not boot it anymore) or you just want to revert to a clean state quickly, you can safely remove the <tt>data</tt> directory in the installation directory.  This folder contains transient data and will be recreated if removed when you relaunch Karaf.<br/>You may also want to remove the files in the <tt>deploy</tt> folder to avoid them being automatically installed when Karaf is started the first time.</p><h2 id="Debugging">Debugging</h2><p>Usually, the easiest way to debug Karaf or any application deployed onto it is to use remote debugging.<br/>Remote debugging can be easily activated by using the <tt>debug</tt> parameter on the command li
 ne.</p><pre>> bin/karaf debug
+{noformat
+or on Windows
+</pre><p>> bin\karaf.bat debug<br/>{noformat</p><p>Another option is to set the <tt>KARAF_DEBUG</tt> environment variable to <tt>TRUE</tt>.</p><p>This can be done using the following command on Unix systems:</p><pre>export KARAF_DEBUG=true
+</pre><p>On Windows, use the following command</p><pre>set KARAF_DEBUG=true
+</pre><p>Then, you can launch Karaf using the usual way:</p><pre>bin/karaf
+</pre><p>or</p><pre>bin\karaf.bat
+</pre><p>Last, inside your IDE, connect to the remote application (the default port to connect to is 5005).</p><p>This option works fine when it is needed to debug a project deployed top of Apache Karaf. Nevertheless, you will be blocked <br/>if you would like to debug the server Karaf. In this case, you can change the following parameter suspend=y in the <br/>karaf.bat script file. That will cause the JVM to pause just before running main() until you attach a debugger then it <br/>will resume the execution.  This way you can set your breakpoints anywhere in the code and you should be able to hit them<br/>no matter how early in the startup they are.  </p><pre>
+export DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
+</pre><p>and on Windows,</p><pre>
+set DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
+</pre><h2 id="Profiling">Profiling</h2><h3 id="jVisualVM">jVisualVM</h3><p>You have to edit the <tt>etc/config.properties</tt> configuration file to add the jVisualVM package:</p><pre>
+org.osgi.framework.bootdelegation=...,org.netbeans.lib.profiler.server
+</pre><p>Run Karaf from the console, and you should now be able to connect using jVisualVM.</p><h3 id="YourKit">YourKit</h3><p>You need a few steps to be able to profile Karaf using YourKit.<br/>The first one is to edit the <tt>etc/config.properties</tt> configuration file and add the following property:</p><pre>
+org.osgi.framework.bootdelegation=com.yourkit.*
+</pre><p>Then, set the <tt>JAVA_OPTS</tt> environment variable:</p><pre>
+export JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
+</pre><p>or, on Windows</p><pre>
+set JAVA_OPTS='-Xmx512M -agentlib:yjpagent'
+</pre><p>Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE.</p><h2 id="Monitoring">Monitoring</h2><p>Karaf uses JMX for monitoring and management of all Karaf components.</p><p>The JMX connection could be:</p><ul><li>local using the process id</li></ul><p><img border="1" src="../images/jconsole_connect.jpg"/></p><ul><li>remote using the <tt>rmiRegistryPort</tt> property defined in <tt>etc/org.apache.karaf.management.cfg</tt> file.</li></ul><p>Using JMX, you can have a clean overview of the running Karaf instance:</p><ul><li>A overview with graphics displaying the load in terms of thread, heap/GC, etc:</li></ul><p><img border="1" src="../images/jconsole_overview.jpg"/></p><ul><li>A thread overview:</li></ul><p><img border="1" src="../images/jconsole_threads.jpg"/></p><ul><li>A memory heap consumption, including "Perform GC" button:</li></ul><p><img border="1" src="../images/jconsole_memory.jpg"/></p><ul><li>A complete
  JVM summary, with all number of threads, etc:</li></ul><p><img border="1" src="../images/jconsole_summary.jpg"/></p><p>You can manage Karaf features like you are in the shell. For example, you have access to the Admin service MBean, allowing you to create, rename, destroy, change SSH port, etc. Karaf instances:</p><p><img border="1" src="../images/jconsole_admin.jpg"/></p><p>You can also manage Karaf features MBean to list, install, and uninstall Karaf features:</p><p><img border="1" src="../images/jconsole_features.jpg"/></p>
+                </div>
+              </td>
+            </tr>
+          </table>
+        </td>
+        <td id="cell-2-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-3-0">
+          &nbsp;
+        </td>
+        <td id="cell-3-1">
+          &nbsp;
+        </td>
+        <td id="cell-3-2">
+          <div id="footer">
+            <div id="site-footer">
+              &copy; 2008-2011 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>
+          </div>
+        </td>
+        <td id="cell-3-3">
+          &nbsp;
+        </td>
+        <td id="cell-3-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-4-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-4-1">
+          &nbsp;
+        </td>
+        <td id="cell-4-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
\ No newline at end of file

Added: karaf/site/production/manual/latest-2.x/developers-guide/developer-commands.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.x/developers-guide/developer-commands.html?rev=1742536&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.x/developers-guide/developer-commands.html (added)
+++ karaf/site/production/manual/latest-2.x/developers-guide/developer-commands.html Fri May  6 12:23:15 2016
@@ -0,0 +1,230 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> 
+<html lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <meta name="description" content="description goes here"/>
+    <meta name="keywords" content="keywords,goes,here"/>
+    <meta name="author" content="The Apache Karaf Team"/>
+    <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+    <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+    <title>
+      Apache Karaf 2.4.5-SNAPSHOT Guides
+    </title>
+  </head>
+  <body>
+    <table width="100%" cellpadding="0" cellspacing="0">
+      <tr width="100%">
+        <td id="cell-0-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-0-1">
+          &nbsp;
+        </td>
+        <td id="cell-0-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-1-0">
+          &nbsp;
+        </td>
+        <td id="cell-1-1">
+          &nbsp;
+        </td>
+        <td id="cell-1-2">
+          <div style="padding: 5px;">
+            <div id="banner">
+                    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+        <tr>
+          <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+            <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+          </td>
+          <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+            <img border="0" src="../images/asf-logo.png">
+</a>
+          </td>
+        </tr>
+      </table>
+
+            </div>
+            <div id="top-menu">
+              <table border="0" cellpadding="1" cellspacing="0" width="100%">
+                <tr>
+                  <td>
+                    <div align="left"></div>
+                  </td>
+                  <td>
+                    <div align="right">
+                      <p>
+<a href="../index.html" title="Home">Home</a>
+&#124;
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+&#124;
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+                    </div>
+                  </td>
+                </tr>
+              </table>
+            </div>
+          </div>
+        </td>
+        <td id="cell-1-3">
+          &nbsp;
+        </td>
+        <td id="cell-1-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-2-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-2-1">
+          <table>
+            <tr height="100%" valign="top">
+              <td height="100%">
+                <div id="wrapper-menu-page-right">
+                  <div id="wrapper-menu-page-top">
+                    <div id="wrapper-menu-page-bottom">
+                      <div id="menu-page">
+                        <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li><a href
 ="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a></li><li><a hre
 f="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </td>
+              <td height="100%" width="100%">
+                <div class="wiki-content">
+<h1 id="Developercommands">Developer commands</h1><p>Karaf provides a set of commands specific for developer use.</p><p>They allow for getting detailed detailed information about the Karaf instance and the applications running in them.</p><h2 id="Diagnosticdumpcommand">Diagnostic dump command</h2><p>Karaf provides a <tt>dev:create-dump</tt> command which creates a dump files containing diagnostic information. The dumps can be<br/>packaged in a zip archive (default) or directly into a given directory.</p><pre>
+karaf@root> dev:create-dump
+Diagnostic dump created.
+</pre><p>The previous command generates a zip archive in the KARAF_HOME (by default the name is the generation timestamp).</p><p>The following dumps are available in the zip archive:</p><ul><li><tt>features.txt</tt> provides an overview of the features. It means:<ul><li>the repository list</li><li>the feature list including bundles URL</li></ul></li><li><tt>bundles.txt</tt> provides an overview of the installed bundles, with the ID and the state of each bundle.</li><li><tt>threads.txt</tt> provides a complete threads dump. It describe all threads running in Karaf and their current state (blocked,<p>waiting, etc) with the associated class hierarchy.</p><p>These dumps are very helpful when you would like to take a snapshot of a current Karaf running instance.</p><h2 id="Dynamicimport">Dynamic import</h2><p>The <tt>dev:dynamic-import</tt> command allows you to enable or disable the dynamic import of a given bundle:</p><pre>
+karaf@root> dev:dynamic-import 41
+Enabling dynamic imports on bundle org.apache.karaf.shell.config [41]
+</pre></li></ul><h2 id="OSGiframework">OSGi framework</h2><p>The <tt>dev:framework</tt> command shows you the current OSGi framework in use, and enables debugging of the underlying OSGi framework.</p><pre>
+karaf@root> dev:framework
+Current OSGi framework is Felix
+karaf@root> dev:framework -debug
+Enabling debug for OSGi framework (Felix)
+- set felix.log.level=4 in etc/config.properties
+
+Restart Karaf now to enable Felix debug logging
+karaf@root> dev:framework -nodebug
+Disabling debug for OSGi framework (Felix)
+- removed felix.log.level from etc/config.properties
+
+Restart Karaf now to disable Felix debug logging
+</pre><h2 id="Printstacktrace">Print stack trace</h2><p>The <tt>dev:print-stack-traces</tt> command prints the full stack trace in the console when the execution of a command<br/>throws an exception.</p><p>You can enable or disable this behavior by passing true (to enable) or false (to disable) on the command on the fly:</p><pre>
+karaf@root> dev:print-stack-traces
+karaf@root> osgi:start
+Error executing command osgi:start: argument ids is required
+org.apache.felix.gogo.commands.CommandException: Argument ids is required
+        at org.apache.felix.gogo.commands.basic.DefaultActionPreparator.prepare(DefaultActionPreparator.java:284)
+        at org.apache.felix.gogo.commands.basic.AbstractCommand.execute(AbstractCommand.java:34)
+        at org.apache.felix.gogo.runtime.CommandProxy.execute(CommandProxy.java:78)
+        at org.apache.felix.gogo.runtime.Closure.executeCmd(Closure.java:474)
+        at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:400)
+        at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108)
+        at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183)
+        at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120)
+        at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:79)
+        at org.apache.karaf.shell.console.jline.Console.run(Console.java:180)
+        at java.lang.Thread.run(Thread.java:619)
+karaf@root> dev:print-stack-traces false
+karaf@root> osgi:start
+Error executing command osgi:start: argument ids is required
+</pre><h2 id="Karafrestart">Karaf restart</h2><p>The <tt>dev:restart</tt> command allows you to restart the running Karaf instance:</p><pre>
+karaf@root> dev:restart
+karaf@root>
+        __ __                  ____
+       / //_/____ __________ _/ __/
+      / ,&lt;  / __ `/ ___/ __ `/ /_
+     / /| |/ /_/ / /  / /_/ / __/
+    /_/ |_|\__,_/_/   \__,_/_/
+
+  Apache Karaf (2.1.99-SNAPSHOT)
+
+Hit '&lt;tab>' for a list of available commands
+and '[cmd] --help' for help on a specific command.
+Hit '&lt;ctrl-d>' or 'osgi:shutdown' to shutdown Karaf.
+
+karaf@root>
+</pre><h2 id="Bundletree">Bundle tree</h2><p>The <tt>dev:show-tree</tt> command shows the bundle dependency tree based on the wiring information of a given single bundle ID.</p><pre>
+karaf@root> dev:show-tree 40
+Bundle org.apache.karaf.diagnostic.command [40] is currently ACTIVE
+
+org.apache.karaf.diagnostic.command [40]
++- org.apache.aries.blueprint [10]
+|  +- org.apache.aries.util [8]
+|  +- org.apache.felix.configadmin [5]
+|  +- org.apache.aries.proxy [7]
+|  |  +- org.apache.aries.util [8]
+|  |  +- org.apache.servicemix.bundles.asm [9]
+|  |  +- org.ops4j.pax.logging.pax-logging-api [3]
+|  +- org.ops4j.pax.logging.pax-logging-api [3]
++- org.apache.karaf.shell.console [22]
+|  +- org.apache.aries.blueprint [10]
+|  +- org.ops4j.pax.logging.pax-logging-api [3]
+|  +- org.apache.karaf.jaas.modules [13]
+|     +- org.apache.aries.blueprint [10]
+|     +- org.apache.felix.configadmin [5]
+|     +- org.apache.karaf.jaas.config [29]
+|     |  +- org.apache.aries.blueprint [10]
+|     |  +- org.ops4j.pax.logging.pax-logging-api [3]
+|     +- org.ops4j.pax.logging.pax-logging-api [3]
++- org.apache.karaf.diagnostic.core [23]
+</pre><h2 id="Watchingandupdatingbundle">Watching and updating bundle</h2><p>The <tt>dev:watch</tt> watches and updates bundles. It's especially helpful in development mode.</p><p>It allows you to configure a set of URLs that will be monitored. All bundles whose location matches the given URL will be<br/>automatically updated. This avoids needing to manually update the bundles or even copy the bundles to the system folder.</p><p>Note that only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically, so if you do:</p><pre>
+karaf@root> dev:watch *
+</pre><p>it will actually monitor all bundles that have a location matching mvn:* that have '-SNAPSHOT' in their URL.</p>
+                </div>
+              </td>
+            </tr>
+          </table>
+        </td>
+        <td id="cell-2-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-3-0">
+          &nbsp;
+        </td>
+        <td id="cell-3-1">
+          &nbsp;
+        </td>
+        <td id="cell-3-2">
+          <div id="footer">
+            <div id="site-footer">
+              &copy; 2008-2011 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>
+          </div>
+        </td>
+        <td id="cell-3-3">
+          &nbsp;
+        </td>
+        <td id="cell-3-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-4-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-4-1">
+          &nbsp;
+        </td>
+        <td id="cell-4-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
\ No newline at end of file

Added: karaf/site/production/manual/latest-2.x/developers-guide/extending-console.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-2.x/developers-guide/extending-console.html?rev=1742536&view=auto
==============================================================================
--- karaf/site/production/manual/latest-2.x/developers-guide/extending-console.html (added)
+++ karaf/site/production/manual/latest-2.x/developers-guide/extending-console.html Fri May  6 12:23:15 2016
@@ -0,0 +1,248 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> 
+<html lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+    <meta name="description" content="description goes here"/>
+    <meta name="keywords" content="keywords,goes,here"/>
+    <meta name="author" content="The Apache Karaf Team"/>
+    <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+    <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+    <title>
+      Apache Karaf 2.4.5-SNAPSHOT Guides
+    </title>
+  </head>
+  <body>
+    <table width="100%" cellpadding="0" cellspacing="0">
+      <tr width="100%">
+        <td id="cell-0-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-0-1">
+          &nbsp;
+        </td>
+        <td id="cell-0-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-1-0">
+          &nbsp;
+        </td>
+        <td id="cell-1-1">
+          &nbsp;
+        </td>
+        <td id="cell-1-2">
+          <div style="padding: 5px;">
+            <div id="banner">
+                    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+        <tr>
+          <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+            <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+          </td>
+          <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+            <img border="0" src="../images/asf-logo.png">
+</a>
+          </td>
+        </tr>
+      </table>
+
+            </div>
+            <div id="top-menu">
+              <table border="0" cellpadding="1" cellspacing="0" width="100%">
+                <tr>
+                  <td>
+                    <div align="left"></div>
+                  </td>
+                  <td>
+                    <div align="right">
+                      <p>
+<a href="../index.html" title="Home">Home</a>
+&#124;
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+&#124;
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+                    </div>
+                  </td>
+                </tr>
+              </table>
+            </div>
+          </div>
+        </td>
+        <td id="cell-1-3">
+          &nbsp;
+        </td>
+        <td id="cell-1-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-2-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-2-1">
+          <table>
+            <tr height="100%" valign="top">
+              <td height="100%">
+                <div id="wrapper-menu-page-right">
+                  <div id="wrapper-menu-page-top">
+                    <div id="wrapper-menu-page-bottom">
+                      <div id="menu-page">
+                        <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installing Karaf</a></li><li><a href="../users-guide/directory-structure.html">Directory Structure</a></li><li><a href="../users-guide/start-stop.html">Starting and stopping Karaf</a></li><li><a href="../users-guide/wrapper.html">OS integration</a></li><li><a href="../users-guide/using-console.html">Using the console</a></li><li><a href="../users-guide/remote-console.html">Remote console</a></li><li><a href="../users-guide/web-console.html">Web console</a></li><li><a href="../users-guide/child-instances.html">Child instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li><a href
 ="../users-guide/failover.html">Failover Deployments</a></li><li><a href="../users-guide/logging-system.html">Logging system</a></li><li><a href="../users-guide/deployer.html">Deployer</a></li><li><a href="../users-guide/provisioning.html">Provisioning</a></li><li><a href="../users-guide/kar.html">KAR archive</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/http.html">HTTP service</a></li><li><a href="../users-guide/web-applications.html">Web applications</a></li><li><a href="../users-guide/jre-tuning.html">JRE tuning</a></li><li><a href="../users-guide/jmx.html">JMX for administration and monitoring</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href="branding-console.html">Branding the Console</a></li><li><a href="extending-console.html">Extending the Console</a></li><li><a hre
 f="custom-distribution.html">Custom Distribution</a></li><li><a href="security-framework.html">Security Framework</a></li><li><a href="features-maven-plugin.html">Using the features-maven-plugin</a></li><li><a href="debugging.html">Troubleshooting, Debugging and Profiling</a></li><li><a href="connect-console.html">Programmatically connect to the console</a></li><li><a href="writing-tests.html">Writing integration tests</a></li><li><a href="creating-bundles.html">Creating bundles</a></li><li><a href="shell-syntax.html">Shell syntax</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </td>
+              <td height="100%" width="100%">
+                <div class="wiki-content">
+<h1 id="Extendingtheconsole">Extending the console</h1><p>This chapter will guide you through the steps needed to extend the console and create a new shell.  <br/>We will leverage Maven, Blueprint and OSGi, so you will need some knowledge of those products.</p><p>You may also find some information about the console at <a href="http://felix.apache.org/site/rfc-147-overview.html">http://felix.apache.org/site/rfc-147-overview.html</a>.</p><h2 id="Createtheprojectusingmaven">Create the project using maven</h2><p>We first need to create a project using Maven.  Let's leverage Maven archetypes for that.</p><h3 id="Commandline">Command line</h3><p>Using the command line, we can create our project:</p><pre>
+mvn archetype:create \
+  -DarchetypeArtifactId=maven-archetype-quickstart \
+  -DgroupId=org.apache.karaf.shell.samples \
+  -DartifactId=shell-sample-commands \
+  -Dversion=1.0-SNAPSHOT
+</pre><p>This generate the main <tt>pom.xml</tt> and some additional packages.</p><h3 id="Interactiveshell">Interactive shell</h3><p>You can also use the interactive mode for creating the skeleton project:</p><pre>
+mvn archetype:generate
+</pre><p>Use the following values when prompted:</p><pre>
+Choose a number:  (1/2/3/4/5/6/7/.../32/33/34/35/36) 15: : 15
+Define value for groupId: : org.apache.karaf.shell.samples
+Define value for artifactId: : shell-sample-commands
+Define value for version:  1.0-SNAPSHOT: : 
+Define value for package: : org.apache.karaf.shell.samples
+</pre><h3 id="Manualcreation">Manual creation</h3><p>Alternatively, you can simply create the directory <tt>shell-sample-commands</tt> and create the <tt>pom.xml</tt> file inside it:</p><div class="syntax"><div class="highlight"><pre><span class="nt">&lt;project</span> <span class="na">xmlns=</span><span class="s">&quot;http://maven.apache.org/POM/4.0.0&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;</span><span class="nt">&gt;</span>&#x000A;&#x000A;  <span class="nt">&lt;modelVersion&gt;</span>4.0.0<span class="nt">&lt;/modelVersion&gt;</span>&#x000A;&#x000A;  <span class="nt">&lt;groupId&gt;</span>org.apache.karaf.shell.samples<span class="nt">&lt;/groupId&gt;</span>&#x000A;  <span class="nt">&lt;artifactId&gt;</span>shell-sample-commands<span class="nt">&lt;a
 rtifactId&gt;</span>&#x000A;  <span class="nt">&lt;packaging&gt;</span>bundle<span class="nt">&lt;/packaging&gt;</span>&#x000A;  <span class="nt">&lt;version&gt;</span>1.0-SNAPSHOT<span class="nt">&lt;/version&gt;</span>&#x000A;  <span class="nt">&lt;name&gt;</span>shell-sample-commmands<span class="nt">&lt;/name&gt;</span>&#x000A;&#x000A;&#x000A;  <span class="nt">&lt;dependencies&gt;</span>&#x000A;    <span class="nt">&lt;dependency&gt;</span>&#x000A;      <span class="nt">&lt;groupId&gt;</span>org.apache.karaf.shell<span class="nt">&lt;/groupId&gt;</span>&#x000A;      <span class="nt">&lt;artifactId&gt;</span>org.apache.karaf.shell.console<span class="nt">&lt;/artifactId&gt;</span>&#x000A;      <span class="nt">&lt;version&gt;</span>2.4.5-SNAPSHOT<span class="nt">&lt;/version&gt;</span>&#x000A;    <span class="nt">&lt;/dependency&gt;</span>&#x000A;    <span class="nt">&lt;dependency&gt;</span>&#x000A;      <span class="nt">&lt;groupId&gt;</span>junit<span class="nt">&lt;/groupId&
 gt;</span>&#x000A;      <span class="nt">&lt;artifactId&gt;</span>junit<span class="nt">&lt;/artifactId&gt;</span>&#x000A;      <span class="nt">&lt;version&gt;</span>3.8.1<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="nt">&lt;/dependencies&gt;</span>&#x000A;&#x000A;  <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.felix<span class="nt">&lt;/groupId&gt;</span>&#x000A;        <span class="nt">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="nt">&lt;/artifactId&gt;</span>&#x000A;        <span class="nt">&lt;version&gt;</span>2.5.3<span class="nt">&lt;/version&gt;</span>&#x000A;        <span class="nt">&lt;configuration&gt;</span>&#x000A;          <span class="n
 t">&lt;instructions&gt;</span>&#x000A;            <span class="nt">&lt;Import-Package&gt;</span>&#x000A;              org.apache.felix.service.command,&#x000A;              org.apache.felix.gogo.commands,&#x000A;              org.apache.karaf.shell.console,&#x000A;              *&#x000A;            <span class="nt">&lt;/Import-Package&gt;</span>&#x000A;          <span class="nt">&lt;/instructions&gt;</span>&#x000A;        <span class="nt">&lt;/configuration&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;&#x000A;<span class="nt">&lt;/project&gt;</span>&#x000A;</pre></div>&#x000A;</div><h2 id="ConfiguringforJava5">Configuring for Java 5</h2><p>We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.5 to compile the jar.<br/>Just add the following snippet after the <tt>dependencies</tt> section.</p><div class="syntax"><div c
 lass="highlight"><pre><span class="nt">&lt;build&gt;</span>&#x000A;  <span class="nt">&lt;plugins&gt;</span>&#x000A;    <span class="nt">&lt;plugin&gt;</span>&#x000A;      <span class="nt">&lt;groupId&gt;</span>org.apache.maven.plugins<span class="nt">&lt;/groupId&gt;</span>&#x000A;      <span class="nt">&lt;artifactId&gt;</span>maven-compiler-plugin<span class="nt">&lt;/artifactId&gt;</span>&#x000A;      <span class="nt">&lt;configuration&gt;</span>&#x000A;        <span class="nt">&lt;target&gt;</span>1.5<span class="nt">&lt;/target&gt;</span>&#x000A;        <span class="nt">&lt;source&gt;</span>1.5<span class="nt">&lt;/source&gt;</span>&#x000A;      <span class="nt">&lt;/configuration&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><h2 id="LoadingtheprojectinyourIDE">Loading the project in your IDE</h2><p>We can use Maven to generate the ne
 eded files for your IDE:</p><p>Inside the project, run the following command</p><pre>
+mvn eclipse:eclipse
+</pre><p>or</p><pre>
+mvn idea:idea
+</pre><p>The project files for your IDE should now be created.  Just open the IDE and load the project.</p><h2 id="Creatingabasiccommandclass">Creating a basic command class</h2><p>We can now create the command class <tt>HelloShellCommand.java</tt></p><div class="syntax"><div class="highlight"><pre><span class="kn">package</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">shell</span><span class="o">.</span><span class="na">samples</span><span class="o">;</span>&#x000A;&#x000A;<span class="kn">import</span> <span class="nn">org.apache.felix.gogo.commands.Command</span><span class="o">;</span>&#x000A;<span class="kn">import</span> <span class="nn">org.apache.karaf.shell.console.OsgiCommandSupport</span><span class="o">;</span>&#x000A;&#x000A;<span class="nd">@Command</span><span class="o">(</span><span class="n">scope</span> <span class="o">=</span> <span
  class="s">&quot;test&quot;</span><span class="o">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s">&quot;hello&quot;</span><span class="o">,</span> <span class="n">description</span><span class="o">=</span><span class="s">&quot;Says hello&quot;</span><span class="o">)</span>&#x000A;<span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloShellCommand</span> <span class="kd">extends</span> <span class="n">OsgiCommandSupport</span> <span class="o">{</span>&#x000A;&#x000A;    <span class="nd">@Override</span>&#x000A;    <span class="kd">protected</span> <span class="n">Object</span> <span class="nf">doExecute</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span>&#x000A;        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Executing H
 ello command&quot;</span><span class="o">);</span>&#x000A;        <span class="k">return</span> <span class="kc">null</span><span class="o">;</span>&#x000A;    <span class="o">}</span>&#x000A;<span class="o">}</span>&#x000A;</pre></div>&#x000A;</div><h2 id="Creatingtheassociatedblueprintconfigurationfiles">Creating the associated blueprint configuration files</h2><p>The blueprint configuration file will be used to create the command and register it in the OSGi registry, which is the way to make the command available to Karaf console.  This blueprint file must be located in the <tt>OSGI-INF/blueprint/</tt> directory inside the bundle.</p><p>If you don't have the <tt>src/main/resources</tt> directory yet, create it.</p><pre>
+mkdir src/main/resources
+</pre><p>Then, re-generate the IDE project files and reload it so that this folder is now recognized as a source folder.</p><p>Inside this directory, create the <tt>OSGI-INF/blueprint/</tt> directory and put the following file inside (the name of this file has no impact at all):</p><div class="syntax"><div class="highlight"><pre><span class="nt">&lt;blueprint</span> <span class="na">xmlns=</span><span class="s">&quot;http://www.osgi.org/xmlns/blueprint/v1.0.0&quot;</span><span class="nt">&gt;</span>&#x000A;&#x000A;    <span class="nt">&lt;command-bundle</span> <span class="na">xmlns=</span><span class="s">&quot;http://karaf.apache.org/xmlns/shell/v1.0.0&quot;</span><span class="nt">&gt;</span>&#x000A;        <span class="nt">&lt;command</span> <span class="na">name=</span><span class="s">&quot;test/hello&quot;</span><span class="nt">&gt;</span>&#x000A;            <span class="nt">&lt;action</span> <span class="na">class=</span><span class="s">&quot;org.apache.karaf.shell.samples.Hel
 loShellCommand&quot;</span><span class="nt">/&gt;</span>&#x000A;        <span class="nt">&lt;/command&gt;</span>&#x000A;    <span class="nt">&lt;/command-bundle&gt;</span>&#x000A;&#x000A;<span class="nt">&lt;/blueprint&gt;</span>&#x000A;</pre></div>&#x000A;</div><h2 id="Compilingthejar">Compiling the jar</h2><p>Let's try to build the jar.  Remove the test classes and sample classes if you used the artifact, then from the command line, run:</p><pre>
+mvn install
+</pre><p>The end of the maven output should look like:</p><pre>
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+</pre><h2 id="TestinKaraf">Test in Karaf</h2><p>Launch a Karaf instance and run the following command to install the newly created bundle:</p><pre>
+karaf@root> osgi:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT
+</pre><p>Let's try running the command:</p><pre>
+karaf@root> test:hello
+Executing Hello command
+</pre><h1 id="Commandcompleter">Command completer</h1><p>A completer allows you to automatically complete a command argument using &lt;tab>. A completer is simply a bean which is injected to a command.</p><p>Of course to be able to complete it, the command should require an argument.</p><h2 id="Commandargument">Command argument</h2><p>We add an argument to the HelloCommand:</p><pre>
+package org.apache.karaf.shell.samples;
+
+import org.apache.felix.gogo.commands.Command;
+import org.apache.felix.gogo.commands.Argument;
+import org.apache.karaf.shell.console.OsgiCommandSupport;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+public class HelloShellCommand extends OsgiCommandSupport {
+
+    @Argument(index = 0, name = "arg", description = "The command argument", required = false, multiValued = false)
+    String arg = null;
+
+    @Override
+    protected Object doExecute() throws Exception {
+        System.out.println("Executing Hello command");
+        return null;
+    }
+}
+</pre><p>The Blueprint configuration file is the same as previously.</p><h2 id="Completerbean">Completer bean</h2><p>A completer is a bean which implements the Completer interface:</p><pre>
+package org.apache.karaf.shell.samples;
+
+import org.apache.karaf.shell.console.completer.StringsCompleter;
+import org.apache.karaf.shell.console.Completer;
+
+/**
+ * &lt;p>
+ * A very simple completer.
+ * &lt;/p>
+ */
+public class SimpleCompleter implements Completer {
+
+ /**
+  * @param buffer the beginning string typed by the user
+  * @param cursor the position of the cursor
+  * @param candidates the list of completions proposed to the user
+  */
+ public int complete(String buffer, int cursor, List candidates) {
+    StringsCompleter delegate = new StringsCompleter();
+    delegate.getStrings().add("one");
+    delegate.getStrings().add("two");
+    delegate.getStrings().add("three");
+    return delegate.complete(buffer, cursor, candidates);
+ }
+
+}
+</pre><h2 id="Blueprintconfigurationfile">Blueprint configuration file</h2><p>Using Blueprint, you can "inject" the completer linked to your command. The same completer could be used for several commands and a command can have several completers:</p><pre>
+&lt;blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+
+    &lt;command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.0.0">
+        &lt;command name="test/hello">
+            &lt;action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+            &lt;completers>
+                &lt;ref component-id="simpleCompleter"/>
+                &lt;null/>
+            &lt;/completers>
+        &lt;/command>
+    &lt;/command-bundle>
+
+    &lt;bean id="simpleCompleter" class="org.apache.karaf.shell.samples.SimpleCompleter"/>
+
+&lt;/blueprint>
+</pre><h2 id="TestinKaraf2">Test in Karaf</h2><p>Launch a Karaf instance and run the following command to install the newly created bundle:</p><pre>
+karaf@root> osgi:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT
+</pre><p>Let's try running the command:</p><pre>
+karaf@root> test:hello &lt;tab>
+ one    two    three
+</pre>
+                </div>
+              </td>
+            </tr>
+          </table>
+        </td>
+        <td id="cell-2-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-3-0">
+          &nbsp;
+        </td>
+        <td id="cell-3-1">
+          &nbsp;
+        </td>
+        <td id="cell-3-2">
+          <div id="footer">
+            <div id="site-footer">
+              &copy; 2008-2011 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>
+          </div>
+        </td>
+        <td id="cell-3-3">
+          &nbsp;
+        </td>
+        <td id="cell-3-4">
+          &nbsp;
+        </td>
+      </tr>
+      <tr width="100%">
+        <td id="cell-4-0" colspan="2">
+          &nbsp;
+        </td>
+        <td id="cell-4-1">
+          &nbsp;
+        </td>
+        <td id="cell-4-2" colspan="2">
+          &nbsp;
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
\ No newline at end of file



Mime
View raw message