Updated Branches: refs/heads/master cc4327856 -> 778745542
[KARAF-2511] Review and update the extending page of the developers guide Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/77874554 Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/77874554 Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/77874554 Branch: refs/heads/master Commit: 77874554296479b17e71041c057c145e1d76c757 Parents: cc43278 Author: Jean-Baptiste Onofré <[email protected]> Authored: Wed Dec 25 07:00:58 2013 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Wed Dec 25 07:00:58 2013 +0100 ---------------------------------------------------------------------- .../main/webapp/developers-guide/extending.conf | 109 +++++++++++-------- 1 file changed, 64 insertions(+), 45 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/77874554/manual/src/main/webapp/developers-guide/extending.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/extending.conf b/manual/src/main/webapp/developers-guide/extending.conf index 5f882a6..8fa46c8 100644 --- a/manual/src/main/webapp/developers-guide/extending.conf +++ b/manual/src/main/webapp/developers-guide/extending.conf @@ -1,19 +1,28 @@ +h1. Extending +Apache Karaf is a very flexible container that you can extend very easily. -h1. Extending the console +h2. Console -This chapter will guide you through the steps needed to extend the console and create a new shell. -We will leverage Maven, Blueprint and OSGi, so you will need some knowledge of those products. +In this section, you will see how to extend the console by adding your own command. -You may also find some information about the console at [http://felix.apache.org/site/rfc-147-overview.html]. +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. -h2. Create the project using maven +h3. Create the Maven project -We first need to create a project using Maven. Let's leverage Maven archetypes for that. +To create the Maven project, we can: -h3. Command line +* use a Maven archetype +* create by hand + +h4. Using archetype + +The Maven Quickstart archetype can create an empty Maven project where you can put your project definition. + +You can directly use: -Using the command line, we can create our project: {code} mvn archetype:create \ -DarchetypeArtifactId=maven-archetype-quickstart \ @@ -22,16 +31,13 @@ mvn archetype:create \ -Dversion=1.0-SNAPSHOT {code} -This generate the main {{pom.xml}} and some additional packages. +It results to a ready to use project, including a {{pom.xml}}. -h3. Interactive shell +You can also use Maven archetype in interactive mode. You will have to answer to some questions used to generate +the project with the {{pom.xml}}: -You can also use the interactive mode for creating the skeleton project: {code} mvn archetype:generate -{code} -Use the following values when prompted: -{code} 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 @@ -39,11 +45,11 @@ Define value for version: 1.0-SNAPSHOT: : Define value for package: : org.apache.karaf.shell.samples {code} -h3. Manual creation +h3. By hand Alternatively, you can simply create the directory {{shell-sample-commands}} and create the {{pom.xml}} file inside it: -{pygmentize:xml} +{code:lang=xml} <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> @@ -90,14 +96,14 @@ Alternatively, you can simply create the directory {{shell-sample-commands}} and </build> </project> -{pygmentize} +{code} -h2. Configuring for Java 6 +h3. Configuring for Java 6/7 -We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.6 to compile the jar. +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. -{pygmentize:xml} +{code:lang=xml} <build> <plugins> <plugin> @@ -110,9 +116,9 @@ Just add the following snippet after the {{dependencies}} section. </plugin> </plugins> </build> -{pygmentize} +{code} -h2. Loading the project in your IDE +h3. Loading the project in your IDE We can use Maven to generate the needed files for your IDE: @@ -127,11 +133,11 @@ mvn idea:idea The project files for your IDE should now be created. Just open the IDE and load the project. -h2. Creating a basic command class +h3. Creating a basic command class We can now create the command class {{HelloShellCommand.java}} -{pygmentize:java} +{code:lang=java} package org.apache.karaf.shell.samples; import Command; @@ -146,11 +152,15 @@ public class HelloShellCommand extends OsgiCommandSupport { return null; } } -{pygmentize} +{code} + +h3. Blueprint definition + +Blueprint is an injection framework for OSGi. It allows you to declare beans in a XML file and contains specific statement for OSGi services. -h2. Creating the associated blueprint configuration files +For the command, we use Blueprint to create the command bean and register as an OSGi service. -The blueprint configuration file will be used to create the command and register it in the OSGi registry, which is the way to make the command available to Karaf console. This blueprint file must be located in the {{OSGI-INF/blueprint/}} directory inside the bundle. +The blueprint definition file is located in the {{OSGI-INF/blueprint}} folder of our bundle. If you don't have the {{src/main/resources}} directory yet, create it. @@ -162,7 +172,7 @@ Then, re-generate the IDE project files and reload it so that this folder is now Inside this directory, create the {{OSGI-INF/blueprint/}} directory and put the following file inside (the name of this file has no impact at all): -{pygmentize:xml} +{code:lang=xml} <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0";> <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0";> @@ -172,9 +182,9 @@ Inside this directory, create the {{OSGI-INF/blueprint/}} directory and put the </command-bundle> </blueprint> -{pygmentize} +{code} -h2. Compiling the jar +h3. 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: @@ -189,32 +199,33 @@ The end of the maven output should look like: [INFO] ------------------------------------------------------------------------ {code} -h2. Test in Karaf +h3. Test + +Launch Apache Karaf and install your bundle: -Launch a Karaf instance and run the following command to install the newly created bundle: {code} -karaf@root> bundles:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT +karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT {code} Let's try running the command: {code} -karaf@root> test:hello +karaf@root()> test:hello Executing Hello command {code} -h1. Command completer +h3. 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. -h2. Command argument +h3. Command argument We add an argument to the HelloCommand: -{code} +{code:lang=java} package org.apache.karaf.shell.samples; import Command; @@ -237,11 +248,11 @@ public class HelloShellCommand extends OsgiCommandSupport { The Blueprint configuration file is the same as previously. -h2. Completer bean +h3. Completer bean A completer is a bean which implements the Completer interface: -{code} +{code:lang=java} package org.apache.karaf.shell.samples; import org.apache.karaf.shell.console.completer.StringsCompleter; @@ -270,7 +281,7 @@ public class SimpleNameCompleter implements Completer { } {code} -h2. Blueprint configuration file +h3. Blueprint with completer Using Blueprint, you can "inject" the completer linked to your command. The same completer could be used for several commands and a command can have several completers: @@ -295,12 +306,12 @@ Using Blueprint, you can "inject" the completer linked to your command. The same You can have multiple completers for a single class, each matching a command argument. The order of the completers must match the order of the arguments, in order to have the desirable results. -h2. Completers for option values +h3. 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. -{code} +{code:lang=java} package org.apache.karaf.shell.samples; import Command; @@ -349,7 +360,8 @@ blueprint configuration that will associate a completer with the -g option or it </blueprint> {code} -h2. Completers with state. +h3. 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 command which will provide auto completion for only for the properties of the pid specified by a previously issued config:edit @@ -369,11 +381,12 @@ If you want to get access to the list of arguments that is already passed to the ArgumentCompleter.ArgumentList list = (ArgumentCompleter.ArgumentList) commandSession.get(ArgumentCompleter.ARGUMENTS_LIST); {code} -h2. Test in Karaf +h3. Test Launch a Karaf instance and run the following command to install the newly created bundle: + {code} -karaf@root> bundles:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT +karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT {code} Let's try running the command: @@ -382,3 +395,9 @@ Let's try running the command: karaf@root> test:hello <tab> one two three {code} + +h2. WebConsole + +You can also extend the Apache Karaf WebConsole by providing and installing a webconsole plugin.o + +A plugin is an OSGi bundle that register a Servlet as an OSGi service with some webconsole properties.
