svn commit: r1056318 - /karaf/trunk/manual/src/main/webapp/developers-guide/extending-console.conf

[jb...@apache.org]

Author: jbonofre
Date: Fri Jan  7 13:55:12 2011
New Revision: 1056318

URL: http://svn.apache.org/viewvc?rev=1056318&view=rev
Log:
[KARAF-306] Add documentation showing how to create a command with completer.

Modified:
    karaf/trunk/manual/src/main/webapp/developers-guide/extending-console.conf

Modified: karaf/trunk/manual/src/main/webapp/developers-guide/extending-console.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/developers-guide/extending-console.conf?rev=1056318&r1=1056317&r2=1056318&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/developers-guide/extending-console.conf (original)
+++ karaf/trunk/manual/src/main/webapp/developers-guide/extending-console.conf Fri Jan  7 13:55:12 2011
@@ -222,4 +222,106 @@ karaf@root> test:hello
 Executing Hello command
 {code}
 
+h1. Command completer
 
+A completer allow 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
+
+We add an argument to the HelloCommand:
+
+{code}
+package org.apache.karaf.shell.samples;
+
+import org.apache.felix.gogo.commands.Command;
+import org.apache.felix.gogo.commands.Option;
+import org.apache.felix.gogo.commands.Argument;
+import org.apache.karaf.shell.console.OsgiCommandSupport;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+public class HelloShellCommand extends OsgiCommandSupport {
+
+    @Argument(index = 0, name = "arg", description = "The command argument", required = false, multiValued = false)
+    String arg = null;
+
+    @Override
+    protected Object doExecute() throws Exception {
+        System.out.println("Executing Hello command");
+        return null;
+    }
+}
+{code}
+
+The Blueprint configuration file is the same as previously.
+
+h2. Completer bean
+
+A completer is a bean which implements the Completer interface:
+
+{code}
+package org.apache.karaf.shell.samples;
+
+import org.apache.karaf.shell.console.completer.StringsCompleter;
+import org.apache.karaf.shell.console.Completer;
+
+/**
+ * <p>
+ * A very simple completer.
+ * </p>
+ */
+public class SimpleCompleter implements Completer {
+
+ /**
+  * @param buffer it's the beginning string typed by the user
+  * @param cursor it's the position of the cursor
+  * @param candidates the list of completions proposed to the user
+  */
+ public int complete(String buffer, int cursor, List candidates) {
+  StringsCompleter delegate = new StringsCompleter();
+  delegate.getStrings().add("one");
+  delegate.getStrings().add("two");
+  delegate.getStrings().add("three");
+  return delegate.complete(buffer, cursor, candidates);
+ }
+
+}
+{code}
+
+h2. Blueprint configuration file
+
+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:
+
+{code:lang=xml}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+
+    <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.0.0">
+        <command name="test/hello">
+            <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+        </command>
+        <completers>
+          <ref component-id="simpleCompleter"/>
+          <null/>
+        </completers>
+    </command-bundle>
+
+    <bean id="simpleCompleter" class="org.apache.karaf.shell.samples.SimpleCompleter"/>
+
+</blueprint>
+{code}
+
+h2. Test in Karaf
+
+
+Launch a Karaf instance and run the following command to install the newly created bundle:
+{code}
+karaf@root> osgi: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 <tab>
+ one    two    three
+{code}