You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/12/23 15:23:54 UTC
git commit: [KARAF-2511] Start to review and update the developers
guide
Updated Branches:
refs/heads/master 70824cc9f -> 56739bd09
[KARAF-2511] Start to review and update 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/56739bd0
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/56739bd0
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/56739bd0
Branch: refs/heads/master
Commit: 56739bd095c0cf47cf56625c42f77ae64bf5270e
Parents: 70824cc
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Mon Dec 23 15:23:03 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Mon Dec 23 15:23:03 2013 +0100
----------------------------------------------------------------------
.../developers-guide/branding-console.conf | 115 ------
.../main/webapp/developers-guide/branding.conf | 115 ++++++
.../developers-guide/connect-console.conf | 53 ---
.../main/webapp/developers-guide/connect.conf | 53 +++
.../developers-guide/extending-console.conf | 384 -------------------
.../main/webapp/developers-guide/extending.conf | 384 +++++++++++++++++++
.../src/main/webapp/developers-guide/index.conf | 24 +-
.../main/webapp/developers-guide/scripting.conf | 171 +++++++++
.../webapp/developers-guide/shell-syntax.conf | 171 ---------
manual/src/main/webapp/overview.conf | 34 +-
manual/src/main/webapp/users-guide/console.conf | 2 +
.../src/main/webapp/users-guide/features.conf | 51 ++-
12 files changed, 792 insertions(+), 765 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/branding-console.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/branding-console.conf b/manual/src/main/webapp/developers-guide/branding-console.conf
deleted file mode 100644
index bb7e065..0000000
--- a/manual/src/main/webapp/developers-guide/branding-console.conf
+++ /dev/null
@@ -1,115 +0,0 @@
-
-
-h1. Branding the Console
-
-This chapter will show you how to customize the user interface of the Karaf console, making changes such as a new
-welcome message and console prompt. This is what we refer to as "branding" Karaf.
-
-By branding, it means that you can define your own welcome message and console prompt.
-
-h2. Create your branding bundle
-
-At startup, Karaf is looking for a bundle which exports the {{org.apache.karaf.branding}} package containing a
-{{branding.properties}} file.
-
-So you need to create a very simply bundle containing just a {{org/apache/karaf/branding/branding.properties}} file.
-
-The Maven POM of your branding bundle should look like this:
-
-{code:lang=xml}
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>your.group.id</groupId>
- <artifactId>your.branding.artifact.id</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>bundle</packaging>
- <name>Your Branding Bundle Name</name>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <version>2.2</version>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-SymbolicName>${project.artifactId}</bundle-SymbolicName>
- <Import-Package>*</Import-Package>
- <Private-Package>!*</Private-Package>
- <Export-Package>
- org.apache.karaf.branding
- </Export-Package>
- <Spring-Context>*;public-context:=false</Spring-Context>
- </instructions>
- </configuration>
- </plugin>
- </plugins>
- </build>
-
-</project>
-{code}
-
-Now, add a {{src/main/resources/org/apache/karaf/branding/branding.properties}} similar to:
-
-{{code}}
-welcome = \
-\u001B[36m __ __ ____ \u001B[0m\r\n\
-\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\
-\u001B[36m / ,< / __ `/ ___/ __ `/ /_ \u001B[0m\r\n\
-\u001B[36m / /| |/ /_/ / / / /_/ / __/ \u001B[0m\r\n\
-\u001B[36m /_/ |_|\\__,_/_/ \\__,_/_/ \u001B[0m\r\n\
-\r\n\
-\u001B[1m Apache Karaf\u001B[0m (${project.version})\r\n\
-\r\n\
-Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
- and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
-Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1msystem:shutdown\u001B[0m' to shutdown Karaf.\r\n
-
-prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m>
-{{code}}
-
-As you can see, the {{branding.properties}} contains two properties:
-* welcome is the welcome message displayed when you start Karaf.
-* prompt is the string used to display the console prompt. This string supports variables:
-** ${USER}} defines the user name of the prompt. Caveat -- the user name is presently static and hardcoded to "karaf",
-however you can override here with your own static user name.
-** ${{APPLICATION}} defines the Karaf instance name.
-
-As you can see, both strings support ASCII escaped format. For instance \u001B[1m switches the foreground in bold
-and \u001B[0m switch back to normal.
-
-Some examples of customized prompt examples follow:
-
-{code}
-# Define a user with fancy colors
-prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m>
-{code}
-
-{code}
-# Static sober prompt
-prompt = my-user@my-karaf>
-{code}
-
-h2. Configuring Karaf to use the branding bundle
-
-In order for Karaf to pick up the branding jar please edit the
-$KARAF_HOME/etc/custom.properties file to include the following:
-
- org.osgi.framework.system.packages.extra = \
- org.apache.karaf.branding
-
-h2. Installing the branding bundle
-
-Build your branding bundle:
-
-{code}
-mvn install
-{code}
-
-and simply drop the generated jar file into the Karaf lib directory.
-
-Start Karaf and you will see your branded Karaf console.
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/branding.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/branding.conf b/manual/src/main/webapp/developers-guide/branding.conf
new file mode 100644
index 0000000..bb7e065
--- /dev/null
+++ b/manual/src/main/webapp/developers-guide/branding.conf
@@ -0,0 +1,115 @@
+
+
+h1. Branding the Console
+
+This chapter will show you how to customize the user interface of the Karaf console, making changes such as a new
+welcome message and console prompt. This is what we refer to as "branding" Karaf.
+
+By branding, it means that you can define your own welcome message and console prompt.
+
+h2. Create your branding bundle
+
+At startup, Karaf is looking for a bundle which exports the {{org.apache.karaf.branding}} package containing a
+{{branding.properties}} file.
+
+So you need to create a very simply bundle containing just a {{org/apache/karaf/branding/branding.properties}} file.
+
+The Maven POM of your branding bundle should look like this:
+
+{code:lang=xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>your.group.id</groupId>
+ <artifactId>your.branding.artifact.id</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>bundle</packaging>
+ <name>Your Branding Bundle Name</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <version>2.2</version>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Bundle-SymbolicName>${project.artifactId}</bundle-SymbolicName>
+ <Import-Package>*</Import-Package>
+ <Private-Package>!*</Private-Package>
+ <Export-Package>
+ org.apache.karaf.branding
+ </Export-Package>
+ <Spring-Context>*;public-context:=false</Spring-Context>
+ </instructions>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
+{code}
+
+Now, add a {{src/main/resources/org/apache/karaf/branding/branding.properties}} similar to:
+
+{{code}}
+welcome = \
+\u001B[36m __ __ ____ \u001B[0m\r\n\
+\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\
+\u001B[36m / ,< / __ `/ ___/ __ `/ /_ \u001B[0m\r\n\
+\u001B[36m / /| |/ /_/ / / / /_/ / __/ \u001B[0m\r\n\
+\u001B[36m /_/ |_|\\__,_/_/ \\__,_/_/ \u001B[0m\r\n\
+\r\n\
+\u001B[1m Apache Karaf\u001B[0m (${project.version})\r\n\
+\r\n\
+Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
+ and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
+Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1msystem:shutdown\u001B[0m' to shutdown Karaf.\r\n
+
+prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m>
+{{code}}
+
+As you can see, the {{branding.properties}} contains two properties:
+* welcome is the welcome message displayed when you start Karaf.
+* prompt is the string used to display the console prompt. This string supports variables:
+** ${USER}} defines the user name of the prompt. Caveat -- the user name is presently static and hardcoded to "karaf",
+however you can override here with your own static user name.
+** ${{APPLICATION}} defines the Karaf instance name.
+
+As you can see, both strings support ASCII escaped format. For instance \u001B[1m switches the foreground in bold
+and \u001B[0m switch back to normal.
+
+Some examples of customized prompt examples follow:
+
+{code}
+# Define a user with fancy colors
+prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m>
+{code}
+
+{code}
+# Static sober prompt
+prompt = my-user@my-karaf>
+{code}
+
+h2. Configuring Karaf to use the branding bundle
+
+In order for Karaf to pick up the branding jar please edit the
+$KARAF_HOME/etc/custom.properties file to include the following:
+
+ org.osgi.framework.system.packages.extra = \
+ org.apache.karaf.branding
+
+h2. Installing the branding bundle
+
+Build your branding bundle:
+
+{code}
+mvn install
+{code}
+
+and simply drop the generated jar file into the Karaf lib directory.
+
+Start Karaf and you will see your branded Karaf console.
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/connect-console.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/connect-console.conf b/manual/src/main/webapp/developers-guide/connect-console.conf
deleted file mode 100644
index 0253960..0000000
--- a/manual/src/main/webapp/developers-guide/connect-console.conf
+++ /dev/null
@@ -1,53 +0,0 @@
-
-
-h1. Programmatically connect to the console
-
-A connection to the Karaf console can also be done programmatically.
-The following code is a simplified version of the code from the client library.
-
-{pygmentize:java}
-import org.apache.sshd.ClientChannel;
-import org.apache.sshd.ClientSession;
-import org.apache.sshd.SshClient;
-import org.apache.sshd.client.future.ConnectFuture;
-
-public class Main {
-
- public static void main(String[] args) throws Exception {
- String host = "localhost";
- int port = 8101;
- String user = "karaf";
- String password = "karaf";
-
- SshClient client = null;
- try {
- client = SshClient.setUpDefaultClient();
- client.start();
- ConnectFuture future = client.connect(host, port);
- future.await();
- ClientSession session = future.getSession();
- session.authPassword(user, password);
- ClientChannel channel = session.createChannel("shell");
- channel.setIn(System.in);
- channel.setOut(System.out);
- channel.setErr(System.err);
- channel.open();
- channel.waitFor(ClientChannel.CLOSED, 0);
- } catch (Throwable t) {
- t.printStackTrace();
- System.exit(1);
- } finally {
- try {
- client.stop();
- } catch (Throwable t) { }
- }
- System.exit(0);
- }
-
-}
-{pygmentize}
-
-You can find a more complete example at the [following location|http://svn.apache.org/repos/asf/karaf/trunk/client/src/main/java/org/apache/karaf/client/Main.java].
-
-
-
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/connect.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/connect.conf b/manual/src/main/webapp/developers-guide/connect.conf
new file mode 100644
index 0000000..0253960
--- /dev/null
+++ b/manual/src/main/webapp/developers-guide/connect.conf
@@ -0,0 +1,53 @@
+
+
+h1. Programmatically connect to the console
+
+A connection to the Karaf console can also be done programmatically.
+The following code is a simplified version of the code from the client library.
+
+{pygmentize:java}
+import org.apache.sshd.ClientChannel;
+import org.apache.sshd.ClientSession;
+import org.apache.sshd.SshClient;
+import org.apache.sshd.client.future.ConnectFuture;
+
+public class Main {
+
+ public static void main(String[] args) throws Exception {
+ String host = "localhost";
+ int port = 8101;
+ String user = "karaf";
+ String password = "karaf";
+
+ SshClient client = null;
+ try {
+ client = SshClient.setUpDefaultClient();
+ client.start();
+ ConnectFuture future = client.connect(host, port);
+ future.await();
+ ClientSession session = future.getSession();
+ session.authPassword(user, password);
+ ClientChannel channel = session.createChannel("shell");
+ channel.setIn(System.in);
+ channel.setOut(System.out);
+ channel.setErr(System.err);
+ channel.open();
+ channel.waitFor(ClientChannel.CLOSED, 0);
+ } catch (Throwable t) {
+ t.printStackTrace();
+ System.exit(1);
+ } finally {
+ try {
+ client.stop();
+ } catch (Throwable t) { }
+ }
+ System.exit(0);
+ }
+
+}
+{pygmentize}
+
+You can find a more complete example at the [following location|http://svn.apache.org/repos/asf/karaf/trunk/client/src/main/java/org/apache/karaf/client/Main.java].
+
+
+
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/extending-console.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/extending-console.conf b/manual/src/main/webapp/developers-guide/extending-console.conf
deleted file mode 100644
index 5f882a6..0000000
--- a/manual/src/main/webapp/developers-guide/extending-console.conf
+++ /dev/null
@@ -1,384 +0,0 @@
-
-
-h1. Extending the 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.
-
-You may also find some information about the console at [http://felix.apache.org/site/rfc-147-overview.html].
-
-h2. Create the project using maven
-
-We first need to create a project using Maven. Let's leverage Maven archetypes for that.
-
-h3. Command line
-
-Using the command line, we can create our project:
-{code}
-mvn archetype:create \
- -DarchetypeArtifactId=maven-archetype-quickstart \
- -DgroupId=org.apache.karaf.shell.samples \
- -DartifactId=shell-sample-commands \
- -Dversion=1.0-SNAPSHOT
-{code}
-
-This generate the main {{pom.xml}} and some additional packages.
-
-h3. Interactive shell
-
-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
-Define value for version: 1.0-SNAPSHOT: :
-Define value for package: : org.apache.karaf.shell.samples
-{code}
-
-h3. Manual creation
-
-Alternatively, you can simply create the directory {{shell-sample-commands}} and create the {{pom.xml}} file inside it:
-
-{pygmentize: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>
-
- <groupId>org.apache.karaf.shell.samples</groupId>
- <artifactId>shell-sample-commands<artifactId>
- <packaging>bundle</packaging>
- <version>1.0-SNAPSHOT</version>
- <name>shell-sample-commmands</name>
-
-
- <dependencies>
- <dependency>
- <groupId>org.apache.karaf.shell</groupId>
- <artifactId>org.apache.karaf.shell.console</artifactId>
- <version>${project.version}</version>
- </dependency>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>3.8.1</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <version>${felix.plugin.version}</version>
- <configuration>
- <instructions>
- <Import-Package>
- org.apache.felix.service.command,
- org.apache.karaf.shell.commands,
- org.apache.karaf.shell.console,
- *
- </Import-Package>
- </instructions>
- </configuration>
- </plugin>
- </plugins>
- </build>
-
-</project>
-{pygmentize}
-
-h2. Configuring for Java 6
-
-We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.6 to compile the jar.
-Just add the following snippet after the {{dependencies}} section.
-
-{pygmentize:xml}
-<build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <configuration>
- <target>1.6</target>
- <source>1.6</source>
- </configuration>
- </plugin>
- </plugins>
-</build>
-{pygmentize}
-
-h2. Loading the project in your IDE
-
-We can use Maven to generate the needed files for your IDE:
-
-Inside the project, run the following command
-{code}
-mvn eclipse:eclipse
-{code}
-or
-{code}
-mvn idea:idea
-{code}
-
-The project files for your IDE should now be created. Just open the IDE and load the project.
-
-h2. Creating a basic command class
-
-We can now create the command class {{HelloShellCommand.java}}
-
-{pygmentize:java}
-package org.apache.karaf.shell.samples;
-
-import Command;
-import org.apache.karaf.shell.console.OsgiCommandSupport;
-
-@Command(scope = "test", name = "hello", description="Says hello")
-public class HelloShellCommand extends OsgiCommandSupport {
-
- @Override
- protected Object doExecute() throws Exception {
- System.out.println("Executing Hello command");
- return null;
- }
-}
-{pygmentize}
-
-h2. Creating the associated blueprint configuration files
-
-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.
-
-If you don't have the {{src/main/resources}} directory yet, create it.
-
-{code}
-mkdir src/main/resources
-{code}
-
-Then, re-generate the IDE project files and reload it so that this folder is now recognized as a source folder.
-
-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}
-<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
-
- <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
- <command>
- <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
- </command>
- </command-bundle>
-
-</blueprint>
-{pygmentize}
-
-h2. Compiling the jar
-
-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:
-
-{code}
-mvn install
-{code}
-
-The end of the maven output should look like:
-{code}
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESSFUL
-[INFO] ------------------------------------------------------------------------
-{code}
-
-h2. Test in Karaf
-
-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
-{code}
-
-Let's try running the command:
-
-{code}
-karaf@root> test:hello
-Executing Hello command
-{code}
-
-h1. 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
-
-We add an argument to the HelloCommand:
-
-{code}
-package org.apache.karaf.shell.samples;
-
-import Command;
-import 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 = "name", description = "The name that sends the greet.", required = true, multiValued = false)
- String name = null;
-
- @Override
- protected Object doExecute() throws Exception {
- System.out.println("Hello " + name);
- 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 SimpleNameCompleter implements Completer {
-
- /**
- * @param buffer the beginning string typed by the user
- * @param cursor the position of the cursor
- * @param candidates the list of completions proposed to the user
- */
- public int complete(String buffer, int cursor, List candidates) {
- StringsCompleter delegate = new StringsCompleter();
- delegate.getStrings().add("Mike");
- delegate.getStrings().add("Eric");
- delegate.getStrings().add("Jenny");
- 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.1.0">
- <command>
- <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
- <completers>
- <ref component-id="simpleNameCompleter"/>
- <null/>
- </completers>
- </command>
- </command-bundle>
-
- <bean id="simpleNameCompleter" class="org.apache.karaf.shell.samples.SimpleNameCompleter"/>
-
-</blueprint>
-{code}
-
-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
-
-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}
-package org.apache.karaf.shell.samples;
-
-import Command;
-import 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 = "name", description = "The name that sends the greet.", required = true, multiValued = false)
- String name = null;
-
- @Option(name = "-g", aliases = "--greet", description = "The configuration pid", required = false, multiValued = false)
- String greet = "Hello;
-
- @Override
- protected Object doExecute() throws Exception {
- System.out.println(greet + " " + name);
- return null;
- }
-}
-{code}
-
-We can now specify a completer for the greet option. All that is required is to add an optional-completer element in the
-blueprint configuration that will associate a completer with the -g option or its --greet alias.
-
-{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">
- <command>
- <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
- <completers>
- <ref component-id="simpleNameCompleter"/>
- <null/>
- </completers>
- <optional-completers>
- <entry key="-g" value-ref="greetCompleter"/>
- </optional-completers>
- </command>
- </command-bundle>
-
- <bean id="simpleNameCompleter" class="org.apache.karaf.shell.samples.SimpleNameCompleter"/>
- <bean id="greetCompleter" class="org.apache.karaf.shell.samples.GreetCompleter"/>
-
-</blueprint>
-{code}
-
-h2. 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
-command or by the option --pid.
-
-This is done by accessing the CommandSession object which holds the state of the console. To get access to the CommandSession:
-
-{code}
-CommandSession session = CommandSessionHolder.getSession();
-{code}
-
-CommandSession provides map like methods for storing key/value pairs and can be used to put/get the state.
-
-If you want to get access to the list of arguments that is already passed to the command, you can simply:
-
-{code}
-ArgumentCompleter.ArgumentList list = (ArgumentCompleter.ArgumentList) commandSession.get(ArgumentCompleter.ARGUMENTS_LIST);
-{code}
-
-h2. Test in Karaf
-
-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
-{code}
-
-Let's try running the command:
-
-{code}
-karaf@root> test:hello <tab>
- one two three
-{code}
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/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
new file mode 100644
index 0000000..5f882a6
--- /dev/null
+++ b/manual/src/main/webapp/developers-guide/extending.conf
@@ -0,0 +1,384 @@
+
+
+h1. Extending the 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.
+
+You may also find some information about the console at [http://felix.apache.org/site/rfc-147-overview.html].
+
+h2. Create the project using maven
+
+We first need to create a project using Maven. Let's leverage Maven archetypes for that.
+
+h3. Command line
+
+Using the command line, we can create our project:
+{code}
+mvn archetype:create \
+ -DarchetypeArtifactId=maven-archetype-quickstart \
+ -DgroupId=org.apache.karaf.shell.samples \
+ -DartifactId=shell-sample-commands \
+ -Dversion=1.0-SNAPSHOT
+{code}
+
+This generate the main {{pom.xml}} and some additional packages.
+
+h3. Interactive shell
+
+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
+Define value for version: 1.0-SNAPSHOT: :
+Define value for package: : org.apache.karaf.shell.samples
+{code}
+
+h3. Manual creation
+
+Alternatively, you can simply create the directory {{shell-sample-commands}} and create the {{pom.xml}} file inside it:
+
+{pygmentize: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>
+
+ <groupId>org.apache.karaf.shell.samples</groupId>
+ <artifactId>shell-sample-commands<artifactId>
+ <packaging>bundle</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>shell-sample-commmands</name>
+
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.karaf.shell</groupId>
+ <artifactId>org.apache.karaf.shell.console</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <version>${felix.plugin.version}</version>
+ <configuration>
+ <instructions>
+ <Import-Package>
+ org.apache.felix.service.command,
+ org.apache.karaf.shell.commands,
+ org.apache.karaf.shell.console,
+ *
+ </Import-Package>
+ </instructions>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
+{pygmentize}
+
+h2. Configuring for Java 6
+
+We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.6 to compile the jar.
+Just add the following snippet after the {{dependencies}} section.
+
+{pygmentize:xml}
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <target>1.6</target>
+ <source>1.6</source>
+ </configuration>
+ </plugin>
+ </plugins>
+</build>
+{pygmentize}
+
+h2. Loading the project in your IDE
+
+We can use Maven to generate the needed files for your IDE:
+
+Inside the project, run the following command
+{code}
+mvn eclipse:eclipse
+{code}
+or
+{code}
+mvn idea:idea
+{code}
+
+The project files for your IDE should now be created. Just open the IDE and load the project.
+
+h2. Creating a basic command class
+
+We can now create the command class {{HelloShellCommand.java}}
+
+{pygmentize:java}
+package org.apache.karaf.shell.samples;
+
+import Command;
+import org.apache.karaf.shell.console.OsgiCommandSupport;
+
+@Command(scope = "test", name = "hello", description="Says hello")
+public class HelloShellCommand extends OsgiCommandSupport {
+
+ @Override
+ protected Object doExecute() throws Exception {
+ System.out.println("Executing Hello command");
+ return null;
+ }
+}
+{pygmentize}
+
+h2. Creating the associated blueprint configuration files
+
+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.
+
+If you don't have the {{src/main/resources}} directory yet, create it.
+
+{code}
+mkdir src/main/resources
+{code}
+
+Then, re-generate the IDE project files and reload it so that this folder is now recognized as a source folder.
+
+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}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+
+ <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.1.0">
+ <command>
+ <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+ </command>
+ </command-bundle>
+
+</blueprint>
+{pygmentize}
+
+h2. Compiling the jar
+
+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:
+
+{code}
+mvn install
+{code}
+
+The end of the maven output should look like:
+{code}
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+{code}
+
+h2. Test in Karaf
+
+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
+{code}
+
+Let's try running the command:
+
+{code}
+karaf@root> test:hello
+Executing Hello command
+{code}
+
+h1. 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
+
+We add an argument to the HelloCommand:
+
+{code}
+package org.apache.karaf.shell.samples;
+
+import Command;
+import 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 = "name", description = "The name that sends the greet.", required = true, multiValued = false)
+ String name = null;
+
+ @Override
+ protected Object doExecute() throws Exception {
+ System.out.println("Hello " + name);
+ 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 SimpleNameCompleter implements Completer {
+
+ /**
+ * @param buffer the beginning string typed by the user
+ * @param cursor the position of the cursor
+ * @param candidates the list of completions proposed to the user
+ */
+ public int complete(String buffer, int cursor, List candidates) {
+ StringsCompleter delegate = new StringsCompleter();
+ delegate.getStrings().add("Mike");
+ delegate.getStrings().add("Eric");
+ delegate.getStrings().add("Jenny");
+ 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.1.0">
+ <command>
+ <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+ <completers>
+ <ref component-id="simpleNameCompleter"/>
+ <null/>
+ </completers>
+ </command>
+ </command-bundle>
+
+ <bean id="simpleNameCompleter" class="org.apache.karaf.shell.samples.SimpleNameCompleter"/>
+
+</blueprint>
+{code}
+
+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
+
+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}
+package org.apache.karaf.shell.samples;
+
+import Command;
+import 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 = "name", description = "The name that sends the greet.", required = true, multiValued = false)
+ String name = null;
+
+ @Option(name = "-g", aliases = "--greet", description = "The configuration pid", required = false, multiValued = false)
+ String greet = "Hello;
+
+ @Override
+ protected Object doExecute() throws Exception {
+ System.out.println(greet + " " + name);
+ return null;
+ }
+}
+{code}
+
+We can now specify a completer for the greet option. All that is required is to add an optional-completer element in the
+blueprint configuration that will associate a completer with the -g option or its --greet alias.
+
+{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">
+ <command>
+ <action class="org.apache.karaf.shell.samples.HelloShellCommand"/>
+ <completers>
+ <ref component-id="simpleNameCompleter"/>
+ <null/>
+ </completers>
+ <optional-completers>
+ <entry key="-g" value-ref="greetCompleter"/>
+ </optional-completers>
+ </command>
+ </command-bundle>
+
+ <bean id="simpleNameCompleter" class="org.apache.karaf.shell.samples.SimpleNameCompleter"/>
+ <bean id="greetCompleter" class="org.apache.karaf.shell.samples.GreetCompleter"/>
+
+</blueprint>
+{code}
+
+h2. 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
+command or by the option --pid.
+
+This is done by accessing the CommandSession object which holds the state of the console. To get access to the CommandSession:
+
+{code}
+CommandSession session = CommandSessionHolder.getSession();
+{code}
+
+CommandSession provides map like methods for storing key/value pairs and can be used to put/get the state.
+
+If you want to get access to the list of arguments that is already passed to the command, you can simply:
+
+{code}
+ArgumentCompleter.ArgumentList list = (ArgumentCompleter.ArgumentList) commandSession.get(ArgumentCompleter.ARGUMENTS_LIST);
+{code}
+
+h2. Test in Karaf
+
+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
+{code}
+
+Let's try running the command:
+
+{code}
+karaf@root> test:hello <tab>
+ one two three
+{code}
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/index.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/index.conf b/manual/src/main/webapp/developers-guide/index.conf
index c168d87..36c7dac 100644
--- a/manual/src/main/webapp/developers-guide/index.conf
+++ b/manual/src/main/webapp/developers-guide/index.conf
@@ -1,17 +1,19 @@
h1. Developers Guide
-* [Connect to the Console|connect-console]
-* [Branding the Console|branding-console]
-* [Maven Archetypes|archetypes]
-* [Extending the Console|extending-console]
-* [Custom Distribution|custom-distribution]
-* [Security Framework|security-framework]
-* [Using the karaf-maven-plugin|karaf-maven-plugin]
-* [Troubleshooting, Debugging, Profiling, and Monitoring|debugging]
* [Developer commands|developer-commands]
-* [Programmatically connect to the console|connect-console]
-* [Writing integration tests|writing-tests]
-* [Creating bundles|creating-bundles]
+* [Scripting|scripting]
+* [Programmatically connect|connect]
+* [Branding|branding]
+* [Extending|extending]
+* [Karaf Maven plugin|karaf-maven-plugin]
+* [Custom distribution|custom-distribution]
* [OSGi services|services]
+* [Create OSGi bundle|creating-bundles]
+* [Blueprint|blueprint]
+* [CDI|cdi]
+* [Maven Archetypes|archetypes]
+* [Security Framework|security-framework]
+* [Troubleshooting, Debugging, Profiling|debugging]
+* [Integration testing|writing-tests]
* [Shell syntax|shell-syntax]
* [Github Contributions|github-contributions]
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/scripting.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/scripting.conf b/manual/src/main/webapp/developers-guide/scripting.conf
new file mode 100644
index 0000000..fc574b2
--- /dev/null
+++ b/manual/src/main/webapp/developers-guide/scripting.conf
@@ -0,0 +1,171 @@
+h1. Shell syntax
+
+h2. Easy to use interactively - no unnecessary syntax
+
+{code}
+// simple command
+karaf@root> echo hello world
+hello world
+
+// session variables
+karaf@root> msg = "hello world"
+hello world
+karaf@root> echo $msg
+hello world
+
+// execution quotes () - similar to bash backquotes
+karaf@root> ($.context bundle 1) location
+mvn:org.ops4j.pax.url/pax-url-mvn/1.1.3
+{code}
+
+h2. List, maps, pipes and closures
+
+{code}
+// lists - []
+karaf@root> list = [1 2 a b]
+1
+2
+a
+b
+
+karaf@root> map = [Jan=1 Feb=2 Mar=3]
+Jan 1
+Feb 2
+Mar 3
+
+// pipes
+karaf@root> ($.context bundles) | grep felix
+000000 ACT org.apache.felix.framework-3.0.2
+000005 ACT org.apache.felix.configadmin-1.2.4
+000006 ACT org.apache.felix.fileinstall-3.0.2
+
+// closures - {}
+karaf@root> echo2 = { echo xxx $args yyy }
+echo xxx $args yyy
+karaf@root> echo2 hello world
+xxx hello world yyy
+{code}
+
+h2. Startup scripts
+
+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.
+
+h2. Constants and variables
+
+The following constants can be used
+ * *{{$.context}}* to access a bundle context
+ * *{{$.variables}}* to access the list of defined variables
+ * *{{$.commands}}* to access the list of defined commands
+
+Variables starting with a '#' that are defined as Function (such as closures) will be executed automatically:
+{code}
+karaf@root> \#inc = { var = "${var}i" ; $var }
+var = "${var}i" ; $var
+karaf@root> echo $inc
+i
+karaf@root> echo $inc
+ii
+karaf@root>
+{code}
+
+h2. Scripting
+
+The following built-in variables are available for scripting:
+ * *{{$args}}* to retrieve the list of parameters given to the closure being executed
+ * *{{$1 .. $999}}* to retrieve the nth argument of the closure
+ * *{{$it}}* (same as {{$1}}) but usually used within a loop to access the iterator value
+
+The {{shell}} scope contains very useful command for scripting such as {{if}}, {{new}}, {{each}}.
+
+h2. Leverages existing Java capabilities, via reflection
+
+{code}
+// exception handling - console shows summary, but full context available
+karaf@root> ($.context bundle) loadClass foo
+Error executing command: foo not found by org.apache.karaf.shell.console [17]
+karaf@root> $karaf.lastException printStackTrace
+java.lang.ClassNotFoundException: foo not found by org.apache.karaf.shell.console [17]
+ at org.apache.felix.framework.BundleWiringImpl.findClassOrResourceByDelegation(BundleWiringImpl.java:1460)
+ at org.apache.felix.framework.BundleWiringImpl.access$400(BundleWiringImpl.java:72)
+ at org.apache.felix.framework.BundleWiringImpl$BundleClassLoader.loadClass(BundleWiringImpl.java:1843)
+ at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
+ at org.apache.felix.framework.Felix.loadBundleClass(Felix.java:1723)
+ at org.apache.felix.framework.BundleImpl.loadClass(BundleImpl.java:926)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:597)
+ at org.apache.felix.gogo.runtime.Reflective.invoke(Reflective.java:137)
+ at org.apache.felix.gogo.runtime.Closure.executeMethod(Closure.java:527)
+ at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:403)
+ at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108)
+ at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183)
+ at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120)
+ at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89)
+ at org.apache.karaf.shell.console.jline.Console.run(Console.java:166)
+ at java.lang.Thread.run(Thread.java:680)
+
+// add all public methods on java.lang.System as commands:
+karaf@root> addcommand system (($.context bundle) loadClass java.lang.System)
+karaf@root> system:getproperty karaf.name
+root
+
+// create new objects
+karaf@root> map = (new java.util.HashMap)
+karaf@root> $map put 0 0
+karaf@root> $map
+0 0
+{code}
+
+h2. Real examples
+
+{code}
+#
+# Add a value at the end of a property in the given OSGi configuration
+#
+# For example:
+# > config-add-to-list org.ops4j.pax.url.mvn org.ops4j.pax.url.mvn.repositories http://scala-tools.org/repo-releases
+#
+config-add-to-list = {
+ config:edit $1 ;
+ a = (config:proplist | grep --color never $2 | tac) ;
+ b = (echo $a | grep --color never "\b$3\b" | tac) ;
+ if { ($b trim) isEmpty } {
+ if { $a isEmpty } {
+ config:propset $2 $3
+ } {
+ config:propappend $2 ", $3"
+ } ;
+ config:update
+ } {
+ config:cancel
+ }
+}
+{code}
+
+{code}
+#
+# Wait for the given OSGi service to be available
+#
+wait-for-service-timeout = {
+ _filter = $.context createFilter $1 ;
+ _tracker = shell:new org.osgi.util.tracker.ServiceTracker $.context $_filter null ;
+ $_tracker open ;
+ _service = $_tracker waitForService $2 ;
+ $_tracker close
+}
+#
+# Wait for the given OSGi service to be available with a timeout of 10 seconds
+#
+wait-for-service = {
+ wait-for-service-timeout $1 10000
+}
+#
+# Wait for the given command to be available with a timeout of 10 seconds
+# For example:
+# > wait-for-command dev watch
+#
+wait-for-command = {
+ wait-for-service "(&(objectClass=org.apache.felix.service.command.Function)(osgi.command.scope=$1)(osgi.command.function=$2))"
+}
+{code}
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/developers-guide/shell-syntax.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/shell-syntax.conf b/manual/src/main/webapp/developers-guide/shell-syntax.conf
deleted file mode 100644
index fc574b2..0000000
--- a/manual/src/main/webapp/developers-guide/shell-syntax.conf
+++ /dev/null
@@ -1,171 +0,0 @@
-h1. Shell syntax
-
-h2. Easy to use interactively - no unnecessary syntax
-
-{code}
-// simple command
-karaf@root> echo hello world
-hello world
-
-// session variables
-karaf@root> msg = "hello world"
-hello world
-karaf@root> echo $msg
-hello world
-
-// execution quotes () - similar to bash backquotes
-karaf@root> ($.context bundle 1) location
-mvn:org.ops4j.pax.url/pax-url-mvn/1.1.3
-{code}
-
-h2. List, maps, pipes and closures
-
-{code}
-// lists - []
-karaf@root> list = [1 2 a b]
-1
-2
-a
-b
-
-karaf@root> map = [Jan=1 Feb=2 Mar=3]
-Jan 1
-Feb 2
-Mar 3
-
-// pipes
-karaf@root> ($.context bundles) | grep felix
-000000 ACT org.apache.felix.framework-3.0.2
-000005 ACT org.apache.felix.configadmin-1.2.4
-000006 ACT org.apache.felix.fileinstall-3.0.2
-
-// closures - {}
-karaf@root> echo2 = { echo xxx $args yyy }
-echo xxx $args yyy
-karaf@root> echo2 hello world
-xxx hello world yyy
-{code}
-
-h2. Startup scripts
-
-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.
-
-h2. Constants and variables
-
-The following constants can be used
- * *{{$.context}}* to access a bundle context
- * *{{$.variables}}* to access the list of defined variables
- * *{{$.commands}}* to access the list of defined commands
-
-Variables starting with a '#' that are defined as Function (such as closures) will be executed automatically:
-{code}
-karaf@root> \#inc = { var = "${var}i" ; $var }
-var = "${var}i" ; $var
-karaf@root> echo $inc
-i
-karaf@root> echo $inc
-ii
-karaf@root>
-{code}
-
-h2. Scripting
-
-The following built-in variables are available for scripting:
- * *{{$args}}* to retrieve the list of parameters given to the closure being executed
- * *{{$1 .. $999}}* to retrieve the nth argument of the closure
- * *{{$it}}* (same as {{$1}}) but usually used within a loop to access the iterator value
-
-The {{shell}} scope contains very useful command for scripting such as {{if}}, {{new}}, {{each}}.
-
-h2. Leverages existing Java capabilities, via reflection
-
-{code}
-// exception handling - console shows summary, but full context available
-karaf@root> ($.context bundle) loadClass foo
-Error executing command: foo not found by org.apache.karaf.shell.console [17]
-karaf@root> $karaf.lastException printStackTrace
-java.lang.ClassNotFoundException: foo not found by org.apache.karaf.shell.console [17]
- at org.apache.felix.framework.BundleWiringImpl.findClassOrResourceByDelegation(BundleWiringImpl.java:1460)
- at org.apache.felix.framework.BundleWiringImpl.access$400(BundleWiringImpl.java:72)
- at org.apache.felix.framework.BundleWiringImpl$BundleClassLoader.loadClass(BundleWiringImpl.java:1843)
- at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
- at org.apache.felix.framework.Felix.loadBundleClass(Felix.java:1723)
- at org.apache.felix.framework.BundleImpl.loadClass(BundleImpl.java:926)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:597)
- at org.apache.felix.gogo.runtime.Reflective.invoke(Reflective.java:137)
- at org.apache.felix.gogo.runtime.Closure.executeMethod(Closure.java:527)
- at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:403)
- at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108)
- at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183)
- at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120)
- at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89)
- at org.apache.karaf.shell.console.jline.Console.run(Console.java:166)
- at java.lang.Thread.run(Thread.java:680)
-
-// add all public methods on java.lang.System as commands:
-karaf@root> addcommand system (($.context bundle) loadClass java.lang.System)
-karaf@root> system:getproperty karaf.name
-root
-
-// create new objects
-karaf@root> map = (new java.util.HashMap)
-karaf@root> $map put 0 0
-karaf@root> $map
-0 0
-{code}
-
-h2. Real examples
-
-{code}
-#
-# Add a value at the end of a property in the given OSGi configuration
-#
-# For example:
-# > config-add-to-list org.ops4j.pax.url.mvn org.ops4j.pax.url.mvn.repositories http://scala-tools.org/repo-releases
-#
-config-add-to-list = {
- config:edit $1 ;
- a = (config:proplist | grep --color never $2 | tac) ;
- b = (echo $a | grep --color never "\b$3\b" | tac) ;
- if { ($b trim) isEmpty } {
- if { $a isEmpty } {
- config:propset $2 $3
- } {
- config:propappend $2 ", $3"
- } ;
- config:update
- } {
- config:cancel
- }
-}
-{code}
-
-{code}
-#
-# Wait for the given OSGi service to be available
-#
-wait-for-service-timeout = {
- _filter = $.context createFilter $1 ;
- _tracker = shell:new org.osgi.util.tracker.ServiceTracker $.context $_filter null ;
- $_tracker open ;
- _service = $_tracker waitForService $2 ;
- $_tracker close
-}
-#
-# Wait for the given OSGi service to be available with a timeout of 10 seconds
-#
-wait-for-service = {
- wait-for-service-timeout $1 10000
-}
-#
-# Wait for the given command to be available with a timeout of 10 seconds
-# For example:
-# > wait-for-command dev watch
-#
-wait-for-command = {
- wait-for-service "(&(objectClass=org.apache.felix.service.command.Function)(osgi.command.scope=$1)(osgi.command.function=$2))"
-}
-{code}
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/overview.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/overview.conf b/manual/src/main/webapp/overview.conf
index c5a6714..8a5281f 100644
--- a/manual/src/main/webapp/overview.conf
+++ b/manual/src/main/webapp/overview.conf
@@ -1,4 +1,4 @@
-h1. Karaf Overview
+h1. Apache Karaf Overview
Apache Karaf is a OSGi-based runtime which provides a lightweight container onto which various components and applications can be deployed.
@@ -6,18 +6,26 @@ Apache Karaf uses either Apache Felix Framework or Eclipse Equinox OSGi framewor
Apache Karaf can be scaled from a very lightweight container to a fully features enterprise service: it's a very flexible and extensible container, covering all the major needs.
-Here is a short list of features supported by the Karaf:
-
-* *Hot deployment*: Karaf supports hot deployment of OSGi bundles by monitoring jar files inside the {{deploy}} directory. Each time a jar is copied in this folder, it will be installed inside the runtime. You can then update or delete it and changes will be handled automatically. In addition, Karaf also supports exploded bundles and custom deployers (Blueprint and Spring ones are included by default).
-* *Dynamic configuration*: Services are usually configured through the ConfigurationAdmin OSGi service. Such configuration can be defined in Karaf using property files inside the {{etc}} directory. These configurations are monitored and changes on the properties files will be propagated to the services.
-* *Logging System*: using a centralized logging back end supported by Log4J, Karaf supports a number of different APIs (JDK 1.4, JCL, SLF4J, Avalon, Tomcat, OSGi)
-* *Provisioning*: Provisioning of libraries or applications can be done through a number of different ways, by which they will be downloaded locally, installed and started.
-* *Native OS integration*: Karaf can be integrated into your own Operating System as a service so that the lifecycle will be bound to your Operating System.
-* *Extensible Shell console*: Karaf features a nice text console where you can manage the services, install new applications or libraries and manage their state. This shell is easily extensible by deploying new commands dynamically along with new features or applications.
-* *Remote access*: use any SSH client to connect to Karaf and issue commands in the console
-* *Security framework* based on JAAS
-* *Managing instances*: Karaf provides simple commands for managing multiple instances. You can easily create, delete, start and stop instances of Karaf through the console.
-* Supports the latest OSGi 4.3 containers: Apache Felix Framework 4.0 and Eclipse Equinox 3.8
+Here is a short list of provided features:
+
+* *Hot deployment*: simply drop a file in the {{deploy}} directory, Apache Karaf will detect the type of the file and
+ try to deploy it.
+* *Complete Console*: Apache Karaf provides a complete Unix-like console where you can completely manage the container.
+* *Dynamic Configuration*: Apache Karaf provides a set of command dedicated for the management of the configuration files.
+ All configuration files are centralized in the {{etc}} folder. Any change in a configuration file is taken on the fly.
+* *Advanced Logging System*: Apache Karaf supports a large set of Logging framework (slf4j, log4j, etc). Whatever the
+ logging framework you use, Apache Karaf centralizes the configuration in one file.
+* *Provisioning*: Apache Karaf supports a large set of URL where you can install your application (Maven repository, HTTP,
+ file, etc). It also provides the concept of "Karaf Feature" which is a way to describe your application.
+* *Management*: Apache Karaf is an enterprise-ready container, providing a lot of management indicators and operations
+ via JMX.
+* *Remote*: Apache Karaf embeds an SSHd server allowing you to use the console remotely. The management layer is also
+ accessible remotely.
+* *Security*: Apache Karaf provides a complete security framework (based on JAAS), and providing RBAC (Role-Based Access
+ Control) mechanism for console and JMX.
+* *Instances*: multiple instances of Apache Karaf can be managed directly from a main instance (root).
+* *OSGi frameworks*: Apache Karaf is not tight to one OSGi framework. By default, Apache Karaf runs with Apache Felix
+ Framework, but you can easily switch to Equinox (just change on property in a configuration file).
!/images/karaf.png!
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/users-guide/console.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/users-guide/console.conf b/manual/src/main/webapp/users-guide/console.conf
index 4f0234c..7dc0c25 100644
--- a/manual/src/main/webapp/users-guide/console.conf
+++ b/manual/src/main/webapp/users-guide/console.conf
@@ -488,6 +488,8 @@ because a space is missing after the {{if}} statement.
As for the aliases, you can create init scripts in the {{etc/shell.init.script}} file.
You can also named you script with an alias. Actually, the aliases are just scripts.
+See the Scripting section of the developers guide for details.
+
h2. Security
The Apache Karaf console supports a Role Based Access Control (RBAC) security mechanism. It means that depending of
http://git-wip-us.apache.org/repos/asf/karaf/blob/56739bd0/manual/src/main/webapp/users-guide/features.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/users-guide/features.conf b/manual/src/main/webapp/users-guide/features.conf
index dce3559..c7fe92c 100644
--- a/manual/src/main/webapp/users-guide/features.conf
+++ b/manual/src/main/webapp/users-guide/features.conf
@@ -1,35 +1,50 @@
-h1. Karaf features
+h1. Features
h2. Standard Features
-* *Hot deployment*: Karaf supports hot deployment of OSGi bundles by monitoring jar files inside the {{\[home\]/deploy}} directory. Each time a jar is copied in this folder, it will be installed inside the runtime. You can then update or delete it and changes will be handled automatically. In addition, Karaf also supports exploded bundles and custom deployers (blueprint and Spring ones are included by default).
-* *Dynamic configuration*: Services are usually configured through the ConfigurationAdmin OSGi service. Such configuration can be defined in Karaf using property files inside the {{\[home\]/etc}} directory. These configurations are monitored and changes on the properties files will be propagated to the services.
-* *Logging System*: using a centralized logging back end supported by Log4J, Karaf supports a number of different APIs (JDK 1.4, JCL, SLF4J, Avalon, Tomcat, OSGi)
-* *Provisioning*: Provisioning of libraries or applications can be done through a number of different ways, by which they will be downloaded locally, installed and started.
-* *Native OS integration*: Karaf can be integrated into your own Operating System as a service so that the lifecycle will be bound to your Operating System.
-* *Extensible Shell console*: Karaf features a nice text console where you can manage the services, install new applications or libraries and manage their state. This shell is easily extensible by deploying new commands dynamically along with new features or applications.
-* *Remote access*: use any SSH client to connect to Karaf and issue commands in the console
-* *Security framework* based on JAAS
-* *Managing instances*: Karaf provides simple commands for managing multiple instances. You can easily create, delete, start and stop instances of Karaf through the console.
-* Supports the latest OSGi 4.3 containers: Apache Felix Framework 4.0 and Eclipse Equinox 3.7
+* *Hot deployment*: simply drop a file in the {{deploy}} directory, Apache Karaf will detect the type of the file and
+ try to deploy it.
+* *Complete Console*: Apache Karaf provides a complete Unix-like console where you can completely manage the container.
+* *Dynamic Configuration*: Apache Karaf provides a set of command dedicated for the management of the configuration files.
+ All configuration files are centralized in the {{etc}} folder. Any change in a configuration file is taken on the fly.
+* *Advanced Logging System*: Apache Karaf supports a large set of Logging framework (slf4j, log4j, etc). Whatever the
+ logging framework you use, Apache Karaf centralizes the configuration in one file.
+* *Provisioning*: Apache Karaf supports a large set of URL where you can install your application (Maven repository, HTTP,
+ file, etc). It also provides the concept of "Karaf Feature" which is a way to describe your application.
+* *Management*: Apache Karaf is an enterprise-ready container, providing a lot of management indicators and operations
+ via JMX.
+* *Remote*: Apache Karaf embeds an SSHd server allowing you to use the console remotely. The management layer is also
+ accessible remotely.
+* *Security*: Apache Karaf provides a complete security framework (based on JAAS), and providing RBAC (Role-Based Access
+ Control) mechanism for console and JMX.
+* *Instances*: multiple instances of Apache Karaf can be managed directly from a main instance (root).
+* *OSGi frameworks*: Apache Karaf is not tight to one OSGi framework. By default, Apache Karaf runs with Apache Felix
+ Framework, but you can easily switch to Equinox (just change on property in a configuration file).
!/images/karaf.png!
h2. Enterprise features
-* JPA
-* JTA
+* WebContainer (JSP/Servlet support, including WAR archive deployment support)
+* Naming (JNDI)
+* Transaction (JTA)
+* DataSources (JDBC)
+* MOM (JMS)
+* Persistence (JPA)
+* EJB
+* CDI
+* HA/failover and cluster
h2. External Features
-Besides the features provided by Karaf itself there are some open source and commercial projects that further extend the usage options of Karaf.
+As a very extend-able container, OpenSource and commercial projects provide "native" support of Apache Karaf.
-These open source projects provide Karaf features that make it easy to use them in the Karaf container:
+We can mention (this list is not exhaustive):
* [Apache ActiveMQ|http://activemq.apache.org/osgi-integration.html]
* [Apache Camel|http://camel.apache.org/karaf.html]
-* Apache CXF
+* [Apache CXF|http://cxf.apache.org]
* [JClouds|http://www.jclouds.org/documentation/userguide/karaf/]
-* OpenEJB
* [Apache Wicket|http://team.ops4j.org/wiki/display/paxwicket/Install+Pax+Wicket]
-* [Cellar|http://karaf.apache.org/manual/cellar/latest-2.2.x/]
+* ...
+