Modified: karaf/site/production/manual/latest/index.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/index.html?rev=1839907&r1=1839906&r2=1839907&view=diff ============================================================================== --- karaf/site/production/manual/latest/index.html (original) +++ karaf/site/production/manual/latest/index.html Mon Sep 3 06:10:48 2018 @@ -697,6 +697,7 @@ table.CodeRay td.code>pre{padding:0} <li><a href="#_schedule_a_new_job_using_the_whitebox_service_paradigm_recommended">4.19.3. Schedule a new Job using the Whitebox-Service paradigm (recommended)</a></li> <li><a href="#_schedule_a_new_job_using_the_gogo_shell">4.19.4. Schedule a new Job using the Gogo Shell</a></li> <li><a href="#_schedule_a_new_job_using_the_scheduler_service">4.19.5. Schedule a new Job using the Scheduler Service</a></li> +<li><a href="#_update_scheduling_of_an_existing_job">4.19.6. Update scheduling of an existing job</a></li> </ul> </li> <li><a href="#_tuning">4.20. Tuning</a> @@ -743,34 +744,36 @@ table.CodeRay td.code>pre{padding:0} <ul class="sectlevel3"> <li><a href="#_console_2">5.4.1. Console</a></li> <li><a href="#_adding_a_branding_properties_file_to_etc">5.4.2. Adding a branding.properties file to etc</a></li> -<li><a href="#_branding_bundle">5.4.3. Branding bundle</a></li> -<li><a href="#_installing_the_branding_bundle">5.4.4. Installing the branding bundle</a></li> -<li><a href="#_webconsole_3">5.4.5. WebConsole</a></li> </ul> </li> -<li><a href="#_extending">5.5. Extending</a> +<li><a href="#_adding_a_branding_ssh_properties_file_to_etc">5.5. Adding a branding-ssh.properties file to etc</a> <ul class="sectlevel3"> -<li><a href="#_console_3">5.5.1. Console</a></li> -<li><a href="#_webconsole_4">5.5.2. WebConsole</a></li> +<li><a href="#_branding_bundle">5.5.1. Branding bundle</a></li> +<li><a href="#_webconsole_3">5.5.2. WebConsole</a></li> </ul> </li> -<li><a href="#_using_the_karaf_maven_plugin">5.6. Using the karaf-maven-plugin</a> +<li><a href="#_extending">5.6. Extending</a> <ul class="sectlevel3"> -<li><a href="#_packaging">5.6.1. Packaging</a></li> -<li><a href="#_commands_goals">5.6.2. Commands goals</a></li> -<li><a href="#_features_and_kar_goals">5.6.3. Features and kar goals</a></li> -<li><a href="#_instances_and_distributions_goals">5.6.4. Instances and distributions goals</a></li> -<li><a href="#_run_client_deploy_goals">5.6.5. Run, client, deploy goals</a></li> +<li><a href="#_shell_commands">5.6.1. Shell commands</a></li> +<li><a href="#_webconsole_4">5.6.2. WebConsole</a></li> </ul> </li> -<li><a href="#_custom_distributions">5.7. Custom distributions</a> +<li><a href="#_using_the_karaf_maven_plugin">5.7. Using the karaf-maven-plugin</a> <ul class="sectlevel3"> -<li><a href="#_maven_assembly">5.7.1. Maven assembly</a></li> -<li><a href="#__deprecated_old_style_maven_assembly">5.7.2. (deprecated old style) Maven assembly</a></li> +<li><a href="#_packaging">5.7.1. Packaging</a></li> +<li><a href="#_commands_goals">5.7.2. Commands goals</a></li> +<li><a href="#_features_and_kar_goals">5.7.3. Features and kar goals</a></li> +<li><a href="#_instances_and_distributions_goals">5.7.4. Instances and distributions goals</a></li> +<li><a href="#_run_client_deploy_goals">5.7.5. Run, client, deploy goals</a></li> </ul> </li> -<li><a href="#_osgi_services_2">5.8. OSGi Services</a></li> -<li><a href="#_basic_bundle_creation_using_the_felix_maven_bundle_plugin">5.9. Basic bundle creation using the Felix maven-bundle-plugin</a> +<li><a href="#_custom_distributions">5.8. Custom distributions</a> +<ul class="sectlevel3"> +<li><a href="#_maven_assembly">5.8.1. Maven assembly</a></li> +<li><a href="#__deprecated_old_style_maven_assembly">5.8.2. (deprecated old style) Maven assembly</a></li> +</ul> +</li> +<li><a href="#_creating_bundles">5.9. Creating Bundles</a> <ul class="sectlevel3"> <li><a href="#_add_extended_information_to_bundles">5.9.1. Add extended information to bundles</a></li> <li><a href="#_wiki_syntax">5.9.2. Wiki Syntax</a></li> @@ -780,52 +783,60 @@ table.CodeRay td.code>pre{padding:0} <ul class="sectlevel3"> <li><a href="#_dynamically_wrapping_jars">5.10.1. Dynamically wrapping jars</a></li> <li><a href="#_statically_bundling_jars">5.10.2. Statically bundling jars</a></li> +<li><a href="#_blueprint">5.10.3. Blueprint</a></li> +<li><a href="#_scr">5.10.4. SCR</a></li> </ul> </li> -<li><a href="#_blueprint">5.11. Blueprint</a></li> -<li><a href="#_declarative_service_ds">5.12. Declarative Service (DS)</a></li> -<li><a href="#_cdi_2">5.13. CDI</a></li> -<li><a href="#_archetypes">5.14. Archetypes</a> +<li><a href="#_archetypes">5.11. Archetypes</a> <ul class="sectlevel3"> -<li><a href="#_create_a_command_karaf_command_archetype">5.14.1. Create a command (karaf-command-archetype)</a></li> -<li><a href="#_create_an_osgi_bundle_karaf_bundle_archetype">5.14.2. Create an OSGi bundle (karaf-bundle-archetype)</a></li> -<li><a href="#_create_an_osgi_blueprint_bundle_karaf_blueprint_archetype">5.14.3. Create an OSGi blueprint bundle (karaf-blueprint-archetype)</a></li> -<li><a href="#_create_a_features_xml_karaf_feature_archetype">5.14.4. Create a features XML (karaf-feature-archetype)</a></li> -<li><a href="#_create_a_kar_file_karaf_kar_archetype">5.14.5. Create a KAR file (karaf-kar-archetype)</a></li> +<li><a href="#_create_a_command_karaf_command_archetype">5.11.1. Create a command (karaf-command-archetype)</a></li> +<li><a href="#_create_an_osgi_bundle_karaf_bundle_archetype">5.11.2. Create an OSGi bundle (karaf-bundle-archetype)</a></li> +<li><a href="#_create_an_osgi_blueprint_bundle_karaf_blueprint_archetype">5.11.3. Create an OSGi blueprint bundle (karaf-blueprint-archetype)</a></li> +<li><a href="#_create_a_features_xml_karaf_feature_archetype">5.11.4. Create a features XML (karaf-feature-archetype)</a></li> +<li><a href="#_create_a_kar_file_karaf_kar_archetype">5.11.5. Create a KAR file (karaf-kar-archetype)</a></li> </ul> </li> -<li><a href="#_security_framework">5.15. Security framework</a> +<li><a href="#_security_framework">5.12. Security framework</a> <ul class="sectlevel3"> -<li><a href="#_overview_2">5.15.1. Overview</a></li> -<li><a href="#_schema">5.15.2. Schema</a></li> -<li><a href="#_architecture">5.15.3. Architecture</a></li> -<li><a href="#_available_realm_and_login_modules">5.15.4. Available realm and login modules</a></li> -<li><a href="#_encryption_service">5.15.5. Encryption service</a></li> -<li><a href="#_role_discovery_policies">5.15.6. Role discovery policies</a></li> -<li><a href="#_default_role_policies">5.15.7. Default role policies</a></li> +<li><a href="#_overview_2">5.12.1. Overview</a></li> +<li><a href="#_schema">5.12.2. Schema</a></li> +<li><a href="#_architecture">5.12.3. Architecture</a></li> +<li><a href="#_available_realm_and_login_modules">5.12.4. Available realm and login modules</a></li> +<li><a href="#_encryption_service">5.12.5. Encryption service</a></li> +<li><a href="#_role_discovery_policies">5.12.6. Role discovery policies</a></li> +<li><a href="#_default_role_policies">5.12.7. Default role policies</a></li> </ul> </li> -<li><a href="#_troubleshooting_debugging_profiling_and_monitoring">5.16. Troubleshooting, Debugging, Profiling, and Monitoring</a> +<li><a href="#_troubleshooting_debugging_profiling_and_monitoring">5.13. Troubleshooting, Debugging, Profiling, and Monitoring</a> <ul class="sectlevel3"> -<li><a href="#_troubleshooting">5.16.1. Troubleshooting</a></li> -<li><a href="#_debugging">5.16.2. Debugging</a></li> -<li><a href="#_profiling">5.16.3. Profiling</a></li> -<li><a href="#_monitoring">5.16.4. Monitoring</a></li> +<li><a href="#_troubleshooting">5.13.1. Troubleshooting</a></li> +<li><a href="#_debugging">5.13.2. Debugging</a></li> +<li><a href="#_profiling">5.13.3. Profiling</a></li> +<li><a href="#_monitoring">5.13.4. Monitoring</a></li> </ul> </li> -<li><a href="#_writing_integration_tests">5.17. Writing integration tests</a> +<li><a href="#_writing_integration_tests">5.14. Writing integration tests</a></li> +<li><a href="#_dump_extender">5.15. Dump extender</a> <ul class="sectlevel3"> -<li><a href="#_introduction">5.17.1. Introduction</a></li> -<li><a href="#_commands_11">5.17.2. Commands</a></li> -<li><a href="#_driver">5.17.3. Driver</a></li> +<li><a href="#_jdbc_jpa">5.15.1. JDBC & JPA</a></li> +<li><a href="#_jms_2">5.15.2. JMS</a></li> +<li><a href="#_custom_log_appender">5.15.3. Custom log appender</a></li> +<li><a href="#_custom_jmx_mbean">5.15.4. Custom JMX MBean</a></li> +<li><a href="#_working_with_profiles">5.15.5. Working with profiles</a></li> +<li><a href="#_servlet">5.15.6. Servlet</a></li> +<li><a href="#_war">5.15.7. WAR</a></li> +<li><a href="#_rest_service">5.15.8. REST service</a></li> +<li><a href="#_soap_service">5.15.9. SOAP service</a></li> +<li><a href="#_scheduling_jobs">5.15.10. Scheduling jobs</a></li> +<li><a href="#_custom_url_handler">5.15.11. Custom URL handler</a></li> </ul> </li> -<li><a href="#_github_contributions">5.18. Github Contributions</a> +<li><a href="#_github_contributions">5.16. Github Contributions</a> <ul class="sectlevel3"> -<li><a href="#_introduction_2">5.18.1. Introduction</a></li> -<li><a href="#_suggested_workflow">5.18.2. Suggested Workflow</a></li> -<li><a href="#_license_reminder">5.18.3. License Reminder</a></li> -<li><a href="#_how_to_generate_a_one_file_patch_via_throw_away_branch">5.18.4. How to Generate a One-File-Patch Via Throw-Away Branch</a></li> +<li><a href="#_introduction">5.16.1. Introduction</a></li> +<li><a href="#_suggested_workflow">5.16.2. Suggested Workflow</a></li> +<li><a href="#_license_reminder">5.16.3. License Reminder</a></li> +<li><a href="#_how_to_generate_a_one_file_patch_via_throw_away_branch">5.16.4. How to Generate a One-File-Patch Via Throw-Away Branch</a></li> </ul> </li> </ul> @@ -842,7 +853,7 @@ table.CodeRay td.code>pre{padding:0} </div> <div class="paragraph"> <p>Karaf can be used standalone as a container, supporting a wide range of applications and technologies. -It also supports the "run anywhere" (on any machine with Java, cloud, docker images, …​) using the embedded mode.</p> +It also supports the "run anywhere" (on any machine with Java, cloud, dockerClient images, …​) using the embedded mode.</p> </div> <div class="paragraph"> <p>It’s a lightweight, powerful, and enterprise ready platform.</p> @@ -1663,6 +1674,59 @@ tar xvf apache-karaf-4.0.0.tar</pre> </tr> </table> </div> +<div class="sect5"> +<h6 id="_installation_on_debian_gnu_linux">Installation on Debian GNU/linux</h6> +<div class="paragraph"> +<p>There is an unofficial debian package of karaf:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p>Add the key of the unofficial debian archive containing karaf</p> +<div class="listingblock"> +<div class="content"> +<pre>wget -O - https://apt.bang.priv.no/apt_pub.gpg | apt-key add -</pre> +</div> +</div> +</li> +<li> +<p>Open /etc/apt/sources.list in a text editor and add the following lines:</p> +<div class="listingblock"> +<div class="content"> +<pre># Unofficial APT archive for apache karaf +deb http://apt.bang.priv.no/public stable main</pre> +</div> +</div> +</li> +<li> +<p>Update the APT package index and install the package</p> +<div class="listingblock"> +<div class="content"> +<pre>apt-get update +apt-get install openjdk-8-jdk karaf</pre> +</div> +</div> +</li> +</ol> +</div> +<div class="paragraph"> +<p>The installed karaf will run as user karaf, group karaf, listening to the usual default karaf ports, be started with systemd, with KARAF_ETC in /etc/karaf and KARAF_DATA in /var/lib/karaf/data.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +<div class="paragraph"> +<p>When/if the link:<code><a href="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=881297"; class="bare">https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=881297</a></code>[Debian Request For Package (RFP) of karaf] results in an official karaf package becoming available, the unofficial debian package will be discontinued.</p> +</div> +</td> +</tr> +</table> +</div> +</div> </div> </div> <div class="sect3"> @@ -1834,7 +1898,7 @@ This property is used to locate the <cod <p><code>/bin</code>: control scripts to start, stop, login, …​</p> </li> <li> -<p><code>/demos</code>: contains some simple Karaf samples</p> +<p><code>/examples</code>: contains several examples to start with Apache Karaf</p> </li> <li> <p><code>/etc</code>: configuration files</p> @@ -1866,7 +1930,7 @@ This property is used to locate the <cod <div class="ulist"> <ul> <li> -<p><code>/lib/boot</code>: contains the systeù libraries used at Karaf bootstrap</p> +<p><code>/lib/boot</code>: contains the system libraries used at Karaf bootstrap</p> </li> <li> <p><code>/lib/endorsed</code>: directory for endorsed libraries</p> @@ -2914,6 +2978,10 @@ wrapper.java.additional.4=-Dkaraf.etc=%K wrapper.java.additional.5=-Dcom.sun.management.jmxremote wrapper.java.additional.6=-Dkaraf.startLocalConsole=false wrapper.java.additional.7=-Dkaraf.startRemoteShell=true +wrapper.java.additional.8=-Djava.io.tmpdir=%KARAF_DATA%/tmp +# Uncomment if you need libraries on Java 8 +#wrapper.java.additional.9=-Djava.endorsed.dirs=%JAVA_HOME%/jre/lib/endorsed:%JAVA_HOME%/lib/endorsed:%KARAF_HOME%/lib/endorsed +#wrapper.java.additional.10=-Djava.ext.dirs=%JAVA_HOME%/jre/lib/ext:%JAVA_HOME%/lib/ext:%KARAF_HOME%/lib/ext # Uncomment to enable jmx #wrapper.java.additional.n=-Dcom.sun.management.jmxremote.port=1616 @@ -4032,10 +4100,15 @@ hostKey = ${karaf.etc}/host.key # sshRole = admin # +# Defines if the SFTP system is enabled or not in the SSH server +# +sftpEnabled=true + +# # Self defined key size in 1024, 2048, 3072, or 4096 -# If not set, this defaults to 4096. +# If not set, this defaults to 2048. # -# keySize = 4096 +# keySize = 2048 # # Specify host key algorithm, defaults to RSA @@ -4078,6 +4151,10 @@ and private key pair of the SSHd server. defined in <code>etc/system.properties</code>. See the [Security section|security] of this user guide for details.</p> </li> <li> +<p><code>sftpEnabled</code> controls if the SSH server start the SFTP system or not. When enabled, Karaf SSHd supports SFTP, meaning +that you can remotely access to the Karaf filesystem with any sftp clients.</p> +</li> +<li> <p><code>keySize</code> is the key size used by the SSHd server. The possible values are 1024, 2048, 3072, or 4096. The default value is 1024.</p> </li> @@ -4397,11 +4474,11 @@ Password: lftp karaf@localhost:~> ls -rw-r--r-- 1 jbonofre jbonofre 27754 Oct 26 10:50 LICENSE -rw-r--r-- 1 jbonofre jbonofre 1919 Dec 3 05:34 NOTICE --rw-r--r-- 1 jbonofre jbonofre 3933 Aug 18 2012 README --rw-r--r-- 1 jbonofre jbonofre 101041 Dec 3 05:34 RELEASE-NOTES +-rw-r--r-- 1 jbonofre jbonofre 3933 Aug 18 2012 README.md +-rw-r--r-- 1 jbonofre jbonofre 101041 Dec 3 05:34 RELEASE-NOTES.md drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 bin drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 18:57 data -drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 demos +drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 examples drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 deploy drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 17:59 etc drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 instances @@ -9410,6 +9487,9 @@ can access those.</p> <pre>org.osgi.framework.bootdelegation = ...,org.bouncycastle*</pre> </div> </div> +<div class="paragraph"> +<p>Unresolved directive in index.adoc - include::user-guide/dockerClient.adoc[]</p> +</div> </div> </div> <div class="sect2"> @@ -10284,6 +10364,16 @@ reverse domain name convention.</p> <p>You can note the <code>webbundle</code> prefix, and the <code>Bundle-SymbolicName</code> and <code>Web-ContextPath</code> headers on the URL.</p> </div> </div> +<div class="sect5"> +<h6 id="_http_proxy">HTTP proxy</h6> +<div class="paragraph"> +<p>Apache Karaf provides a HTTP proxy service. It allows you to proxy any HTTP URLs within Karaf. It allows you to expose +remote web applications in Karaf.</p> +</div> +<div class="paragraph"> +<p>You can use the Karaf <code>ProxyService</code> programmatically, or via the corresponding shell commands and MBeans.</p> +</div> +</div> </div> <div class="sect4"> <h5 id="_commands_7">Commands</h5> @@ -10362,6 +10452,46 @@ corresponding to the bundle ID (as displ </div> </div> </div> +<div class="sect5"> +<h6 id="__code_http_proxies_code"><code>http:proxies</code></h6> +<div class="paragraph"> +<p>The <code>http:proxies</code> command list the configured HTTP proxies:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre>karaf@root()> http:proxies +karaf@root()> http:proxies +URL â ProxyTo +âââââââââââââ¼âââââââââââââââââââââââââââââââââââââ +/webconsole â http://localhost:8181/system/console</pre> +</div> +</div> +</div> +</div> +<div class="sect4"> +<h5 id="__code_http_proxy_add_code"><code>http:proxy-add</code></h5> +<div class="paragraph"> +<p>The <code>http:proxy-add</code> registers a new HTTP proxy. For instance, you can proxy the Karaf WebConsole on another URL of your choice using:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre>karaf@root()> http:proxy-add /webconsole http://localhost:8181/system/console</pre> +</div> +</div> +<div class="paragraph"> +<p>Karaf HTTP Proxy can proxy any URL, like a backend running on Docker or a remote URL.</p> +</div> +</div> +<div class="sect4"> +<h5 id="__code_http_proxy_remove_code"><code>http:proxy-remove</code></h5> +<div class="paragraph"> +<p>The <code>http:proxy-remove</code> removes an existing HTTP proxy:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre>karaf@root()> http:proxy-remove /webconsole</pre> +</div> +</div> </div> <div class="sect4"> <h5 id="_jmx_httpmbean">JMX HttpMBean</h5> @@ -10395,6 +10525,35 @@ corresponding to the bundle ID (as displ </li> </ul> </div> +<div class="paragraph"> +<p>The <code>Proxies</code> attribute provides a tabular data providing the list of HTTP proxies including:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><code>URL</code> is the proxy URL.</p> +</li> +<li> +<p><code>proxyTo</code> is the proxy target.</p> +</li> +<li> +<p><code>prefix</code> is optional proxy prefix.</p> +</li> +</ul> +</div> +</div> +<div class="sect5"> +<h6 id="_operations_8">Operations</h6> +<div class="ulist"> +<ul> +<li> +<p><code>addProxy(url, proxyTo, prefix)</code> registers a new HTTP proxy.</p> +</li> +<li> +<p><code>removeProxy(url)</code> removes an existing HTTP proxy.</p> +</li> +</ul> +</div> </div> </div> <div class="sect4"> @@ -10434,7 +10593,7 @@ corresponding to the bundle ID (as displ </div> </div> <div class="sect5"> -<h6 id="_operations_8">Operations</h6> +<h6 id="_operations_9">Operations</h6> <div class="ulist"> <ul> <li> @@ -10746,7 +10905,7 @@ and the regular JNDI service.</p> </div> </div> <div class="sect5"> -<h6 id="_operations_9">Operations</h6> +<h6 id="_operations_10">Operations</h6> <div class="ulist"> <ul> <li> @@ -10927,13 +11086,13 @@ aries.transaction.howl.bufferSizeKBytes </div> <div class="listingblock"> <div class="content"> -<pre>karaf@root()> feature:repo-add pax-jdbc -karaf@root()> feature:install pax-jdbc -karaf@root()> feature:install pax-jdbc-config -karaf@root()> feature:install jdbc</pre> +<pre>karaf@root()> feature:install jdbc</pre> </div> </div> <div class="paragraph"> +<p>NB: <code>jdbc</code> feature automatically installs the <code>pax-jdbc-*</code> core features.</p> +</div> +<div class="paragraph"> <p>Pax JDBC provides ready to use adapters for different databases:</p> </div> <div class="ulist"> @@ -11210,7 +11369,7 @@ REF_GENERATION | TYPE_NAME | TABLE_NAME </div> </div> <div class="sect5"> -<h6 id="_operations_10">Operations</h6> +<h6 id="_operations_11">Operations</h6> <div class="ulist"> <ul> <li> @@ -11327,14 +11486,15 @@ SYNTAX ARGUMENTS name The JMS connection factory name + (required) OPTIONS -t, --type - The JMS connection factory type (ActiveMQ or WebsphereMQ) - (defaults to ActiveMQ) - -u, --username - Username to connect to the JMS broker - (defaults to karaf) + The JMS connection factory type (ActiveMQ, Artemis or WebsphereMQ) + (defaults to activemq) + --pool + The pool mechanism to use for this connection factory + (defaults to pooledjms) --help Display this help message --url @@ -11342,6 +11502,9 @@ OPTIONS (defaults to tcp://localhost:61616) -p, --password Password to connect to the JMS broker + (defaults to karaf) + -u, --username + Username to connect to the JMS broker (defaults to karaf)</pre> </div> </div> @@ -11362,6 +11525,9 @@ OPTIONS <li> <p>the <code>-p</code> (<code>--password</code>) option is optional (karaf by default). In the case of the broker requires authentication, it’s the password used.</p> </li> +<li> +<p>the <code>--pool</code> option is optional (<code>pooledjms</code> by default). It allows you to define the pooling framework you want to use: pooledjms, narayana, transx.</p> +</li> </ul> </div> <div class="paragraph"> @@ -11369,8 +11535,23 @@ OPTIONS </div> <div class="listingblock"> <div class="content"> -<pre>karaf@root()> jms:create -t activemq --url tcp://localhost:61616 test</pre> +<pre>karaf@root()> feature:install pax-jms-activemq +karaf@root()> jms:create -t activemq --url tcp://localhost:61616 test</pre> +</div> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +<div class="paragraph"> +<p>When you use ActiveMQ, Karaf uses <code>transx</code> as connection factory pooling framework.</p> </div> +</td> +</tr> +</table> </div> <div class="admonitionblock note"> <table> @@ -11668,7 +11849,7 @@ ID:vostro-59602-1387462183019-3:3:1:1:1 </div> </div> <div class="sect5"> -<h6 id="_operations_11">Operations</h6> +<h6 id="_operations_12">Operations</h6> <div class="ulist"> <ul> <li> @@ -12844,13 +13025,14 @@ Right now, the WebConsole doesn’t </div> </div> <div class="paragraph"> -<p>The <code>scheduler</code> feature automatically installs the <code>scheduler</code> Gogo command group, too:</p> +<p>The <code>scheduler</code> feature automatically installs the <code>scheduler</code> command group, too:</p> </div> <div class="listingblock"> <div class="content"> <pre>scheduler:list scheduler:schedule -scheduler:unschedule</pre> +scheduler:unschedule +scheduler:reschedule</pre> </div> </div> </div> @@ -13037,6 +13219,16 @@ public class Demo { </div> </div> </div> +<div class="sect3"> +<h4 id="_update_scheduling_of_an_existing_job">4.19.6. Update scheduling of an existing job</h4> +<div class="paragraph"> +<p>You can change the scheduling of an existing job using <code>scheduler:reschedule</code> command.</p> +</div> +<div class="paragraph"> +<p>This command works as the schedule command (using the same <code>at</code>, <code>period</code>, <code>cron</code>, …​ options) but taking the job name +as argument (as given by the <code>scheduler:list</code> command).</p> +</div> +</div> </div> <div class="sect2"> <h3 id="_tuning">4.20. Tuning</h3> @@ -13296,21 +13488,6 @@ ones from the bundles.</p> <div class="sect1"> <h2 id="_developer_guide">5. Developer Guide</h2> <div class="sectionbody"> -<div class="admonitionblock note"> -<table> -<tr> -<td class="icon"> -<div class="title">Note</div> -</td> -<td class="content"> -<div class="paragraph"> -<p>The developer guide is currently under a refactoring. The "new" developer guide will document samples providing -in the Karaf Container distribution, in order to have more practical recipes.</p> -</div> -</td> -</tr> -</table> -</div> <div class="sect2"> <h3 id="_developer_commands">5.1. Developer commands</h3> <div class="paragraph"> @@ -14314,156 +14491,22 @@ prompt = \u001B[1m${USER}@${APPLICATION} <p>Start Karaf and you will see your branded Karaf console.</p> </div> </div> -<div class="sect3"> -<h4 id="_branding_bundle">5.4.3. Branding bundle</h4> -<div class="paragraph"> -<p>At startup, Apache Karaf is looking for a bundle which exports the <code>org.apache.karaf.branding</code> package, containing -a <code>branding.properties</code> file.</p> -</div> -<div class="paragraph"> -<p>Basically, a branding bundle is a very simple bundle, just containing a <code>org/apache/karaf/branding/branding.properties</code> -file.</p> -</div> -<div class="paragraph"> -<p>It’s easy to create such branding bundle using Apache Maven.</p> -</div> -<div class="paragraph"> -<p>The following <code>pom.xml</code> creates a branding bundle:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><?xml version="1.0" encoding="UTF-8"?> -<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"> - - <modelVersion>4.0.0</modelVersion> - - <groupId>your.group.id</groupId> - <artifactId>your.branding.artifact.id</artifactId> - <version>1.0-SNAPSHOT</version> - <packaging>bundle</packaging> - <name>Your Branding Bundle Name</name> - - <build> - <plugins> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>2.4.0</version> - <extensions>true</extensions> - <configuration> - <instructions> - <Bundle-SymbolicName>${project.artifactId}</bundle-SymbolicName> - <Import-Package>*</Import-Package> - <Private-Package>!*</Private-Package> - <Export-Package> - org.apache.karaf.branding - </Export-Package> - <Spring-Context>*;public-context:=false</Spring-Context> - </instructions> - </configuration> - </plugin> - </plugins> - </build> - -</project></pre> -</div> -</div> -<div class="paragraph"> -<p>You can put your <code>branding.properties</code> file in the project resources (<code>src/main/resources/org/apache/karaf/branding/branding.properties</code>):</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>welcome = This is my Karaf brand\r\n -prompt = Hey ${USER}></pre> -</div> -</div> -<div class="paragraph"> -<p>For instance, the default Apache Karaf branding properties file contains:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>welcome = \ -\u001B[36m __ __ ____ \u001B[0m\r\n\ -\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\ -\u001B[36m / ,< / __ `/ ___/ __ `/ /_ \u001B[0m\r\n\ -\u001B[36m / /| |/ /_/ / / / /_/ / __/ \u001B[0m\r\n\ -\u001B[36m /_/ |_|\\__,_/_/ \\__,_/_/ \u001B[0m\r\n\ -\r\n\ -\u001B[1m Apache Karaf\u001B[0m (${project.version})\r\n\ -\r\n\ -Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\ - and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\ -Hit '\u001B[1m<ctrl-d>\u001B[0m' or type '\u001B[1msystem:shutdown\u001B[0m' or '\u001B[1mlogout\u001B[0m' to shutdown Karaf.\r\n</pre> -</div> -</div> -<div class="paragraph"> -<p>As you can see, the <code>branding.properties</code> contains two properties:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>welcome is the welcome message displayed when you start Apache Karaf console.</p> -</li> -<li> -<p>prompt is the string used to display the console prompt. This string supports variables:</p> -<div class="ulist"> -<ul> -<li> -<p>${USER` defines the user name of the prompt. Caveat — the user name is presently static and hardcoded to "karaf", -however you can override here with your own static user name.</p> -</li> -<li> -<p>$<code>APPLICATION</code> defines the Karaf instance name.</p> -</li> -</ul> -</div> -</li> -</ul> -</div> -<div class="paragraph"> -<p>As you can see, both strings support ASCII escaped format. For instance \u001B[1m switches the foreground in bold -and \u001B[0m switch back to normal.</p> </div> +<div class="sect2"> +<h3 id="_adding_a_branding_ssh_properties_file_to_etc">5.5. Adding a branding-ssh.properties file to etc</h3> <div class="paragraph"> -<p>Some examples of customized prompt examples follow:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre># Define a user with fancy colors -prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m></pre> -</div> -</div> -<div class="listingblock"> -<div class="content"> -<pre># Static sober prompt -prompt = my-user@my-karaf></pre> -</div> -</div> +<p>In a similar way, a <code>etc/branding-ssh.properties</code> file can be added. It should contain the same +<code>welcome</code> and <code>prompt</code> entries but those will be used for external clients connecting through ssh. +The values default to the ones in <code>etc/branding.properties</code> if this file is not defined.</p> </div> <div class="sect3"> -<h4 id="_installing_the_branding_bundle">5.4.4. Installing the branding bundle</h4> -<div class="paragraph"> -<p>Thanks to the <code>pom.xml</code>, we can use <code>mvn</code> to build the branding bundle:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>mvn install</pre> -</div> -</div> -<div class="paragraph"> -<p>You just have to drop the file in the <code>lib</code> directory:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>cp branding.jar /opt/apache-karaf-4.0.0/lib/karaf-branding.jar</pre> -</div> -</div> +<h4 id="_branding_bundle">5.5.1. Branding bundle</h4> <div class="paragraph"> -<p>You can now start Apache Karaf to see your branded console.</p> +<p>See [<a href="https://github.com/apache/karaf/examples/karaf-branding-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-branding-example/README.md</a>].</p> </div> </div> <div class="sect3"> -<h4 id="_webconsole_3">5.4.5. WebConsole</h4> +<h4 id="_webconsole_3">5.5.2. WebConsole</h4> <div class="paragraph"> <p>It’s also possible to brand the Apache Karaf WebConsole.</p> </div> @@ -14549,427 +14592,28 @@ webconsole.stylesheet = /res/karaf/ui/we </div> </div> <div class="sect2"> -<h3 id="_extending">5.5. Extending</h3> +<h3 id="_extending">5.6. Extending</h3> <div class="paragraph"> <p>Apache Karaf is a very flexible container that you can extend very easily.</p> </div> <div class="sect3"> -<h4 id="_console_3">5.5.1. Console</h4> +<h4 id="_shell_commands">5.6.1. Shell commands</h4> <div class="paragraph"> -<p>In this section, you will see how to extend the console by adding your own command.</p> -</div> -<div class="paragraph"> -<p>We will leverage Apache Maven to create and build the OSGi bundle. -This OSGi bundle will use Blueprint. We don’t cover the details of OSGi bundle and Blueprint, see the specific -sections for details.</p> -</div> -<div class="sect4"> -<h5 id="_create_the_maven_project">Create the Maven project</h5> -<div class="paragraph"> -<p>To create the Maven project, we can:</p> -</div> -<div class="ulist"> -<ul> -<li> -<p>use a Maven archetype</p> -</li> -<li> -<p>create by hand</p> -</li> -</ul> -</div> -<div class="sect5"> -<h6 id="_using_archetype">Using archetype</h6> -<div class="paragraph"> -<p>The Maven Quickstart archetype can create an empty Maven project where you can put your project definition.</p> -</div> -<div class="paragraph"> -<p>You can directly use:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>mvn archetype:generate \ - -DarchetypeArtifactId=maven-archetype-quickstart \ - -DgroupId=org.apache.karaf.shell.samples \ - -DartifactId=shell-sample-commands \ - -Dversion=1.0-SNAPSHOT</pre> -</div> -</div> -<div class="paragraph"> -<p>It results to a ready to use project, including a <code>pom.xml</code>.</p> -</div> -<div class="paragraph"> -<p>You can also use Maven archetype in interactive mode. You will have to answer to some questions used to generate -the project with the <code>pom.xml</code>:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>mvn archetype:generate -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> -</div> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_by_hand">By hand</h5> -<div class="paragraph"> -<p>Alternatively, you can simply create the directory <code>shell-sample-commands</code> and create the <code>pom.xml</code> file inside it:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><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"> - - <modelVersion>4.0.0</modelVersion> - - <groupId>org.apache.karaf.shell.samples</groupId> - <artifactId>shell-sample-commands<artifactId> - <packaging>bundle</packaging> - <version>1.0-SNAPSHOT</version> - <name>shell-sample-commmands</name> - - - <dependencies> - <dependency> - <groupId>org.apache.karaf.shell</groupId> - <artifactId>org.apache.karaf.shell.core</artifactId> - <version>${project.version}</version> - </dependency> - <dependency> - <groupId>junit</groupId> - <artifactId>junit</artifactId> - <version>3.8.1</version> - <scope>test</scope> - </dependency> - </dependencies> - - <build> - <plugins> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>${felix.plugin.version}</version> - <configuration> - <instructions> - <Import-Package> - org.apache.felix.service.command, - org.apache.karaf.shell.commands, - org.apache.karaf.shell.console, - * - </Import-Package> - </instructions> - </configuration> - </plugin> - </plugins> - </build> - -</project></pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_configuring_for_java_8">Configuring for Java 8</h5> -<div class="paragraph"> -<p>We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.6 or 1.7 to compile the jar. -Just add the following snippet after the <code>dependencies</code> section.</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-compiler-plugin</artifactId> - <configuration> - <target>1.8</target> - <source>1.8</source> - </configuration> - </plugin> - </plugins> -</build></pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_loading_the_project_in_your_ide">Loading the project in your IDE</h5> -<div class="paragraph"> -<p>We can use Maven to generate the needed files for your IDE:</p> -</div> -<div class="paragraph"> -<p>Inside the project, run the following command</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>mvn eclipse:eclipse</pre> -</div> -</div> -<div class="paragraph"> -<p>or</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>mvn idea:idea</pre> -</div> -</div> -<div class="paragraph"> -<p>The project files for your IDE should now be created. Just open the IDE and load the project.</p> -</div> -</div> -<div class="sect4"> -<h5 id="_creating_a_basic_command_class">Creating a basic command class</h5> -<div class="paragraph"> -<p>We can now create the command class <code>HelloShellCommand.java</code></p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.Action; -import org.apache.karaf.shell.api.action.Command; -import org.apache.karaf.shell.api.action.lifecycle.Service; - -@Command(scope = "test", name = "hello", description="Says hello") -@Service -public class HelloShellCommand implements Action { - - @Override - public Object execute() throws Exception { - System.out.println("Executing Hello command"); - return null; - } -}</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_manifest">Manifest</h5> -<div class="paragraph"> -<p>In order for Karaf to find your command, you need to add the <code>Karaf-Commands=*</code> manifest header.</p> -</div> -<div class="paragraph"> -<p>This is usually done by modifying the maven bundle plugin configuration</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <configuration> - <instructions> - <Karaf-Commands>*</Karaf-Commands> - </instructions> - </configuration> -</plugin></pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_compile">Compile</h5> -<div class="paragraph"> -<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> -</div> -<div class="listingblock"> -<div class="content"> -<pre>mvn install</pre> -</div> -</div> -<div class="paragraph"> -<p>The end of the maven output should look like:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESSFUL -[INFO] ------------------------------------------------------------------------</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_test">Test</h5> -<div class="paragraph"> -<p>Launch Apache Karaf and install your bundle:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT</pre> -</div> -</div> -<div class="paragraph"> -<p>Let’s try running the command:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>karaf@root()> test:hello -Executing Hello command</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_command_completer">Command completer</h5> -<div class="paragraph"> -<p>A completer allows you to automatically complete a command argument using <tab>. A completer is simply a bean which is -injected to a command.</p> -</div> -<div class="paragraph"> -<p>Of course to be able to complete it, the command should require an argument.</p> -</div> -</div> -<div class="sect4"> -<h5 id="_command_argument">Command argument</h5> -<div class="paragraph"> -<p>We add an argument to the HelloCommand:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.Action; -import org.apache.karaf.shell.api.action.Argument; -import org.apache.karaf.shell.api.action.Command; -import org.apache.karaf.shell.api.action.Completion; -import org.apache.karaf.shell.api.action.lifecycle.Service; - -@Command(scope = "test", name = "hello", description="Says hello") -@Service -public class HelloShellCommand implements Action { - - @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false) - @Completion(SimpleNameCompleter.class) - String name = null; - - @Override - public Object execute() throws Exception { - System.out.println("Hello " + name); - return null; - } -}</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_completer_bean">Completer bean</h5> -<div class="paragraph"> -<p>A completer is a bean which implements the Completer interface:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.lifecycle.Service; -import org.apache.karaf.shell.api.console.CommandLine; -import org.apache.karaf.shell.api.console.Completer; -import org.apache.karaf.shell.api.console.Session; -import org.apache.karaf.shell.support.completers.StringsCompleter; - -/** - * <p> - * A very simple completer. - * </p> - */ -@Service -public class SimpleNameCompleter implements Completer { - - public int complete(Session session, CommandLine commandLine, List<String> candidates) { - StringsCompleter delegate = new StringsCompleter(); - delegate.getStrings().add("Mike"); - delegate.getStrings().add("Eric"); - delegate.getStrings().add("Jenny"); - return delegate.complete(session, commandLine, candidates); - } - -}</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_completers_for_option_values">Completers for option values</h5> -<div class="paragraph"> -<p>Quite often your commands will not have just arguments, but also options. You can provide completers for option values. -The snippet below shows the HelloShellCommand with an option to specify what the greet message will be.</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.Action; -import org.apache.karaf.shell.api.action.Argument; -import org.apache.karaf.shell.api.action.Command; -import org.apache.karaf.shell.api.action.Completion; -import org.apache.karaf.shell.api.action.Option; -import org.apache.karaf.shell.api.action.lifecycle.Service; - -@Command(scope = "test", name = "hello", description="Says hello") -@Service -public class HelloShellCommand implements Action { - - @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false) - @Completion(SimpleNameCompleter.class) - String name = null; - - @Option(name = "-g", aliases = "--greet", description = "The configuration pid", required = false, multiValued = false) - @Completion(GreetCompleter.class) - String greet = "Hello; - - @Override - public Object execute() throws Exception { - System.out.println(greet + " " + name); - return null; - } -}</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_completers_with_state">Completers with state</h5> -<div class="paragraph"> -<p>Some times we want to tune the behavior of the completer depending on the commands already executed, in the current shell -or even the rest of the arguments that have been already passed to the command. Such example is the config:set-property -command which will provide auto completion for only for the properties of the pid specified by a previously issued config:edit -command or by the option --pid.</p> -</div> -<div class="paragraph"> -<p>The Session object provides map like methods for storing key/value pairs and can be used to put/get the state. -The pre-parsed CommandLine objects allows you to check the previous arguments and options on the command line and to fine tune -the behavior of the Completer. -Those two objects are given to the Completer when calling the <code>complete</code> method.</p> -</div> -</div> -<div class="sect4"> -<h5 id="_test_2">Test</h5> -<div class="paragraph"> -<p>Launch a Karaf instance and run the following command to install the newly created bundle:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT</pre> -</div> -</div> -<div class="paragraph"> -<p>Let’s try running the command:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>karaf@root> test:hello <tab> - one two three</pre> -</div> -</div> +<p>See [examples/karaf-command-example] to add your own shell commands.</p> </div> </div> <div class="sect3"> -<h4 id="_webconsole_4">5.5.2. WebConsole</h4> +<h4 id="_webconsole_4">5.6.2. WebConsole</h4> <div class="paragraph"> <p>You can also extend the Apache Karaf WebConsole by providing and installing a webconsole plugin.</p> </div> <div class="paragraph"> -<p>A plugin is an OSGi bundle that register a Servlet as an OSGi service with some webconsole properties.</p> +<p>A plugin is an OSGi bundle that register a Servlet as an OSGi service with webconsole properties.</p> </div> </div> </div> <div class="sect2"> -<h3 id="_using_the_karaf_maven_plugin">5.6. Using the karaf-maven-plugin</h3> +<h3 id="_using_the_karaf_maven_plugin">5.7. Using the karaf-maven-plugin</h3> <div class="paragraph"> <p>The Karaf Maven plugin allows you:</p> </div> @@ -14986,8 +14630,11 @@ Those two objects are given to the Compl </li> </ul> </div> +<div class="paragraph"> +<p>See [examples/karaf-maven-example] for details.</p> +</div> <div class="sect3"> -<h4 id="_packaging">5.6.1. Packaging</h4> +<h4 id="_packaging">5.7.1. Packaging</h4> <div class="paragraph"> <p>The most generally useful features of the karaf-maven-plugin are exposed as packagings. To use the packagings the pom or an ancestor must configure the karaf-maven-plugin with extensions:</p> </div> @@ -15049,7 +14696,7 @@ Those two objects are given to the Compl </table> </div> <div class="sect3"> -<h4 id="_commands_goals">5.6.2. Commands goals</h4> +<h4 id="_commands_goals">5.7.2. Commands goals</h4> <div class="paragraph"> <p>The <code>karaf-maven-plugin</code> is able to generate documentation for Karaf commands</p> </div> @@ -15133,7 +14780,7 @@ option in the Karaf shell console.</p> </div> </div> <div class="sect3"> -<h4 id="_features_and_kar_goals">5.6.3. Features and kar goals</h4> +<h4 id="_features_and_kar_goals">5.7.3. Features and kar goals</h4> <div class="admonitionblock note"> <table> <tr> @@ -15530,7 +15177,7 @@ META-INF in the kar, without getting ins </div> </div> <div class="sect3"> -<h4 id="_instances_and_distributions_goals">5.6.4. Instances and distributions goals</h4> +<h4 id="_instances_and_distributions_goals">5.7.4. Instances and distributions goals</h4> <div class="admonitionblock note"> <table> <tr> @@ -15656,7 +15303,7 @@ META-INF in the kar, without getting ins </div> </div> <div class="sect3"> -<h4 id="_run_client_deploy_goals">5.6.5. Run, client, deploy goals</h4> +<h4 id="_run_client_deploy_goals">5.7.5. Run, client, deploy goals</h4> <div class="sect4"> <h5 id="__code_karaf_run_code"><code>karaf:run</code></h5> @@ -15672,7 +15319,7 @@ META-INF in the kar, without getting ins </div> </div> <div class="sect2"> -<h3 id="_custom_distributions">5.7. Custom distributions</h3> +<h3 id="_custom_distributions">5.8. Custom distributions</h3> <div class="paragraph"> <p>As Karaf is an OSGi container, it’s heavily used as as application and middleware kernel.</p> </div> @@ -15704,8 +15351,11 @@ META-INF in the kar, without getting ins </li> </ul> </div> +<div class="paragraph"> +<p>See [example/karaf-maven-example/karaf-maven-example-assembly] for a custom distribution example.</p> +</div> <div class="sect3"> -<h4 id="_maven_assembly">5.7.1. Maven assembly</h4> +<h4 id="_maven_assembly">5.8.1. Maven assembly</h4> <div class="paragraph"> <p>The recommended way to create a Karaf server assembly is to use the karaf-assembly packaging with the karaf-maven-plugin. This assembles a server from the maven dependencies in the project pom. After explanation of the configuration options @@ -15951,7 +15601,7 @@ For instance:</p> </div> </div> <div class="sect3"> -<h4 id="__deprecated_old_style_maven_assembly">5.7.2. (deprecated old style) Maven assembly</h4> +<h4 id="__deprecated_old_style_maven_assembly">5.8.2. (deprecated old style) Maven assembly</h4> <div class="paragraph"> <p>Basically a Karaf custom distribution involves:</p> </div> @@ -16329,7 +15979,6 @@ assembly descriptor, configured in POM a <directory>target/dependencies/apache-karaf-${karaf.version}</directory> <outputDirectory>/</outputDirectory> <excludes> - <exclude>**/demos/**</exclude> <exclude>bin/**</exclude> <exclude>etc/system.properties</exclude> <exclude>etc/users.properties</exclude> @@ -16337,8 +15986,8 @@ assembly descriptor, configured in POM a <exclude>etc/org.ops4j.pax.logging.cfg</exclude> <exclude>LICENSE</exclude> <exclude>NOTICE</exclude> - <exclude>README</exclude> - <exclude>RELEASE-NOTES</exclude> + <exclude>README.md</exclude> + <exclude>RELEASE-NOTES.md</exclude> <exclude>karaf-manual*.html</exclude> <exclude>karaf-manual*.pdf</exclude> </excludes> @@ -16419,57 +16068,22 @@ assembly descriptor, configured in POM a </div> </div> <div class="sect2"> -<h3 id="_osgi_services_2">5.8. OSGi Services</h3> - -</div> -<div class="sect2"> -<h3 id="_basic_bundle_creation_using_the_felix_maven_bundle_plugin">5.9. Basic bundle creation using the Felix maven-bundle-plugin</h3> +<h3 id="_creating_bundles">5.9. Creating Bundles</h3> <div class="paragraph"> -<p>Create a bundle instead of a normal jar by using a Maven POM file like this:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><?xml version="1.0" encoding="UTF-8"?> -<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"> - - <modelVersion>4.0.0</modelVersion> - - <groupId>my.groupId</groupId> - <artifactId>my.bundle</artifactId> - <version>1.0-SNAPSHOT</version> - <name>My Bundle</name> - <description>My bundle short description</description> - - <build> - <resources> - <resource> - <directory>${project.basedir}/src/main/resources</directory> - <filtering>true</filtering> - <includes> - <include>**/*</include> - </includes> - </resource> - </resources> - <plugins> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>2.4.0</version> - <extensions>true</extensions> - <configuration> - <instructions> - <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName> - ... - </instructions> - </configuration> - </plugin> - </plugins> - </build> - -</project></pre> +<p>The examples provides different kind of bundles and services definition:</p> </div> +<div class="ulist"> +<ul> +<li> +<p><a href="https://github.com/apache/karaf/examples/karaf-bundle-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-bundle-example/README.md</a></p> +</li> +<li> +<p><a href="https://github.com/apache/karaf/examples/karaf-blueprint-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-blueprint-example/README.md</a></p> +</li> +<li> +<p><a href="https://github.com/apache/karaf/examples/karaf-scr-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-scr-example/README.md</a></p> +</li> +</ul> </div> <div class="sect3"> <h4 id="_add_extended_information_to_bundles">5.9.1. Add extended information to bundles</h4> @@ -16682,27 +16296,27 @@ This bundle is simply a Maven POM that s </div> </div> </div> +<div class="sect3"> +<h4 id="_blueprint">5.10.3. Blueprint</h4> +<div class="paragraph"> +<p>See <a href="https://github.com/apache/example/karaf-blueprint-example/README.md"; class="bare">https://github.com/apache/example/karaf-blueprint-example/README.md</a></p> </div> -<div class="sect2"> -<h3 id="_blueprint">5.11. Blueprint</h3> - </div> -<div class="sect2"> -<h3 id="_declarative_service_ds">5.12. Declarative Service (DS)</h3> - +<div class="sect3"> +<h4 id="_scr">5.10.4. SCR</h4> +<div class="paragraph"> +<p>See <a href="https://github.com/apache/example/karaf-scr-example/README.md"; class="bare">https://github.com/apache/example/karaf-scr-example/README.md</a></p> +</div> </div> -<div class="sect2"> -<h3 id="_cdi_2">5.13. CDI</h3> - </div> <div class="sect2"> -<h3 id="_archetypes">5.14. Archetypes</h3> +<h3 id="_archetypes">5.11. Archetypes</h3> <div class="paragraph"> <p>Karaf provides archetypes to easily create commands, manage features or repository and create a kar archive. This section describes each of them and explain How to use it.</p> </div> <div class="sect3"> -<h4 id="_create_a_command_karaf_command_archetype">5.14.1. Create a command (karaf-command-archetype)</h4> +<h4 id="_create_a_command_karaf_command_archetype">5.11.1. Create a command (karaf-command-archetype)</h4> <div class="paragraph"> <p>This archetype creates a Maven skeleton project that you will use to develop new Karaf commands.</p> </div> @@ -16810,7 +16424,7 @@ scope: my </div> </div> <div class="sect3"> -<h4 id="_create_an_osgi_bundle_karaf_bundle_archetype">5.14.2. Create an OSGi bundle (karaf-bundle-archetype)</h4> +<h4 id="_create_an_osgi_bundle_karaf_bundle_archetype">5.11.2. Create an OSGi bundle (karaf-bundle-archetype)</h4> <div class="paragraph"> <p>This archetype creates a Maven skeleton to create an OSGi bundle, including a bundle Activator (a special callback class for bundle start/stop).</p> @@ -16885,7 +16499,7 @@ package: com.mycompany.package </div> </div> <div class="sect3"> -<h4 id="_create_an_osgi_blueprint_bundle_karaf_blueprint_archetype">5.14.3. Create an OSGi blueprint bundle (karaf-blueprint-archetype)</h4> +<h4 id="_create_an_osgi_blueprint_bundle_karaf_blueprint_archetype">5.11.3. Create an OSGi blueprint bundle (karaf-blueprint-archetype)</h4> <div class="paragraph"> <p>This archetype creates a Maven skeleton project to create an OSGi blueprint bundle, including a sample bean exposed as an OSGi service in the blueprint XML descriptor.</p> @@ -16960,7 +16574,7 @@ package: com.mycompany.package </div> </div> <div class="sect3"> -<h4 id="_create_a_features_xml_karaf_feature_archetype">5.14.4. Create a features XML (karaf-feature-archetype)</h4> +<h4 id="_create_a_features_xml_karaf_feature_archetype">5.11.4. Create a features XML (karaf-feature-archetype)</h4> <div class="paragraph"> <p>This archetype creates a Maven skeleton project which create a features XML file, using the dependencies that you define in the POM.</p> @@ -17035,7 +16649,7 @@ package: com.mycompany.package </div> </div> <div class="sect3"> -<h4 id="_create_a_kar_file_karaf_kar_archetype">5.14.5. Create a KAR file (karaf-kar-archetype)</h4> +<h4 id="_create_a_kar_file_karaf_kar_archetype">5.11.5. Create a KAR file (karaf-kar-archetype)</h4> <div class="paragraph"> <p>This archetype creates a Maven skeleton project including a features XML sample, used to generate a KAR file.</p> </div> @@ -17110,7 +16724,7 @@ package: com.mycompany.package </div> </div> <div class="sect2"> -<h3 id="_security_framework">5.15. Security framework</h3> +<h3 id="_security_framework">5.12. Security framework</h3> <div class="paragraph"> <p>Karaf supports <a href="http://download.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html";>JAAS</a> with some enhancements to allow JAAS to work nicely in an OSGi environment.</p> @@ -17119,7 +16733,7 @@ some enhancements to allow JAAS to work <p>This framework also features an OSGi keystore manager with the ability to deploy new keystores or truststores at runtime.</p> </div> <div class="sect3"> -<h4 id="_overview_2">5.15.1. Overview</h4> +<h4 id="_overview_2">5.12.1. Overview</h4> <div class="paragraph"> <p>This feature allows runtime deployment of JAAS based configuration for use in various parts of the application. This includes the remote console login, which uses the <code>karaf</code> realm, but which is configured with a dummy login module @@ -17135,7 +16749,7 @@ up HTTPS connectors or using certificate </div> </div> <div class="sect3"> -<h4 id="_schema">5.15.2. Schema</h4> +<h4 id="_schema">5.12.2. Schema</h4> <div class="paragraph"> <p>To override or deploy a new realm, you can use the following XSD which is supported by a Spring namespace handler and can thus be defined in a Spring xml configuration file.</p> @@ -17228,7 +16842,7 @@ JMX layer), you need to deploy a JAAS co </div> </div> <div class="sect3"> -<h4 id="_architecture">5.15.3. Architecture</h4> +<h4 id="_architecture">5.12.3. Architecture</h4> <div class="paragraph"> <p>Due to constraints in the JAAS specification, one class has to be available for all bundles. This class is called ProxyLoginModule and is a LoginModule that acts as a proxy for an OSGi defines LoginModule. @@ -17254,7 +16868,7 @@ Some login modules (for security reason </div> </div> <div class="sect3"> -<h4 id="_available_realm_and_login_modules">5.15.4. Available realm and login modules</h4> +<h4 id="_available_realm_and_login_modules">5.12.4. Available realm and login modules</h4> <div class="paragraph"> <p>Karaf comes with a default realm named "karaf" using login modules.</p> </div> @@ -18072,7 +17686,7 @@ users and roles directly from Karaf. To </div> </div> <div class="sect3"> -<h4 id="_encryption_service">5.15.5. Encryption service</h4> +<h4 id="_encryption_service">5.12.5. Encryption service</h4> <div class="paragraph"> <p>The EncryptionService is a service registered in the OSGi registry providing means to encrypt and check encrypted passwords. This service acts as a factory for Encryption objects actually performing the encryption.</p> @@ -18309,7 +17923,7 @@ Jasypt documentation (<a href="http://ww </div> </div> <div class="sect3"> -<h4 id="_role_discovery_policies">5.15.6. Role discovery policies</h4> +<h4 id="_role_discovery_policies">5.12.6. Role discovery policies</h4> <div class="paragraph"> <p>The JAAS specification does not provide means to distinguish between User and Role Principals without referring to the specification classes. In order to provide means to the application developer to decouple the application from Karaf @@ -18397,7 +18011,7 @@ for (Principal p : subject.getPrincipals </div> </div> <div class="sect3"> -<h4 id="_default_role_policies">5.15.7. Default role policies</h4> +<h4 id="_default_role_policies">5.12.7. Default role policies</h4> <div class="paragraph"> <p>The previous section describes how to leverage role policies. However, Karaf provides a default role policy, based on the following class names:</p> </div> @@ -18431,9 +18045,9 @@ for (Principal p : subject.getPrincipals </div> </div> <div class="sect2"> -<h3 id="_troubleshooting_debugging_profiling_and_monitoring">5.16. Troubleshooting, Debugging, Profiling, and Monitoring</h3> +<h3 id="_troubleshooting_debugging_profiling_and_monitoring">5.13. Troubleshooting, Debugging, Profiling, and Monitoring</h3> <div class="sect3"> -<h4 id="_troubleshooting">5.16.1. Troubleshooting</h4> +<h4 id="_troubleshooting">5.13.1. Troubleshooting</h4> <div class="sect4"> <h5 id="_logging">Logging</h5> <div class="paragraph"> @@ -18477,7 +18091,7 @@ is started the first time.</p> </div> </div> <div class="sect3"> -<h4 id="_debugging">5.16.2. Debugging</h4> +<h4 id="_debugging">5.13.2. Debugging</h4> <div class="paragraph"> <p>Usually, the easiest way to debug Karaf or any application deployed onto it is to use remote debugging. Remote debugging can be easily activated by using the <code>debug</code> parameter on the command line.</p> @@ -18594,7 +18208,7 @@ how early in the startup they are.</p> </div> </div> <div class="sect3"> -<h4 id="_profiling">5.16.3. Profiling</h4> +<h4 id="_profiling">5.13.3. Profiling</h4> <div class="sect4"> <h5 id="_jvisualvm">jVisualVM</h5> <div class="paragraph"> @@ -18644,7 +18258,7 @@ how early in the startup they are.</p> </div> </div> <div class="sect3"> -<h4 id="_monitoring">5.16.4. Monitoring</h4> +<h4 id="_monitoring">5.13.4. Monitoring</h4> <div class="paragraph"> <p>Karaf uses JMX for monitoring and management of all Karaf components.</p> </div> @@ -18727,452 +18341,99 @@ allowing you to create, rename, destroy, </div> </div> <div class="sect2"> -<h3 id="_writing_integration_tests">5.17. Writing integration tests</h3> -<div class="paragraph"> -<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> -</div> +<h3 id="_writing_integration_tests">5.14. Writing integration tests</h3> <div class="paragraph"> -<p>Starting with Karaf 3.0 we’ve also included a component briding between Karaf and Pax Exam making it easier to write integration tests -for Karaf or Karaf based distributions.</p> -</div> -<div class="sect3"> -<h4 id="_introduction">5.17.1. Introduction</h4> -<div class="paragraph"> -<p>Pax Exam directly supports Karaf as a test container.</p> -</div> -<div class="paragraph"> -<p>To make use of this new framework simply add the following dependencies into your integration tests pom.xml:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><dependency> - <groupId>org.ops4j.pax.exam</groupId> - <artifactId>pax-exam-container-karaf</artifactId> - <version>4.7.0</version> - <scope>test</scope> -</dependency> -<dependency> - <groupId>org.ops4j.pax.exam</groupId> - <artifactId>pax-exam-junit4</artifactId> - <version>4.7.0</version> - <scope>test</scope> -</dependency> -<dependency> - <groupId>org.apache.geronimo.specs</groupId> - <artifactId>geronimo-atinject-1.0_spec</artifactId> - <version>1.0</version> - <scope>test</scope> -</dependency></pre> -</div> -</div> -<div class="paragraph"> -<p>As a next step you need to reference the distribution you want to run your tests on. -For instance, if you want to run your tests on Karaf the following section would be required in the integration tests pom.xml:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><dependency> - <groupId>org.apache.karaf</groupId> - <artifactId>apache-karaf</artifactId> - <version>4.0.0</version> - <type>tar.gz</type> - <scope>test</scope> -</dependency></pre> -</div> -</div> -<div class="paragraph"> -<p>If you want to make use of Exams "versionAsInProject" feature you also need to add the following section:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre><build> - <plugins> - <plugin> - <groupId>org.apache.servicemix.tooling</groupId> - <artifactId>depends-maven-plugin</artifactId> - <version>1.2</version> - <executions> - <execution> - <id>generate-depends-file</id> - <goals> - <goal>generate-depends-file</goal> - </goals> - </execution> - </executions> - </plugin> - </plugins> -</build></pre> +<p>See [examples/karaf-itest-example/README.md]</p> </div> </div> +<div class="sect2"> +<h3 id="_dump_extender">5.15. Dump extender</h3> <div class="paragraph"> -<p>With this done we can start writing our first test case:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>import static junit.framework.Assert.assertTrue; -import static org.ops4j.pax.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("tar.gz").versionAsInProject()) - .karafVersion("4.0.0").name("Apache Karaf")}; - } - - @Test - public void test() throws Exception { - assertTrue(true); - } -}</pre> -</div> -</div> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-dump-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-dump-example/README.md</a></p> </div> <div class="sect3"> -<h4 id="_commands_11">5.17.2. Commands</h4> -<div class="sect4"> -<h5 id="_karafdistributionconfigurationoption">KarafDistributionConfigurationOption</h5> -<div class="paragraph"> -<p>The framework itself is non of the typical runtimes you define normally in Pax-Exam.</p> -</div> -<div class="paragraph"> -<p>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> -<div class="listingblock"> -<div class="content"> -<pre>new KarafDistributionConfigurationOption( - "mvn:org.apache.karaf/apache-karaf/4.0.0/zip", // artifact to unpack and use - "karaf", // name; display only - "4.0.0") // the karaf version; this one is relevant since the startup script differs between versions</pre> -</div> -</div> -<div class="paragraph"> -<p>or for Servicemix e.g.</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>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</pre> -</div> -</div> -<div class="paragraph"> -<p>As an alternative you can also use the maven url resolvers.</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>... -<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></pre> -</div> -</div> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration - public Option[] config() { - return new Option[]{ karafDistributionConfiguration().frameworkUrl( - maven().groupId("org.apache.karaf").artifactId("apache-karaf").type("zip") - .classifier("bin").versionAsInProject()) }; - }</pre> -</div> -</div> -<div class="paragraph"> -<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> -</div> -<div class="sect5"> -<h6 id="_unpack_directory">Unpack Directory</h6> +<h4 id="_jdbc_jpa">5.15.1. JDBC & JPA</h4> <div class="paragraph"> -<p>Pax-Exam 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> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip") - .unpackDirectory(new File("target/paxexam/unpack/")) }; -}</pre> -</div> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-jdbc-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-jdbc-example/README.md</a></p> </div> -</div> -<div class="sect5"> -<h6 id="_use_deploy_folder">Use Deploy Folder</h6> <div class="paragraph"> -<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 <code>etc/org.apache.karaf.features.cfg</code>) for those deploys. To use it instead of the deploy folder simply do the following:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip") - .useDeployFolder(false)) }; -}</pre> -</div> -</div> -</div> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-jpa-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-jpa-example/README.md</a></p> </div> -<div class="sect4"> -<h5 id="_karafdistributionkitconfigurationoption">KarafDistributionKitConfigurationOption</h5> -<div class="paragraph"> -<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> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ - new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/4.0.0/zip", - Platform.WINDOWS).executable("bin\\karaf.bat").filesToMakeExecutable("bin\\admin.bat"), - new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/4.0.0/tar.gz", "karaf", - Platform.NIX).executable("bin/karaf").filesToMakeExecutable("bin/admin") }; -}</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_karafdistributionconfigurationfileputoption">KarafDistributionConfigurationFilePutOption</h5> -<div class="paragraph"> -<p>The option replaces or adds an option to one of Karaf’s configuration files:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>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</pre> </div> -</div> -<div class="paragraph"> -<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> -</div> -</div> -<div class="sect4"> -<h5 id="_karafdistributionconfigurationfileextendoption">KarafDistributionConfigurationFileExtendOption</h5> -<div class="paragraph"> -<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> -</div> -<div class="paragraph"> -<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> -</div> -</div> -<div class="sect4"> -<h5 id="_karafdistributionconfigurationfilereplacementoption">KarafDistributionConfigurationFileReplacementOption</h5> -<div class="paragraph"> -<p>The file replacement option allows you to simply replace a file in you Karaf distribution with a different file:</p> -</div> -<div class="listingblock"> -<div class="content"> -<pre>new KarafDistributionConfigurationFileReplacementOption("etc/tests.cfg", new File( - "src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey"));</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_provisionoption">ProvisionOption</h5> -<div class="paragraph"> -<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> -</div> -</div> -<div class="sect4"> -<h5 id="_karafdistributionconfigurationconsoleoption">KarafDistributionConfigurationConsoleOption</h5> -<div class="paragraph"> -<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> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), - configureConsole().ignoreLocalConsole().startRemoteShell() }; -}</pre> -</div> -</div> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), - configureConsole().startLocalConsole(), configureConsole().ignoreRemoteShell() }; -}</pre> -</div> -</div> -</div> -<div class="sect4"> -<h5 id="_vmoption">VMOption</h5> -<div class="paragraph"> -<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> -</div> -</div> -<div class="sect4"> -<h5 id="_logleveloption">LogLevelOption</h5> +<div class="sect3"> +<h4 id="_jms_2">5.15.2. JMS</h4> <div class="paragraph"> -<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> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-jms-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-jms-example/README.md</a></p> </div> -<div class="listingblock"> -<div class="content"> -<pre>import static org.openengsb.labs.paxexam.karaf.options.KarafDistributionOption.logLevel; -... -@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), - logLevel(LogLevel.TRACE) }; -}</pre> </div> -</div> -</div> -<div class="sect4"> -<h5 id="_donotmodifylogoption">DoNotModifyLogOption</h5> +<div class="sect3"> +<h4 id="_custom_log_appender">5.15.3. Custom log appender</h4> <div class="paragraph"> -<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> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-log-appender-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-log-appender-example/README.md</a></p> </div> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), - doNotModifyLogConfiguration() }; -}</pre> </div> -</div> -</div> -<div class="sect4"> -<h5 id="_keepruntimefolderoption">KeepRuntimeFolderOption</h5> +<div class="sect3"> +<h4 id="_custom_jmx_mbean">5.15.4. Custom JMX MBean</h4> <div class="paragraph"> -<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> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-mbean-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-mbean-example/README.md</a></p> </div> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), - keepRuntimeFolder() }; -}</pre> </div> -</div> -</div> -<div class="sect4"> -<h5 id="_featuresscannerprovisionoption">FeaturesScannerProvisionOption</h5> +<div class="sect3"> +<h4 id="_working_with_profiles">5.15.5. Working with profiles</h4> <div class="paragraph"> -<p>The FeaturesScannerProvisionOption (e.g. CoreOption.scanFeature()) are directly supported by the Paxexam Karaf Testframework.</p> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-profile-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-profile-example/README.md</a></p> </div> </div> -<div class="sect4"> -<h5 id="_bootdelegationoption">BootDelegationOption</h5> +<div class="sect3"> +<h4 id="_servlet">5.15.6. Servlet</h4> <div class="paragraph"> -<p>The BootDelegationOption as known from PaxExam is also supported added the boot delegation string directly into the correct property files.</p> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-servlet-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-servlet-example/README.md</a></p> </div> </div> -<div class="sect4"> -<h5 id="_systempackageoption">SystemPackageOption</h5> +<div class="sect3"> +<h4 id="_war">5.15.7. WAR</h4> <div class="paragraph"> -<p>The Standard Exam SystemPackageOption is implemented by adding those packages to "org.osgi.framework.system.packages.extra" of the config.properties file.</p> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-war-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-war-example/README.md</a></p> </div> </div> -<div class="sect4"> -<h5 id="_bootclasspathlibraryoption">BootClasspathLibraryOption</h5> +<div class="sect3"> +<h4 id="_rest_service">5.15.8. REST service</h4> <div class="paragraph"> -<p>The BootClasspathLibraryOption is honored by copying the urls into the lib directory where they are automatically taken and worked on.</p> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-rest-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-rest-example/README.md</a></p> </div> </div> -<div class="sect4"> -<h5 id="_exambundlesstartlevel">ExamBundlesStartLevel</h5> +<div class="sect3"> +<h4 id="_soap_service">5.15.9. SOAP service</h4> <div class="paragraph"> -<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> -<div class="listingblock"> -<div class="content"> -<pre>@Configuration -public Option[] config() { - return new Option[]{ karafDistributionConfiguration("mvn:org.apache.karaf/apache-karaf/4.0.0/zip"), - useOwnExamBundlesStartLevel(4) }; -}</pre> -</div> -</div> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-soap-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-soap-example/README.md</a></p> </div> </div> <div class="sect3"> -<h4 id="_driver">5.17.3. Driver</h4> -<div class="paragraph"> -<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> -</div> -<div class="sect4"> -<h5 id="_javarunner">JavaRunner</h5> +<h4 id="_scheduling_jobs">5.15.10. Scheduling jobs</h4> <div class="paragraph"> -<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> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-scheduler-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-scheduler-example/README.md</a></p> </div> </div> -<div class="sect4"> -<h5 id="_scriptrunner">ScriptRunner</h5> +<div class="sect3"> +<h4 id="_custom_url_handler">5.15.11. Custom URL handler</h4> <div class="paragraph"> -<p>The script runner has the disadvantage over the java runner that it is also platform dependent. -The advantage though is that you can also test your specific scripts. To use it follow the explanation of the KarafDistributionKitConfigurationOption in the Commands section.</p> -</div> +<p>See <a href="https://github.com/apache/karaf/examples/karaf-url-namespace-handler-example/README.md"; class="bare">https://github.com/apache/karaf/examples/karaf-url-namespace-handler-example/README.md</a></p> </div> </div> </div> <div class="sect2"> -<h3 id="_github_contributions">5.18. Github Contributions</h3> +<h3 id="_github_contributions">5.16. Github Contributions</h3> <div class="paragraph"> <p>Some people prefer to make contributions to karaf source via github. If you are one of them, this is for you!</p> </div> <div class="sect3"> -<h4 id="_introduction_2">5.18.1. Introduction</h4> +<h4 id="_introduction">5.16.1. Introduction</h4> <div class="paragraph"> <p>Apache Karaf is available as a periodically replicated mirror on: <a href="https://github.com/apache/karaf"; class="bare">https://github.com/apache/karaf</a></p> </div> </div> <div class="sect3"> -<h4 id="_suggested_workflow">5.18.2. Suggested Workflow</h4> +<h4 id="_suggested_workflow">5.16.2. Suggested Workflow</h4> <div class="olist arabic"> <ol class="arabic"> <li> @@ -19200,7 +18461,7 @@ The advantage though is that you can als </div> </div> <div class="sect3"> -<h4 id="_license_reminder">5.18.3. License Reminder</h4> +<h4 id="_license_reminder">5.16.3. License Reminder</h4> <div class="paragraph"> <p>In order for your contributions to be accepted:</p> </div> @@ -19216,7 +18477,7 @@ The advantage though is that you can als </div> </div> <div class="sect3"> -<h4 id="_how_to_generate_a_one_file_patch_via_throw_away_branch">5.18.4. How to Generate a One-File-Patch Via Throw-Away Branch</h4> +<h4 id="_how_to_generate_a_one_file_patch_via_throw_away_branch">5.16.4. How to Generate a One-File-Patch Via Throw-Away Branch</h4> <div class="paragraph"> <p>Here is one way to generate squash of your commits:</p> </div> @@ -19268,7 +18529,7 @@ git format-patch archon/trunk</pre> </div> <div id="footer"> <div id="footer-text"> -Last updated 2017-08-09 13:23:59 +02:00 +Last updated 2018-08-17 21:42:57 +02:00 </div> </div> </body>
Modified: karaf/site/production/manual/latest/installation.html URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest/installation.html?rev=1839907&r1=1839906&r2=1839907&view=diff ============================================================================== --- karaf/site/production/manual/latest/installation.html (original) +++ karaf/site/production/manual/latest/installation.html Mon Sep 3 06:10:48 2018 @@ -697,6 +697,59 @@ tar xvf apache-karaf-4.0.0.tar</pre> </tr> </table> </div> +<div class="sect5"> +<h6 id="_installation_on_debian_gnu_linux">Installation on Debian GNU/linux</h6> +<div class="paragraph"> +<p>There is an unofficial debian package of karaf:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p>Add the key of the unofficial debian archive containing karaf</p> +<div class="listingblock"> +<div class="content"> +<pre>wget -O - https://apt.bang.priv.no/apt_pub.gpg | apt-key add -</pre> +</div> +</div> +</li> +<li> +<p>Open /etc/apt/sources.list in a text editor and add the following lines:</p> +<div class="listingblock"> +<div class="content"> +<pre># Unofficial APT archive for apache karaf +deb http://apt.bang.priv.no/public stable main</pre> +</div> +</div> +</li> +<li> +<p>Update the APT package index and install the package</p> +<div class="listingblock"> +<div class="content"> +<pre>apt-get update +apt-get install openjdk-8-jdk karaf</pre> +</div> +</div> +</li> +</ol> +</div> +<div class="paragraph"> +<p>The installed karaf will run as user karaf, group karaf, listening to the usual default karaf ports, be started with systemd, with KARAF_ETC in /etc/karaf and KARAF_DATA in /var/lib/karaf/data.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +<div class="paragraph"> +<p>When/if the <a href="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=881297";>Debian Request For Package (RFP) of karaf</a> results in an official karaf package becoming available, the unofficial debian package will be discontinued.</p> +</div> +</td> +</tr> +</table> +</div> +</div> </div> </div> <div class="sect3"> @@ -860,7 +913,7 @@ This property is used to locate the <cod </div> <div id="footer"> <div id="footer-text"> -Last updated 2017-07-26 16:36:29 +02:00 +Last updated 2018-08-17 21:42:57 +02:00 </div> </div> </body>
