Use article format for documentation
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/c806a6ad Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/c806a6ad Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/c806a6ad Branch: refs/heads/master Commit: c806a6ad43bb777228bc4ce72b39fb1f4e3f2ed5 Parents: 3d646d6 Author: Jean-Baptiste Onofré <[email protected]> Authored: Mon Jan 4 17:53:27 2016 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Mon Jan 4 17:53:27 2016 +0100 ---------------------------------------------------------------------- manual/pom.xml | 4 +- .../asciidoc/developer-guide/archetypes.adoc | 34 +- .../asciidoc/developer-guide/blueprint.adoc | 2 +- .../main/asciidoc/developer-guide/branding.adoc | 12 +- .../main/asciidoc/developer-guide/connect.adoc | 6 +- .../developer-guide/creating-bundles.adoc | 12 +- .../developer-guide/custom-distribution.adoc | 14 +- .../asciidoc/developer-guide/debugging.adoc | 20 +- .../main/asciidoc/developer-guide/dev-cdi.adoc | 2 +- .../developer-guide/developer-commands.adoc | 21 +- .../src/main/asciidoc/developer-guide/ds.adoc | 2 +- .../asciidoc/developer-guide/extending.adoc | 36 +- .../developer-guide/github-contributions.adoc | 10 +- .../developer-guide/karaf-maven-plugin.adoc | 56 +- .../asciidoc/developer-guide/scripting.adoc | 26 +- .../developer-guide/security-framework.adoc | 36 +- .../main/asciidoc/developer-guide/services.adoc | 2 +- .../asciidoc/developer-guide/writing-tests.adoc | 48 +- manual/src/main/asciidoc/index.adoc | 14 +- manual/src/main/asciidoc/overview.adoc | 2 + manual/src/main/asciidoc/quick-start.adoc | 18 +- manual/src/main/asciidoc/update-notes.adoc | 26 +- manual/src/main/asciidoc/user-guide/cdi.adoc | 10 +- .../asciidoc/user-guide/configugration.adoc | 30 +- .../src/main/asciidoc/user-guide/console.adoc | 24 +- .../src/main/asciidoc/user-guide/deployers.adoc | 14 +- .../user-guide/directory-structure.adoc | 2 +- manual/src/main/asciidoc/user-guide/ejb.adoc | 6 +- .../src/main/asciidoc/user-guide/failover.adoc | 22 +- manual/src/main/asciidoc/user-guide/http.adoc | 10 +- .../main/asciidoc/user-guide/installation.adoc | 48 +- .../src/main/asciidoc/user-guide/instances.adoc | 34 +- manual/src/main/asciidoc/user-guide/jdbc.adoc | 24 +- manual/src/main/asciidoc/user-guide/jms.adoc | 32 +- manual/src/main/asciidoc/user-guide/jndi.adoc | 28 +- manual/src/main/asciidoc/user-guide/jpa.adoc | 4 +- manual/src/main/asciidoc/user-guide/jta.adoc | 6 +- manual/src/main/asciidoc/user-guide/kar.adoc | 22 +- manual/src/main/asciidoc/user-guide/log.adoc | 42 +- .../main/asciidoc/user-guide/monitoring.adoc | 14 +- manual/src/main/asciidoc/user-guide/obr.adoc | 36 +- .../main/asciidoc/user-guide/provisioning.adoc | 60 +- manual/src/main/asciidoc/user-guide/remote.adoc | 24 +- .../src/main/asciidoc/user-guide/security.adoc | 50 +- .../main/asciidoc/user-guide/start-stop.adoc | 24 +- manual/src/main/asciidoc/user-guide/tuning.adoc | 18 +- manual/src/main/asciidoc/user-guide/urls.adoc | 4 +- .../main/asciidoc/user-guide/webconsole.adoc | 6 +- .../main/asciidoc/user-guide/webcontainer.adoc | 30 +- .../src/main/asciidoc/user-guide/wrapper.adoc | 14 +- .../main/asciidoc/users-guide/provisioning.adoc | 600 ------------------- 51 files changed, 533 insertions(+), 1108 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/pom.xml ---------------------------------------------------------------------- diff --git a/manual/pom.xml b/manual/pom.xml index 90fccc8..b48928f 100644 --- a/manual/pom.xml +++ b/manual/pom.xml @@ -214,10 +214,10 @@ <configuration> <sourceHighlighter>coderay</sourceHighlighter> <backend>html5</backend> + <doctype>article</doctype> <attributes> <toc /> <linkcss>false</linkcss> - <doctype>book</doctype> </attributes> </configuration> </execution> @@ -225,7 +225,7 @@ <configuration> <sourceDirectory>src/main/asciidoc</sourceDirectory> <headerFooter>true</headerFooter> - <imagesDir>../resources/images</imagesDir> + <imagesDir>src/main/asciidoc/images</imagesDir> </configuration> </plugin> <plugin> http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/archetypes.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/archetypes.adoc b/manual/src/main/asciidoc/developer-guide/archetypes.adoc index 3584338..734f365 100644 --- a/manual/src/main/asciidoc/developer-guide/archetypes.adoc +++ b/manual/src/main/asciidoc/developer-guide/archetypes.adoc @@ -12,16 +12,16 @@ // limitations under the License. // -== Archetypes +=== Archetypes 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. -=== Create a command (karaf-command-archetype) +==== Create a command (karaf-command-archetype) This archetype creates a Maven skeleton project that you will use to develop new Karaf commands. -==== Command line +===== Command line Using the command line, we can create our project: @@ -36,7 +36,7 @@ mvn archetype:generate \ -Dpackage=com.mycompany.package ---- -==== Additional parameters +===== Additional parameters During the maven creation process, additional questions will be asked on the console : @@ -46,7 +46,7 @@ This description will be displayed in the Karaf console when the parameter --hel * Define value for property 'scope': this value represents the family name to which the command belongs (features, osgi, admin, jaas, ...) -==== Result of Maven command execution +===== Result of Maven command execution ---- [INFO] Scanning for projects... @@ -106,12 +106,12 @@ scope: my Next, you can import your project in Eclipse/IntelliJ and developp the Karaf command. -=== Create an OSGi bundle (karaf-bundle-archetype) +==== Create an OSGi bundle (karaf-bundle-archetype) This archetype creates a Maven skeleton to create an OSGi bundle, including a bundle Activator (a special callback class for bundle start/stop). -==== Command line +===== Command line Using the command line, we can create our project: @@ -126,7 +126,7 @@ mvn archetype:generate \ -Dpackage=com.mycompany.package ---- -==== Result of Maven command execution +===== Result of Maven command execution ---- [INFO] Scanning for projects... @@ -174,12 +174,12 @@ package: com.mycompany.package [INFO] ------------------------------------------------------------------------ ---- -=== Create an OSGi blueprint bundle (karaf-blueprint-archetype) +==== Create an OSGi blueprint bundle (karaf-blueprint-archetype) 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. -==== Command line +===== Command line Using the command line, we can create our project: @@ -194,7 +194,7 @@ mvn archetype:generate \ -Dpackage=com.mycompany.blueprint ---- -==== Result of Maven command execution +===== Result of Maven command execution ---- [INFO] Scanning for projects... @@ -242,12 +242,12 @@ package: com.mycompany.package [INFO] ------------------------------------------------------------------------ ---- -=== Create a features XML (karaf-feature-archetype) +==== Create a features XML (karaf-feature-archetype) This archetype creates a Maven skeleton project which create a features XML file, using the dependencies that you define in the POM. -==== Command line +===== Command line Using the command line, we can create our project: @@ -262,7 +262,7 @@ mvn archetype:generate \ -Dpackage=my.company.package ---- -==== Result of maven command execution +===== Result of maven command execution ---- [INFO] Scanning for projects... @@ -310,11 +310,11 @@ package: com.mycompany.package [INFO] ------------------------------------------------------------------------ ---- -=== Create a KAR file (karaf-kar-archetype) +==== Create a KAR file (karaf-kar-archetype) This archetype creates a Maven skeleton project including a features XML sample, used to generate a KAR file. -==== Command line +===== Command line Using the command line, we can create our project: @@ -329,7 +329,7 @@ mvn archetype:generate \ -Dpackage=com.mycompany.package ---- -==== Result of maven command execution +===== Result of maven command execution ---- [INFO] Scanning for projects... http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/blueprint.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/blueprint.adoc b/manual/src/main/asciidoc/developer-guide/blueprint.adoc index 88abccc..8ca2caf 100644 --- a/manual/src/main/asciidoc/developer-guide/blueprint.adoc +++ b/manual/src/main/asciidoc/developer-guide/blueprint.adoc @@ -12,4 +12,4 @@ // limitations under the License. // -== Blueprint \ No newline at end of file +=== Blueprint \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/branding.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/branding.adoc b/manual/src/main/asciidoc/developer-guide/branding.adoc index da2cff8..2abf408 100644 --- a/manual/src/main/asciidoc/developer-guide/branding.adoc +++ b/manual/src/main/asciidoc/developer-guide/branding.adoc @@ -12,9 +12,9 @@ // limitations under the License. // -== Branding +=== Branding -=== Console +==== Console You can "brand" the Apache Karaf console. @@ -28,7 +28,7 @@ There are 2 ways of branding the Karaf console: . adding a branding.properties file to etc . creating a branding bundle. -=== Adding a branding.properties file to etc +==== Adding a branding.properties file to etc Create a `etc/branding.properties` file similar to: @@ -51,7 +51,7 @@ prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m> Start Karaf and you will see your branded Karaf console. -=== Branding bundle +==== Branding bundle At startup, Apache Karaf is looking for a bundle which exports the `org.apache.karaf.branding` package, containing a `branding.properties` file. @@ -147,7 +147,7 @@ prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICAT prompt = my-user@my-karaf> ---- -=== Installing the branding bundle +==== Installing the branding bundle Thanks to the `pom.xml`, we can use `mvn` to build the branding bundle: @@ -163,7 +163,7 @@ cp branding.jar /opt/apache-karaf-4.0.0/lib/karaf-branding.jar You can now start Apache Karaf to see your branded console. -=== WebConsole +==== WebConsole It's also possible to brand the Apache Karaf WebConsole. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/connect.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/connect.adoc b/manual/src/main/asciidoc/developer-guide/connect.adoc index 98881bf..42bc771 100644 --- a/manual/src/main/asciidoc/developer-guide/connect.adoc +++ b/manual/src/main/asciidoc/developer-guide/connect.adoc @@ -12,12 +12,12 @@ // limitations under the License. // -== Programmatically connect +=== Programmatically connect As described in the users guide, Apache Karaf supports remote access to both the console (by embedding a SSHd server) and the management layer. -=== To the console +==== To the console You can write a Apache Karaf remote console client in Java (or other language). @@ -70,7 +70,7 @@ public class Main { } ---- -=== To the management layer +==== To the management layer The Apache Karaf management layer uses JMX. Apache Karaf embeds a JMX MBeanServer that you can use remotely. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc b/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc index 2388968..1838f21 100644 --- a/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc +++ b/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Basic bundle creation using the Felix maven-bundle-plugin +=== Basic bundle creation using the Felix maven-bundle-plugin Create a bundle instead of a normal jar by using a Maven POM file like this: @@ -59,7 +59,7 @@ Create a bundle instead of a normal jar by using a Maven POM file like this: </project> ---- -=== Add extended information to bundles +==== Add extended information to bundles Karaf supports a OSGI-INF/bundle.info file in a bundle. This file is extended description of the bundle. @@ -85,7 +85,7 @@ You can display this extended information using: root@karaf> bundles:info ---- -=== Wiki Syntax +==== Wiki Syntax Karaf supports some simple wiki syntax in bundle info files: @@ -95,9 +95,9 @@ Karaf supports some simple wiki syntax in bundle info files: [http://....] : links ---- -== Creating bundles for non OSGi third party dependencies +=== Creating bundles for non OSGi third party dependencies -=== Dynamically wrapping jars +==== Dynamically wrapping jars Karaf supports the wrap: protocol execution. @@ -121,7 +121,7 @@ root@karaf> bundles:install 'wrap:mvn:commons-lang/commons-lang/2.4$Bundle-Symbo <bundle>wrap:mvn:commons-lang/commons-lang/2.4$Bundle-SymbolicName=commons-lang&Bundle-Version=2.4</bundle> ---- -=== Statically bundling jars +==== Statically bundling jars You can also create a wrap bundle for a third party dependency. This bundle is simply a Maven POM that shades an existing jar and package into a jar bundle. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc b/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc index 8a6eb83..fb6d086 100644 --- a/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc +++ b/manual/src/main/asciidoc/developer-guide/custom-distribution.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Custom distributions +=== Custom distributions As Karaf is an OSGi container, it's heavily used as as application and middleware kernel. @@ -27,7 +27,7 @@ This custom distribution could contain: * renamed or specific scripts in the bin folder * system documentation files -=== Maven assembly +==== Maven assembly 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 @@ -39,7 +39,7 @@ limitations we have to simulate rather than use the karaf-assembly packaging. This packaging creates tar.gz and zip archives containing the assembled server. They are identical except that zip archives don't unpack with appropriate unix file permissions for the scripts. -==== Maven dependencies +===== Maven dependencies Maven dependencies in a karaf-assembly project can be feature repositories (classifier "features") or kar archives. Feature repositories are installed in the internal "system" Maven structured repository. @@ -53,7 +53,7 @@ configuration file `etc/org.apache.karaf.features.cfg` `featuresRepositories` pr * runtime: feature installation is controlled by `<startupFeature>`, `<bootFeature>`, and `<installedFeature>` elements in the karaf-maven-plugin configuration. The feature repo uri is listed in the features service configuration file. -==== Plugin configuration +===== Plugin configuration Control how features are installed using these elements referring to features from installed feature repositories: @@ -67,7 +67,7 @@ You can use feature_name or feature_name/feature_version formats. the "system" internal repository. Therefore at runtime the feature may be installed without access to external repositories. You can use feature_name or feature_name/feature_version formats. -==== Minimal Distribution Example +===== Minimal Distribution Example This is the minimal assembly pom changed to use the packaging and annotated @@ -156,7 +156,7 @@ This is the minimal assembly pom changed to use the packaging and annotated </project> ---- -==== Custom Distribution Example +===== Custom Distribution Example It's possible to specify feature versions using the name/version format. @@ -254,7 +254,7 @@ For instance, to pre-install Spring 4.0.7.RELEASE_1 feature in your custom distr </project> ---- -=== (deprecated old style) Maven assembly +==== (deprecated old style) Maven assembly Basically a Karaf custom distribution involves: http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/debugging.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/debugging.adoc b/manual/src/main/asciidoc/developer-guide/debugging.adoc index 1664438..bbba176 100644 --- a/manual/src/main/asciidoc/developer-guide/debugging.adoc +++ b/manual/src/main/asciidoc/developer-guide/debugging.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== Troubleshooting, Debugging, Profiling, and Monitoring +=== Troubleshooting, Debugging, Profiling, and Monitoring -=== Troubleshooting +==== Troubleshooting -==== Logging +===== Logging Logging is easy to control through the console, with commands grouped under _log_ shell. To learn about the available logging commands type: @@ -34,7 +34,7 @@ Typical usage is: . Execute the problematic operation . Use `log:display` (or `log:display-exception` to display the log -==== Worst Case Scenario +===== Worst Case Scenario 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 `data` directory just in the installation directory. This folder @@ -42,7 +42,7 @@ contains transient data and will be recreated if removed when you relaunch Karaf You may also want to remove the files in the `deploy` folder to avoid them being automatically installed when Karaf is started the first time. -=== Debugging +==== Debugging 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 `debug` parameter on the command line. @@ -101,7 +101,7 @@ and on Windows, set DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' ---- -==== Debugging Environment Variables +===== Debugging Environment Variables |=== |Variable |Description |Default @@ -123,9 +123,9 @@ set DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:tr |5005 |=== -=== Profiling +==== Profiling -==== jVisualVM +===== jVisualVM You have to edit the `etc/config.properties` configuration file to add the jVisualVM package: @@ -135,7 +135,7 @@ org.osgi.framework.bootdelegation=...,org.netbeans.lib.profiler.server Run Karaf from the console, and you should now be able to connect using jVisualVM. -==== YourKit +===== YourKit You need a few steps to be able to profile Karaf using YourKit. @@ -159,7 +159,7 @@ set JAVA_OPTS='-Xmx512M -agentlib:yjpagent' Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE. -=== Monitoring +==== Monitoring Karaf uses JMX for monitoring and management of all Karaf components. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc b/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc index f41d8e4..9e64e35 100644 --- a/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc +++ b/manual/src/main/asciidoc/developer-guide/dev-cdi.adoc @@ -12,4 +12,4 @@ // limitations under the License. // -== CDI \ No newline at end of file +=== CDI \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/developer-commands.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/developer-commands.adoc b/manual/src/main/asciidoc/developer-guide/developer-commands.adoc index 18437b4..f4a6cec 100644 --- a/manual/src/main/asciidoc/developer-guide/developer-commands.adoc +++ b/manual/src/main/asciidoc/developer-guide/developer-commands.adoc @@ -12,14 +12,14 @@ // limitations under the License. // -== Developer commands +=== Developer commands As you can see in the users guide, Apache Karaf is an enterprise ready OSGi container. It's also a container designed to simplify the life for developers and administrators to get details about the running container. -=== Dump +==== Dump If you encounter issues like performance degradations, weird behaviour, it could be helpful to have a kind of snapshot about the current activity of the container. @@ -65,7 +65,7 @@ karaf@root()> dev:dump-create -d /tmp/mydump Diagnostic dump created. ---- -=== Diagnostic +==== Diagnostic It's not always easy for the developers to understand why a bundle is not active. @@ -108,7 +108,7 @@ Unsatisfied Requirements: [81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.resource)(version>=6.1.0)(!(version>=7.0.0))) ---- -=== Dynamic import +==== Dynamic import The `bundle:dynamic-import` command allows you to enable or disable the dynamic import of a given bundle: @@ -123,7 +123,7 @@ bundles to be considered for a wiring import to be added. The `bundle:dynamic-import` command allows or doesn't allow this behaviour. -=== OSGi framework +==== OSGi framework The `system:framework` command allows to display the current OSGi framework in use, and enable/disable debugging inside the OSGi framework. @@ -136,7 +136,7 @@ karaf@root()> system:framework -nodebug Disabling debug for OSGi framework (felix) ---- -=== Stack traces printout +==== Stack traces printout The `shell:stack-traces-print` command prints the full stack trace when the execution of a command throws an exception. @@ -187,7 +187,7 @@ karaf@root()> bundle:start Error executing command: Access to system bundle 0 denied. You can override with -f ---- -=== Bundle tree +==== Bundle tree The `bundle:tree-show` command shows the bundle dependency tree based on the wiring information of a given single bundle ID. @@ -220,7 +220,7 @@ org.ops4j.pax.url.wrap [40] +- org.ops4j.base.lang [41] ---- -=== Watch +==== Watch The `bundle:watch` command enables watching the local Maven repository for updates on bundles. If the bundle file changes on the Maven repository, Apache Karaf will automatically update the bundle. @@ -229,9 +229,10 @@ The `bundle:watch` allows you to configure a set of URLs to monitore. All bundle given URL will be automatically updated. It avoids needing to manually update the bundles or even copy the bundle to the system folder. -{warning} +[NOTE] +==== Only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically. -{warning} +==== The following command: http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/ds.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/ds.adoc b/manual/src/main/asciidoc/developer-guide/ds.adoc index bb34893..af4086e 100644 --- a/manual/src/main/asciidoc/developer-guide/ds.adoc +++ b/manual/src/main/asciidoc/developer-guide/ds.adoc @@ -12,4 +12,4 @@ // limitations under the License. // -== Declarative Service (DS) \ No newline at end of file +=== Declarative Service (DS) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/extending.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/extending.adoc b/manual/src/main/asciidoc/developer-guide/extending.adoc index 62c56a4..809b1ec 100644 --- a/manual/src/main/asciidoc/developer-guide/extending.adoc +++ b/manual/src/main/asciidoc/developer-guide/extending.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== Extending +=== Extending Apache Karaf is a very flexible container that you can extend very easily. -=== Console +==== Console In this section, you will see how to extend the console by adding your own command. @@ -24,14 +24,14 @@ 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. -==== Create the Maven project +===== Create the Maven project To create the Maven project, we can: * use a Maven archetype * create by hand -===== Using archetype +====== Using archetype The Maven Quickstart archetype can create an empty Maven project where you can put your project definition. @@ -59,7 +59,7 @@ Define value for version: 1.0-SNAPSHOT: : Define value for package: : org.apache.karaf.shell.samples ---- -==== By hand +===== By hand Alternatively, you can simply create the directory `shell-sample-commands` and create the `pom.xml` file inside it: @@ -112,7 +112,7 @@ Alternatively, you can simply create the directory `shell-sample-commands` and c </project> ---- -==== Configuring for Java 6/7 +===== Configuring for Java 6/7 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 `dependencies` section. @@ -132,7 +132,7 @@ Just add the following snippet after the `dependencies` section. </build> ---- -==== Loading the project in your IDE +===== Loading the project in your IDE We can use Maven to generate the needed files for your IDE: @@ -150,7 +150,7 @@ mvn idea:idea The project files for your IDE should now be created. Just open the IDE and load the project. -==== Creating a basic command class +===== Creating a basic command class We can now create the command class `HelloShellCommand.java` @@ -173,7 +173,7 @@ public class HelloShellCommand implements Action { } ---- -==== Manifest +===== Manifest In order for Karaf to find your command, you need to add the `Karaf-Commands=*` manifest header. @@ -191,7 +191,7 @@ This is usually done by modifying the maven bundle plugin configuration </plugin> ---- -==== Compile +===== Compile 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: @@ -207,7 +207,7 @@ The end of the maven output should look like: [INFO] ------------------------------------------------------------------------ ---- -==== Test +===== Test Launch Apache Karaf and install your bundle: @@ -222,14 +222,14 @@ karaf@root()> test:hello Executing Hello command ---- -==== Command completer +===== Command completer A completer allows you to automatically complete a command argument using <tab>. A completer is simply a bean which is injected to a command. Of course to be able to complete it, the command should require an argument. -==== Command argument +===== Command argument We add an argument to the HelloCommand: @@ -258,7 +258,7 @@ public class HelloShellCommand implements Action { } ---- -==== Completer bean +===== Completer bean A completer is a bean which implements the Completer interface: @@ -290,7 +290,7 @@ public class SimpleNameCompleter implements Completer { } ---- -==== Completers for option values +===== Completers for option values 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. @@ -325,7 +325,7 @@ public class HelloShellCommand implements Action { } ---- -==== Completers with state +===== Completers with state 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 @@ -337,7 +337,7 @@ The pre-parsed CommandLine objects allows you to check the previous arguments an the behavior of the Completer. Those two objects are given to the Completer when calling the `complete` method. -==== Test +===== Test Launch a Karaf instance and run the following command to install the newly created bundle: @@ -352,7 +352,7 @@ karaf@root> test:hello <tab> one two three ---- -=== WebConsole +==== WebConsole You can also extend the Apache Karaf WebConsole by providing and installing a webconsole plugin. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/github-contributions.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/github-contributions.adoc b/manual/src/main/asciidoc/developer-guide/github-contributions.adoc index de3c098..bc03e00 100644 --- a/manual/src/main/asciidoc/developer-guide/github-contributions.adoc +++ b/manual/src/main/asciidoc/developer-guide/github-contributions.adoc @@ -12,15 +12,15 @@ // limitations under the License. // -== Github Contributions +=== Github Contributions Some people prefer to make contributions to karaf source via github. If you are one of them, this is for you! -=== Introduction +==== Introduction Apache Karaf is available as a periodically replicated mirror on: https://github.com/apache/karaf -=== Suggested Workflow +==== Suggested Workflow . Make a fork of karaf repo github mirror . Do all your new work on your own karaf fork @@ -30,14 +30,14 @@ Apache Karaf is available as a periodically replicated mirror on: https://github . Now pray to your favorite ASF committer to really accept the patch :-) . When your patch is committed to the svn, and you can verify it in the latest karaf snapshot, close your pull request on github -=== License Reminder +==== License Reminder In order for your contributions to be accepted: * All files must contain ASL license grant header * You must select ASF grant check box when attaching patch to the jira -=== How to Generate a One-File-Patch Via Throw-Away Branch +==== How to Generate a One-File-Patch Via Throw-Away Branch Here is one way to generate squash of your commits: http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc b/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc index e4ed117..f3f9b2b 100644 --- a/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc +++ b/manual/src/main/asciidoc/developer-guide/karaf-maven-plugin.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Using the karaf-maven-plugin +=== Using the karaf-maven-plugin The Karaf Maven plugin allows you: @@ -20,7 +20,7 @@ The Karaf Maven plugin allows you: * to create Karaf commands help: it generates help from Karaf commands * to modify Karaf instances and create distributions -=== Packaging +==== Packaging 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: @@ -64,18 +64,18 @@ Then specify the packaging in your project as usual, e.g. |Assembles a Karaf server based on the features descriptors and kar files listed as Maven dependencies. |=== -=== Commands goals +==== Commands goals The `karaf-maven-plugin` is able to generate documentation for Karaf commands -==== `karaf:commands-generate-help` +===== `karaf:commands-generate-help` The `karaf:commands-generate-help` goal generates documentation containing Karaf commands help. It looks for Karaf commands in the current project class loader and generates the help as displayed with the `--help` option in the Karaf shell console. -===== Example +====== Example The example below generates help for the commands in the current project: @@ -106,7 +106,7 @@ The example below generates help for the commands in the current project: </project> ---- -===== Parameters +====== Parameters |=== |Name |Type |Description @@ -124,7 +124,7 @@ The example below generates help for the commands in the current project: |The class loader to use in loading the commands. Default value: ${project} |=== -=== Features and kar goals +==== Features and kar goals [NOTE] ==== @@ -133,7 +133,7 @@ You should use the features or kar packaging instead of these individual goals. The `karaf-maven-plugin` provides several goals to help you create and validate features XML descriptors as well as leverage your features to create a custom Karaf distribution. -==== `karaf:features-generate-descriptor` +===== `karaf:features-generate-descriptor` Except in unusual circumstances, use the `<packaging>feature</packaging>` to run this goal. @@ -144,7 +144,7 @@ A record of the dependency tree search can be found in target/history/treeListin You can track dependency changes and warn or fail on change. -===== Configuration +====== Configuration Specify the packaging as a top level element @@ -189,7 +189,7 @@ This can be overridden by specifying the bundle in the source feature.xml with t |If true, the `src/main/history/dependencies.xml` file will be overwritten if it has changed. |=== -===== Example +====== Example ---- <project> @@ -219,7 +219,7 @@ This can be overridden by specifying the bundle in the source feature.xml with t </project> ---- -==== `karaf:features-validate-descriptor` +===== `karaf:features-validate-descriptor` The `karaf:features-validate-descriptor` goal validates a features XML descriptor by checking if all the required imports for the bundles defined in the features can be matched to a provided export. @@ -228,7 +228,7 @@ By default, the plugin tries to add the Karaf core features (standard and enterp It means that it's not required to explicitly define the Karaf features descriptor in the repository section of your features descriptor. -===== Example +====== Example The example below validates the features defined in the `target/features.xml` by checking all the imports and exports. It reads the definition for the packages that are exported by the system bundle from the `src/main/resources/config.properties` file. @@ -267,7 +267,7 @@ It reads the definition for the packages that are exported by the system bundle </project> ---- -===== Parameters +====== Parameters |=== |Name |Type |Description @@ -293,7 +293,7 @@ It reads the definition for the packages that are exported by the system bundle |Additional features XML descriptors that will be used during the validation process |=== -==== `karaf:features-add-to-repository` +===== `karaf:features-add-to-repository` Consider using the karaf-assembly packaging which makes it easy to assemble a custom distribution in one step instead of this individual goal. @@ -303,7 +303,7 @@ You can use this goal to create a `/system` directory for building your own Kara By default, the Karaf core features descriptors (standard and enterprise) are automatically included in the descriptors set. -===== Example +====== Example The example below copies the bundles for the `spring` and `war` features defined in the Karaf features XML descriptor into the `target/features-repo` directory. @@ -344,7 +344,7 @@ into the `target/features-repo` directory. </project> ---- -===== Parameters +====== Parameters |=== |Name |Type |Description @@ -362,7 +362,7 @@ into the `target/features-repo` directory. |The directory where the bundles will be copied by the plugin goal |=== -==== `karaf:create-kar` +===== `karaf:create-kar` [NOTE] ==== @@ -383,7 +383,7 @@ Therefore resources you want installed into Karaf need to be in e.g. `src/main/r This choice is so other resources such as legal files from the maven-remote-resources-plugin can be included under META-INF in the kar, without getting installed into Karaf. -===== Example +====== Example ---- <project> @@ -403,9 +403,9 @@ META-INF in the kar, without getting installed into Karaf. </project> ---- -==== `karaf:install-kar` +===== `karaf:install-kar` -=== Instances and distributions goals +==== Instances and distributions goals [NOTE] ==== @@ -414,7 +414,7 @@ You should use the karaf-assembly packaging instead of this individual goal. The `karaf-maven-plugin` helps you to build custom Karaf distributions or archives existing Karaf instances: -==== `karaf:archive` +===== `karaf:archive` [NOTE] ==== @@ -425,7 +425,7 @@ The `karaf:archive` goal packages a Karaf instance archive from a given assemble Both tar.gz and zip formats are generated in the destination folder. -===== Example +====== Example The example below create archives for the given Karaf instance: @@ -457,7 +457,7 @@ The example below create archives for the given Karaf instance: </project> ---- -===== Parameters +====== Parameters |=== |Name |Type |Description @@ -475,12 +475,12 @@ The example below create archives for the given Karaf instance: |The target file to set as the project's artifact. Default value: ${project.file} |=== -==== `karaf:assembly` +===== `karaf:assembly` -=== Run, client, deploy goals +==== Run, client, deploy goals -==== `karaf:run` +===== `karaf:run` -==== `karaf:client` +===== `karaf:client` -==== `karaf:deploy` \ No newline at end of file +===== `karaf:deploy` \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/scripting.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/scripting.adoc b/manual/src/main/asciidoc/developer-guide/scripting.adoc index 64dae18..1ae4402 100644 --- a/manual/src/main/asciidoc/developer-guide/scripting.adoc +++ b/manual/src/main/asciidoc/developer-guide/scripting.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== Scripting +=== Scripting In the console section of the users guide, we introduced the scripting support. -=== Assignation +==== Assignation You already know the first usage of scripting: execution of command. @@ -50,7 +50,7 @@ The `$.context` access the context variables in the current session. We access to the `bundle` variable (an array containing all bundles), and we want to display the bundle location for the bundle at the index 1 in the bundle array. -=== Expressions +==== Expressions The shell has a built-in expression parser. Expressions must be enclosed with the `%(...)` syntax. @@ -71,7 +71,7 @@ karaf@root()> %(SQRT(a^2 + b^2)) 1.7320508 ---- -==== Mathematical Operators +===== Mathematical Operators |=== |Operator |Description @@ -95,7 +95,7 @@ karaf@root()> %(SQRT(a^2 + b^2)) | Power operator |=== -==== Boolean Operators +===== Boolean Operators |=== |Operator |Description @@ -131,7 +131,7 @@ karaf@root()> %(SQRT(a^2 + b^2)) |Boolean or |=== -==== Supported Functions +===== Supported Functions |=== |Function |Description @@ -196,7 +196,7 @@ karaf@root()> %(SQRT(a^2 + b^2)) Functions names are case insensitive. -==== Supported Constants +===== Supported Constants |=== |Constant |Description @@ -211,7 +211,7 @@ Functions names are case insensitive. |The value zero |=== -=== List, maps, pipes and closures +==== List, maps, pipes and closures Using [], you can define array variable: @@ -254,12 +254,12 @@ karaf@root()> echo2 hello world xxx hello world yyy ---- -=== Startup +==== Startup The `etc/shell.init.script` file is executed at startup in each shell session, allowing the definition of additional variables or aliases or even complex functions. It's like the bashrc or profile on Unix. -=== Constants and variables +==== Constants and variables Apache Karaf console provides a set of implicit constants and variables that you can use in your script. @@ -279,7 +279,7 @@ ii karaf@root> ---- -=== Built-in variables and commands +==== Built-in variables and commands Apache Karaf console provides built-in variable very useful for scripting: @@ -296,7 +296,7 @@ Apache Karaf console provides commands for scripting: See the link:commands[full list of `shell` commands] for details. -=== Leveraging existing Java capabilities (via reflection) +==== Leveraging existing Java capabilities (via reflection) Apache Karaf console supports loading and execution of Java classes. @@ -345,7 +345,7 @@ karaf@root> $map 0 0 ---- -=== Examples +==== Examples The following examples show some scripts defined in `etc/shell.init.script`. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/security-framework.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/security-framework.adoc b/manual/src/main/asciidoc/developer-guide/security-framework.adoc index 62c6ba4..190d064 100644 --- a/manual/src/main/asciidoc/developer-guide/security-framework.adoc +++ b/manual/src/main/asciidoc/developer-guide/security-framework.adoc @@ -12,14 +12,14 @@ // limitations under the License. // -== Security framework +=== Security framework Karaf supports http://download.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html[JAAS] with some enhancements to allow JAAS to work nicely in an OSGi environment. This framework also features an OSGi keystore manager with the ability to deploy new keystores or truststores at runtime. -=== Overview +==== Overview 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 `karaf` realm, but which is configured with a dummy login module @@ -31,7 +31,7 @@ up HTTPS connectors or using certificates for WS-Security. A very simple XML schema for spring has been defined, allowing the deployment of a new realm or a new keystore very easily. -=== Schema +==== Schema 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. @@ -84,7 +84,7 @@ The content of the `module` element is parsed as a properties file and will be u Deploying such a code will lead to a JaasRealm object in the OSGi registry, which will then be used when using the JAAS login module. -==== Configuration override and use of the `rank` attribute +===== Configuration override and use of the `rank` attribute The `rank` attribute on the `config` element is tied to the ranking of the underlying OSGi service. When the JAAS framework performs an authentication, it will use the realm name to find a matching JAAS configuration. If multiple @@ -112,7 +112,7 @@ JMX layer), you need to deploy a JAAS configuration with the name `name="karaf"` </blueprint> ---- -=== Architecture +==== Architecture 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. @@ -133,13 +133,13 @@ allows you to manipulate users and roles directly from Karaf (adding a new user, The backend engine is constructed by a backend engine factory, registered as an OSGi service. Some login modules (for security reason for instance) don't provide backend engine. -=== Available realm and login modules +==== Available realm and login modules Karaf comes with a default realm named "karaf" using login modules. Karaf also provides a set of login modules and backend engines to handle authentication needs for your environment. -==== PropertiesLoginModule +===== PropertiesLoginModule |=== |LoginModule |BackendEngineFactory @@ -208,7 +208,7 @@ shows how to register the PropertiesLoginModule and the corresponding backend en </blueprint> ---- -==== OsgiConfigLoginModule +===== OsgiConfigLoginModule |=== |LoginModule |BackendEngineFactory @@ -257,7 +257,7 @@ The following blueprint shows how to use this configuration: The OsgiConfigLoginModule doesn't provide a backend engine. ==== -==== JDBCLoginModule +===== JDBCLoginModule |=== |LoginModule |BackendEngineFactory @@ -348,7 +348,7 @@ The following blueprint shows how to define the JDBCLoginModule with the corresp </blueprint> ---- -==== LDAPLoginModule +===== LDAPLoginModule |=== |LoginModule |BackendEngineFactory @@ -505,7 +505,7 @@ The LDAPLoginModule doesn't provide backend engine. It means that the administra performed directly on the LDAP backend. ==== -==== SyncopeLoginModule +===== SyncopeLoginModule |=== |LoginModule |BackendEngineFactory @@ -573,14 +573,14 @@ For instance, the following blueprint descriptor enables the SyncopeLoginModule </blueprint> ---- -=== Encryption service +==== Encryption service 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. This service is used in all Karaf login modules to support encrypted passwords. -==== Configuring properties +===== Configuring properties Each login module supports the following additional set of properties: @@ -626,12 +626,12 @@ A simple example follows: </jaas:config> ---- -==== Prefix and suffix +===== Prefix and suffix The login modules have the ability to support both encrypted and plain passwords at the same time. In some cases, some login modules may be able to encrypt the passwords on the fly and save them back in an encrypted form. -==== Jasypt +===== Jasypt Karaf default installation comes with a simple encryption service which usually fullfill simple needs. However, in some cases, you may want to install the Jasypt (http://www.jasypt.org/) library which provides stronger encryption algorithms @@ -685,7 +685,7 @@ A typical realm definition using Jasypt encryption service would look like: </jaas:config> ---- -==== Using encrypted property placeholders +===== Using encrypted property placeholders When using blueprint framework for OSGi for configuring devices that requires passwords like JDBC datasources, it is undesirable to use plain text passwords in configuration files. To avoid this problem it is good to store database @@ -750,7 +750,7 @@ Don't forget to install the jasypt feature to add the support of the enc namespa karaf@root()> feature:install jasypt-encryption ---- -=== Role discovery policies +==== Role discovery policies 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 @@ -821,7 +821,7 @@ for (Principal p : subject.getPrincipals()) { } ---- -=== Default role policies +==== Default role policies The previous section describes how to leverage role policies. However, Karaf provides a default role policy, based on the following class names: http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/services.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/services.adoc b/manual/src/main/asciidoc/developer-guide/services.adoc index f724270..55df2dc 100644 --- a/manual/src/main/asciidoc/developer-guide/services.adoc +++ b/manual/src/main/asciidoc/developer-guide/services.adoc @@ -12,4 +12,4 @@ // limitations under the License. // -== OSGi Services \ No newline at end of file +=== OSGi Services \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/developer-guide/writing-tests.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/writing-tests.adoc b/manual/src/main/asciidoc/developer-guide/writing-tests.adoc index d3f95a7..1c95008 100644 --- a/manual/src/main/asciidoc/developer-guide/writing-tests.adoc +++ b/manual/src/main/asciidoc/developer-guide/writing-tests.adoc @@ -12,14 +12,14 @@ // limitations under the License. // -== Writing integration tests +=== Writing integration tests We recommend using http://team.ops4j.org/wiki/display/paxexam/Pax+Exam[PAX Exam] to write integration tests when developing applications using Karaf. 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. -=== Introduction +==== Introduction Pax Exam directly supports Karaf as a test container. @@ -114,9 +114,9 @@ public class VersionAsInProjectKarafTest { } ---- -=== Commands +==== Commands -==== KarafDistributionConfigurationOption +===== KarafDistributionConfigurationOption The framework itself is non of the typical runtimes you define normally in Pax-Exam. @@ -177,7 +177,7 @@ As an alternative you can also use the maven url resolvers. 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. -===== Unpack Directory +====== Unpack Directory 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: @@ -190,7 +190,7 @@ public Option[] config() { } ---- -===== Use Deploy Folder +====== Use Deploy Folder 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 @@ -205,7 +205,7 @@ public Option[] config() { } ---- -==== KarafDistributionKitConfigurationOption +===== KarafDistributionKitConfigurationOption 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 @@ -224,7 +224,7 @@ public Option[] config() { } ---- -==== KarafDistributionConfigurationFilePutOption +===== KarafDistributionConfigurationFilePutOption The option replaces or adds an option to one of Karaf's configuration files: @@ -239,7 +239,7 @@ This option could also be used in "batch-mode" via a property file. Therefore us 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. -==== KarafDistributionConfigurationFileExtendOption +===== KarafDistributionConfigurationFileExtendOption 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. @@ -247,7 +247,7 @@ adds or appends a specific property. This is especially useful if you do not wan 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. -==== KarafDistributionConfigurationFileReplacementOption +===== KarafDistributionConfigurationFileReplacementOption The file replacement option allows you to simply replace a file in you Karaf distribution with a different file: @@ -256,12 +256,12 @@ new KarafDistributionConfigurationFileReplacementOption("etc/tests.cfg", new Fil "src/test/resources/BaseKarafDefaultFrameworkDuplicatedPropertyEntryTestSecondKey")); ---- -==== ProvisionOption +===== ProvisionOption 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. -==== KarafDistributionConfigurationConsoleOption +===== KarafDistributionConfigurationConsoleOption 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: @@ -281,12 +281,12 @@ public Option[] config() { } ---- -==== VMOption +===== VMOption 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. -==== LogLevelOption +===== LogLevelOption 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: @@ -300,7 +300,7 @@ public Option[] config() { } ---- -==== DoNotModifyLogOption +===== DoNotModifyLogOption 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: @@ -313,7 +313,7 @@ public Option[] config() { } ---- -==== KeepRuntimeFolderOption +===== KeepRuntimeFolderOption 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: @@ -325,23 +325,23 @@ public Option[] config() { } ---- -==== FeaturesScannerProvisionOption +===== FeaturesScannerProvisionOption The FeaturesScannerProvisionOption (e.g. CoreOption.scanFeature()) are directly supported by the Paxexam Karaf Testframework. -==== BootDelegationOption +===== BootDelegationOption The BootDelegationOption as known from PaxExam is also supported added the boot delegation string directly into the correct property files. -==== SystemPackageOption +===== SystemPackageOption The Standard Exam SystemPackageOption is implemented by adding those packages to "org.osgi.framework.system.packages.extra" of the config.properties file. -==== BootClasspathLibraryOption +===== BootClasspathLibraryOption The BootClasspathLibraryOption is honored by copying the urls into the lib directory where they are automatically taken and worked on. -==== ExamBundlesStartLevel +===== ExamBundlesStartLevel 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: @@ -353,18 +353,18 @@ public Option[] config() { } ---- -=== Driver +==== Driver 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. -==== JavaRunner +===== JavaRunner 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. -==== ScriptRunner +===== ScriptRunner 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. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc index 7f7a57f..9ffab56 100644 --- a/manual/src/main/asciidoc/index.adoc +++ b/manual/src/main/asciidoc/index.adoc @@ -15,26 +15,20 @@ Apache Karaf Container 4.x - Documentation ========================================= Apache Software Foundation -:doctype: book +:doctype: article :toc: left :toclevels: 3 :toc-position: left :toc-title: Apache Karaf Container 4.x - Documentation :numbered: -= Overview - include::overview.adoc[] -= Quick Start - include::quick-start.adoc[] -= Update Notes (from Karaf 3.x to 4.x versions) - include::update-notes.adoc[] -= User Guide +== User Guide include::user-guide/installation.adoc[] @@ -66,7 +60,7 @@ include::user-guide/security.adoc[] include::user-guide/obr.adoc[] -== Enterprise +=== Enterprise include::user-guide/http.adoc[] @@ -94,7 +88,7 @@ include::user-guide/webconsole.adoc[] include::user-guide/tuning.adoc[] -= Developer Guide +== Developer Guide [NOTE] ==== http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/overview.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/overview.adoc b/manual/src/main/asciidoc/overview.adoc index 6b87e57..ff3bbce 100644 --- a/manual/src/main/asciidoc/overview.adoc +++ b/manual/src/main/asciidoc/overview.adoc @@ -12,6 +12,8 @@ // limitations under the License. // +== Overview + Apache Karaf is a modern and polymorphic container. Karaf can be used standalone as a container, supporting a wide range of applications and technologies. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/quick-start.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/quick-start.adoc b/manual/src/main/asciidoc/quick-start.adoc index 5a9b55a..16094fb 100644 --- a/manual/src/main/asciidoc/quick-start.adoc +++ b/manual/src/main/asciidoc/quick-start.adoc @@ -12,9 +12,11 @@ // limitations under the License. // +== Quick Start + These instructions should help you get Apache Karaf up and running in 5 to 15 minutes. -== Prerequisites +=== Prerequisites Karaf requires a Java SE 7 or Java SE 8 environment to run. Refer to http://www.oracle.com/technetwork/java/javase/ for details on how to download and install Java SE 1.7 or greater. @@ -22,7 +24,7 @@ Karaf requires a Java SE 7 or Java SE 8 environment to run. Refer to http://www. * Download the binary distribution that matches your system (zip for windows, tar.gz for unixes) * Extract the archive to a new folder on your hard drive; for example in c:\karaf - from now on this directory will be referenced as <KARAF_HOME>. -== Start the server +=== Start the server Open a command line console and change the directory to <KARAF_HOME>. @@ -57,7 +59,7 @@ karaf@root()> ---- -== Shell console basics +=== Shell console basics You can now run your first command. Simply type the `<tab>` key in the console. @@ -114,7 +116,7 @@ OPTIONS Note that the console supports tab completion so if you start typing a command it will show all possible completions and also auto complete if there is only one completion. -== Deploy a sample application +=== Deploy a sample application While you will learn in the Karaf user's guide how to fully use and leverage Apache Karaf, let's install a sample http://camel.apache.org[Apache Camel] application for now: @@ -143,7 +145,7 @@ karaf@root()> log:display 2015-06-30 13:39:48,730 | INFO | timer://myTimer | ExampleRouter | 53 - org.apache.camel.camel-core - 2.15.2 | Exchange[ExchangePattern: InOnly, BodyType: String, Body: SpringDSL set body: Tue Jun 30 13:39:48 CEST 2015] ---- -== Stopping and uninstalling the sample application +=== Stopping and uninstalling the sample application To stop and uninstall the demo, run the following command: @@ -152,7 +154,7 @@ karaf@root()> bundle:stop camel-example-osgi karaf@root()> bundle:uninstall camel-example-osgi ---- -== Stopping Karaf +=== Stopping Karaf To stop Karaf from the console, enter `^D` in the console: @@ -172,10 +174,10 @@ halt is also an alias for system:shutdown: karaf@root()> halt ---- -== Cleaning the Karaf state +=== Cleaning the Karaf state Normally Karaf remembers the features and bundles you installed and started. To reset Karaf into a clean state, just delete the data directory when Karaf is not running. -== Summary +=== Summary This document shows how simple it is to get Apache Karaf up and running and install a simple Apache Camel application. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/update-notes.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/update-notes.adoc b/manual/src/main/asciidoc/update-notes.adoc index 0c5176f..59673c9 100644 --- a/manual/src/main/asciidoc/update-notes.adoc +++ b/manual/src/main/asciidoc/update-notes.adoc @@ -12,20 +12,28 @@ // limitations under the License. // +== Update Notes (from Karaf 3.x to 4.x versions) + This section is dedicated to users of previous Apache Karaf version. -NB: for the users upgrading from Karaf 2.x, please see the "Update Notes (from 2.x to 3.x)" in the Karaf 3.x +[NOTE] +==== +For the users upgrading from Karaf 2.x, please see the "Update Notes (from 2.x to 3.x)" in the Karaf 3.x documentation first. +==== -NB: Karaf 4.x supports Java8. +[NOTE] +==== +Karaf 4.x supports Java8. +==== -== Distributions +=== Distributions Apache Karaf 4.x is available as tar.gz and zip archives. The content is the same and works on either Unix or Windows platforms. The `bin` folder contains both sh and bat scripts. -== Commands +=== Commands Karaf 4 commands are close to the ones provided in Karaf 3. @@ -106,7 +114,7 @@ To simplify the generation of the code and OSGi headers, Karaf 4.x provides the Take a look in the developer guide for the command development "new style" details. -== Features repositories +=== Features repositories Karaf 4.x provides: @@ -116,7 +124,7 @@ Karaf 4.x provides: * `mvn:org.apache.karaf.features/standard/4.0.x/xml/features` * `mvn:org.apache.karaf.features/static/4.0.x/xml/features` -== Features resolver +=== Features resolver Apache Karaf 4.x brings a complete new feature resolver. The purpose is to simplify the features installation and lifecycle. @@ -127,7 +135,7 @@ It allows Karaf to automatically install bundles required by features. For "old style" feature (features XML using namespace from Karaf 2.x or 3.x), this feature is not enabled. As soon as you use a "new style" feature (with namespace 1.3.0 used by Karaf 4.x), this feature is enabled. -== Namespaces +=== Namespaces Apache Karaf 4.x brings updated version of the namespaces: @@ -144,7 +152,7 @@ Apache Karaf 4.x brings updated version of the namespaces: ** `karaf-shell-1.0.0.xsd` ** `karaf-shell-1.1.0.xsd` -== Maven plugin +=== Maven plugin A cleanup of the goals provided by {{karaf-maven-plugin}} has been done. @@ -162,7 +170,7 @@ Now the provided goals are: * `karaf:client` to interact with a remote Karaf instance * `karaf:deploy` to deploy an application to a remote Karaf instance -== Update guide +=== Update guide We encourage users to start a fresh Apache Karaf 4.x container. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/cdi.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/cdi.adoc b/manual/src/main/asciidoc/user-guide/cdi.adoc index 3ddd253..e4eb64f 100644 --- a/manual/src/main/asciidoc/user-guide/cdi.adoc +++ b/manual/src/main/asciidoc/user-guide/cdi.adoc @@ -12,12 +12,12 @@ // limitations under the License. // -=== CDI +==== CDI This section described how to add support of CDI, and embed a CDI container in Apache Karaf. It doesn't describe how to develop CDI applications. See the developer guide for that. -==== Pax CDI +===== Pax CDI Apache Karaf supports different CDI containers by using Pax CDI. @@ -47,13 +47,13 @@ deltaspike-partial-bean | 1.2.1 | deltaspike-data | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike data support ---- -==== CDI Containers +===== CDI Containers Thanks to Pax CDI, Apache Karaf supports multiple CDI implementation versions, and different CDI containers. You just have to install the feature corresponding to the CDI container and version that you want to use. -===== Apache OpenWebBeans +====== Apache OpenWebBeans Apache Karaf provides a ready to use feature for Apache OpenWebBeans. @@ -64,7 +64,7 @@ karaf@root()> feature:install http karaf@root()> feature:install pax-cdi-openwebbeans ---- -===== JBoss Weld CDI container +====== JBoss Weld CDI container Apache Karaf provides a ready to use feature for JBoss Weld. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/configugration.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/configugration.adoc b/manual/src/main/asciidoc/user-guide/configugration.adoc index 7226849..165c765 100644 --- a/manual/src/main/asciidoc/user-guide/configugration.adoc +++ b/manual/src/main/asciidoc/user-guide/configugration.adoc @@ -12,9 +12,9 @@ // limitations under the License. // -== Configuration +=== Configuration -=== Files +==== Files Apache Karaf stores and loads all configuration in files located in the `etc` folder. @@ -75,11 +75,11 @@ You can change the configuration at runtime by directly editiing the configurati You can also do the same using the `config:*` commands or the ConfigMBean. -=== `config:*` commands +==== `config:*` commands Apache Karaf provides a set of commands to manage the configuration. -==== `config:list` +===== `config:list` `config:list` displays the list of all configurations available, or the properties in a given configuration (PID). @@ -128,7 +128,7 @@ Properties: size = 500 ---- -==== `config:edit` +===== `config:edit` `config:edit` is the first command to do when you want to change a configuration. `config:edit` command put you in edition mode for a given configuration. @@ -149,7 +149,7 @@ All changes that you do in configuration edit mode are store in your console ses applied in the configuration. It allows you to "commit" the changes (see `config:update` command) or "rollback" and cancel your changes (see `config:cancel` command). -==== `config:property-list` +===== `config:property-list` The `config:property-list` lists the properties for the currently edited configuration. @@ -163,7 +163,7 @@ karaf@root()> config:property-list size = 500 ---- -==== `config:property-set` +===== `config:property-set` The `config:property-set` command update the value of a given property in the currently edited configuration. @@ -201,7 +201,7 @@ Properties: Using the `pid` option, you bypass the configuration commit and rollback mechanism. ==== -==== `config:property-append` +===== `config:property-append` The `config:property-append` is similar to `config:property-set` command, but instead of completely replacing the property value, it appends a string at the end of the property value. @@ -241,7 +241,7 @@ Properties: Using the `pid` option, you bypass the configuration commit and rollback mechanism. ==== -==== `config:property-delete` +===== `config:property-delete` The `config:property-delete` command delete a property in the currently edited configuration. @@ -270,7 +270,7 @@ You can use the `config:property-delete` command outside the configuration edit karaf@root()> config:property-delete -p org.apache.karaf.log test ---- -==== `config:update` and `config:cancel` +===== `config:update` and `config:cancel` When you are in the configuration edit mode, all changes that you do using `config:property*` commands are stored in "memory" (actually in the console session). @@ -318,7 +318,7 @@ Properties: felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg ---- -==== `config:delete` +===== `config:delete` The `config:delete` command completely delete an existing configuration. You don't have to be in edit mode to delete a configuration. @@ -347,7 +347,7 @@ karaf@root()> config:list "(service.pid=my.config)" karaf@root()> ---- -==== `config:meta` +===== `config:meta` The `config:meta` command lists the meta type information related to a given configuration. @@ -362,17 +362,17 @@ size | Size | int | 500 pattern | Pattern | String | %d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n | Pattern used to display log entries ---- -=== JMX ConfigMBean +==== JMX ConfigMBean On the JMX layer, you have a MBean dedicated to the management of the configurations: the ConfigMBean. The ConfigMBean object name is: `org.apache.karaf:type=config,name=*`. -==== Attributes +===== Attributes The `Configs` attribute is a list of all configuration PIDs. -==== Operations +===== Operations * `listProperties(pid)` returns the list of properties (property=value formatted) for the configuration `pid`. * `deleteProperty(pid, property)` deletes the `property` from the configuration `pid`. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/console.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/console.adoc b/manual/src/main/asciidoc/user-guide/console.adoc index efcb8e1..72bff8f 100644 --- a/manual/src/main/asciidoc/user-guide/console.adoc +++ b/manual/src/main/asciidoc/user-guide/console.adoc @@ -12,9 +12,9 @@ // limitations under the License. // -== Using the console +=== Using the console -=== Available commands +==== Available commands To see a list of the available commands in the console, you can use the `help`: @@ -40,7 +40,7 @@ karaf@root()> Display all 294 possibilities? (y or n) ... ---- -=== Subshell and completion mode +==== Subshell and completion mode The commands have a scope and a name. For instance, the command `feature:list` has `feature` as scope, and `list` as name. @@ -163,11 +163,11 @@ backlog-tracer-dump backlog-tracer-info backlog-tracer-start backlog-tracer-stop route-resume route-show route-start route-stop route-suspend ---- -=== Unix like environment +==== Unix like environment Karaf console provides a full Unix like environment. -==== Help or man +===== Help or man We already saw the usage of the `help` command to display all commands available. @@ -206,7 +206,7 @@ OPTIONS ---- -==== Completion +===== Completion When you type the tab key, Karaf tries to complete: @@ -216,7 +216,7 @@ When you type the tab key, Karaf tries to complete: * command arguments * command options -==== Alias +===== Alias An alias is another name associated to a given command. @@ -274,7 +274,7 @@ You can see here the aliases available by default: You can create your own aliases in the `etc/shell.init.script` file. -==== Key binding +===== Key binding Like on most Unix environment, Karaf console support some key bindings: @@ -283,7 +283,7 @@ Like on most Unix environment, Karaf console support some key bindings: * CTRL-R to search previously executed command * CTRL-U to remove the current line -==== Pipe +===== Pipe You can pipe the output of one command as input to another one. It's a pipe, using the | character: @@ -295,7 +295,7 @@ war | 4.0.0 | | Un blueprint-web | 4.0.0 | | Uninstalled | standard-4.0.0 | Provides an OSGI-aware Servlet ContextListener fo ---- -==== Grep, more, find, ... +===== Grep, more, find, ... Karaf console provides some core commands similar to Unix environment: @@ -336,7 +336,7 @@ So you can use 'head' instead of 'shell:head' Again, you can find details and all options of these commands using `help` command or `--help` option. -==== Scripting +===== Scripting The Apache Karaf Console supports a complete scripting language, similar to bash or csh on Unix. @@ -451,7 +451,7 @@ You can also named you script with an alias. Actually, the aliases are just scri See the Scripting section of the developers guide for details. -=== Security +==== Security The Apache Karaf console supports a Role Based Access Control (RBAC) security mechanism. It means that depending of the user connected to the console, you can define, depending of the user's groups and roles, the permission to execute http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/deployers.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/deployers.adoc b/manual/src/main/asciidoc/user-guide/deployers.adoc index 63bdd18..01a273e 100644 --- a/manual/src/main/asciidoc/user-guide/deployers.adoc +++ b/manual/src/main/asciidoc/user-guide/deployers.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Deployers +=== Deployers The following picture describes the architecture of the deployers. @@ -64,7 +64,7 @@ By default, Apache Karaf provides a set of deployers: * Wrap deployer is able to handle non-OSGi jar files and turns it as OSGi bundles "on the fly". * Optionally, WAR deployer (if you install the war feature) is able to handle WAR files. -=== Blueprint deployer +==== Blueprint deployer The Blueprint deployer is able to handle plain Blueprint XML configuration files. @@ -95,7 +95,7 @@ If you need to customize the generated manifest, you can do so by including an x </manifest> ---- -=== Spring deployer +==== Spring deployer The Spring deployer is similar to the Blueprint deployer. @@ -121,15 +121,15 @@ If you need to customize the generated manifest, you can do so by including a XM </manifest> ---- -=== Features deployer +==== Features deployer See the link:provisioning[Provisioning section] for details. -=== KAR deployer +==== KAR deployer See the link:kar[KAR section] for details. -=== War deployer +==== War deployer The installation of the WAR feature enables a WAR deployer. @@ -150,7 +150,7 @@ The WAR deployer supports: The only requirement of the WAR deployer is that the archive contains the `WEB-INF/web.xml` file. -=== Wrap deployer +==== Wrap deployer The wrap deployer allows you to "hot deploy" non-OSGi jar files ("classical" jar files) from the deploy folder. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/directory-structure.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/directory-structure.adoc b/manual/src/main/asciidoc/user-guide/directory-structure.adoc index 40da8ae..fd4a595 100644 --- a/manual/src/main/asciidoc/user-guide/directory-structure.adoc +++ b/manual/src/main/asciidoc/user-guide/directory-structure.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Directory structure +=== Directory structure The directory layout of a Karaf installation is as follows: http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/ejb.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/ejb.adoc b/manual/src/main/asciidoc/user-guide/ejb.adoc index 2eebbd6..4fb26e2 100644 --- a/manual/src/main/asciidoc/user-guide/ejb.adoc +++ b/manual/src/main/asciidoc/user-guide/ejb.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -=== EJB +==== EJB This section describes how to add support of EJB in Apache Karaf. It doesn't describe how to develop EJB applications. -==== Apache OpenEJB +===== Apache OpenEJB Apache Karaf doesn't provide "native" support of EJB (Enterprise Java Beans). @@ -82,7 +82,7 @@ You can add EJB support installing the `openejb-core` feature: karaf@root()> feature:install openejb-core ---- -==== Apache KarafEE +===== Apache KarafEE A custom distribution of Apache Karaf embedding OpenEJB is available in the Apache TomEE project. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/failover.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/failover.adoc b/manual/src/main/asciidoc/user-guide/failover.adoc index 24a95dc..7154f03 100644 --- a/manual/src/main/asciidoc/user-guide/failover.adoc +++ b/manual/src/main/asciidoc/user-guide/failover.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -=== HA/failover and cluster +==== HA/failover and cluster Apache Karaf natively provides a failover mechanism. It uses a kind of master/slave topology where one instance is active and the others are in standby. @@ -22,7 +22,7 @@ If you are looking for cluster of Apache Karaf instances (active/active), [Apach Karaf provides failover capability using either a simple lock file or a JDBC locking mechanism. In both cases, a container-level lock system allows bundles to be preloaded into the slave Karaf instance in order to provide faster failover performance. -==== HA/failover (active/passive) +===== HA/failover (active/passive) The Apache Karaf failover capability uses a lock system. @@ -37,7 +37,7 @@ When a first instance starts, if the lock is available, it takes the lock and be If a second instance starts, it tries to acquire the lock. As the lock is already hold by the master, the instance becomes a slave, in standby mode (not active). A slave periodically check if the lock has been released or not. -===== Filesystem lock +====== Filesystem lock The Apache Karaf instances share a lock on the filesystem. It means that the filesystem storing the lock has to be accessible to the different instances (using SAN, NFS, ...). @@ -56,7 +56,7 @@ karaf.lock.delay=10000 * `karaf.lock.dir` property contains the location where the lock will be written. All instances have to share the same lock. * `karaf.lock.delay` property is the interval period (in milliseconds) to check if the lock has been released or not. -===== Database lock +====== Database lock It's not always possible and easy to have a shared filesystem between multiple Apache Karaf instances. @@ -113,7 +113,7 @@ If the connection to the database is lost, the master instance tries to graceful become the master when the database is back. The former master instance will required a manual restart. ==== -====== Lock on Oracle +*Lock on Oracle* Apache Karaf supports Oracle database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.OracleJDBCLock`: @@ -137,7 +137,7 @@ The `karaf.lock.jdbc.url` property contains a JDBC URL which requires an active database instance first before using the lock mechanism. ==== -====== Lock on Derby +*Lock on Derby* Apache Karaf supports Apache Derby database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.DerbyJDBCLock`: @@ -155,7 +155,7 @@ karaf.lock.jdbc.timeout=30 The Derby JDBC driver file name has to be copied in the `lib/ext` folder. -====== Lock on MySQL +*Lock on MySQL* Apache Karaf supports MySQL database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.MySQLJDBCLock`: @@ -173,7 +173,7 @@ karaf.lock.jdbc.timeout=30 The MySQL JDBC driver file name has to be copied in `lib/ext` folder. -====== Lock on PostgreSQL +*Lock on PostgreSQL* Apache Karaf supports PostgreSQL database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.PostgreSQLJDBCLock`: @@ -191,7 +191,7 @@ karaf.lock.jdbc.timeout=0 The PostgreSQL JDBC driver file has to be copied in the `lib/ext` folder. -====== Lock on Microsoft SQLServer +*Lock on Microsoft SQLServer* Apache Karaf supports Microsoft SQLServer database for locking. The lock implementation class name to use is `org.apache.karaf.main.lock.SQLServerJDBCLock`: @@ -211,7 +211,7 @@ karaf.lock.jdbc.timeout=30 The JTDS JDBC driver file has to be copied in the `lib/ext` folder. -===== Container-level locking +====== Container-level locking Apache Karaf supports container-level locking. It allows bundles to be preloaded into the slave instance. Thanks to that, switching to a slave instance is very fast as the slave instance already contains all required bundles. @@ -248,7 +248,7 @@ Using 'hot' standby means that the slave instances are running and bind some por to update the slave configuration to bind the services (ssh, JMX, etc) on different port numbers. ==== -==== Cluster (active/active) +===== Cluster (active/active) Apache Karaf doesn't natively support cluster. By cluster, we mean several active instances, synchronized with each other. http://git-wip-us.apache.org/repos/asf/karaf/blob/c806a6ad/manual/src/main/asciidoc/user-guide/http.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/http.adoc b/manual/src/main/asciidoc/user-guide/http.adoc index f145675..7cedd5f 100644 --- a/manual/src/main/asciidoc/user-guide/http.adoc +++ b/manual/src/main/asciidoc/user-guide/http.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -=== Http Service +==== Http Service The Karaf http feature enables the Pax Web implementation of the OSGi HTTPService. -==== Installing the HTTP feature +===== Installing the HTTP feature ---- root@karaf()> feature:install http @@ -24,7 +24,7 @@ root@karaf()> feature:install http Test the HTTP service is up by pointing your browser to [http://localhost:8181/]. -==== Configuring the HTTPService +===== Configuring the HTTPService By default the HTTPService listens on port 8181 you can change the port by creating a file `etc/org.ops4j.pax.web.cfg` with the following content: @@ -39,11 +39,11 @@ root@karaf> config:property-set -p org.ops4j.pax.web org.osgi.service.http.port If the http feature is already installed the change will take effect immediately. -==== Registering a servlet with the HttpService manually +===== Registering a servlet with the HttpService manually See http://felix.apache.org/site/apache-felix-http-service.html. -==== Using the Pax Web whiteboard extender +===== Using the Pax Web whiteboard extender The Pax Web whiteboard extender is an enhancement of the http feature. So use the following command to install:
