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 21:54:15 UTC
[1/4] git commit: [KARAF-2511] Review and update the developer
commands page of the developers guide
Updated Branches:
refs/heads/master 56739bd09 -> 40810dee0
[KARAF-2511] Review and update the developer commands 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/b8d6e0ec
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/b8d6e0ec
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/b8d6e0ec
Branch: refs/heads/master
Commit: b8d6e0ec0d35d8af36dc2088704f5cd055c3a440
Parents: 56739bd
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Mon Dec 23 19:00:42 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Mon Dec 23 19:00:42 2013 +0100
----------------------------------------------------------------------
.../developers-guide/developer-commands.conf | 267 ++++++++++++-------
1 file changed, 172 insertions(+), 95 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/b8d6e0ec/manual/src/main/webapp/developers-guide/developer-commands.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developers-guide/developer-commands.conf b/manual/src/main/webapp/developers-guide/developer-commands.conf
index 6e161da..14ae266 100644
--- a/manual/src/main/webapp/developers-guide/developer-commands.conf
+++ b/manual/src/main/webapp/developers-guide/developer-commands.conf
@@ -1,106 +1,175 @@
h1. Developer commands
-Karaf provides a set of commands specific for developer use.
+As you can see in the users guide, Apache Karaf is an enterprise ready OSGi container.
-They allow for getting detailed information about the Karaf instances and the applications running in them.
+It's also a container designed to simplify the life for developers and administrators to get details about the
+running container.
-h2. Diagnostic dump command
+h2. Dump
-Karaf provides a {{dev:create-dump}} command which creates a dump file containing diagnostic information. The dumps
-could be packaged in a zip archive (default) or directly into a given directory.
+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.
+
+The {{dev:dump-create}} command creates a dump file containing:
+
+* the {{bundles.txt}} file contains the list of all OSGi bundles, with id, symbolic name, version, current status
+* the {{environment.txt}} file contains details about Apache Karaf, OSGi framework, Operating System, JVM, system
+ properties, threads count, classes loaded
+* the {{features.txt}} file contains the list of Apache Karaf features repositories, features with version, current
+ status, and bundles provided.
+* the {{threads.txt}} file contains a thread dump, with all threads, waiting status, etc.
+* the {{log}} folder contains the {{data/log}} folder, with all log files.
+
+By default, the {{dev:dump-create}} command creates a zip file in the {{KARAF_BASE}} folder, with the timestamp of the
+dump creation:
{code}
-karaf@root> dev:create-dump
+karaf@root()> dev:dump-create
Diagnostic dump created.
{code}
-The previous command generates a zip archive in the KARAF_HOME (by default the name is the generation timestamp).
+We can see the file generated in the {{KARAF_BASE}} folder:
-The following dumps are available in the zip archive:
-* {{features.txt}} provides an overview of the feature repositoroes, the installed features and bundles
-* {{bundles.txt}} provides an overview of the installed bundles, with the ID and the state of each bundle.
-* {{threads.txt}} provides a complete threads dump. It describe all threads running in Karaf and their current state (blocked, waiting, etc) with the associated class hierarchy.
+{code}
+$ cd /opt/apache-karaf-3.0.0
+$ ls -lh *.zip
+-rw-r--r-- 1 user group 11K Dec 23 16:08 2013-12-23_160858.zip
+{code}
+You can specify the file name of the zip archive:
-These dumps are very helpful when you would like to take a snapshot of a current Karaf running instance.
+{code}
+karaf@root()> dev:dump-create mydump.zip
+Diagnostic dump created.
+{code}
+Instead of a zip archive, you can create the dump (exploded) in a directory using the {{-d}} ({{--directory}}) option:
+
+{code}
+karaf@root()> dev:dump-create -d /tmp/mydump
+Diagnostic dump created.
+{code}
+
+h2. Diagnostic
+
+It's not always easy for the developers to understand why a bundle is not active.
+
+It could be because the Activator failed, the Blueprint container start failed, etc.
+
+The {{bundle:diag}} command gives you details about a bundle is not active:
+
+{code}
+karaf@root()> bundle:diag
+Apache ServiceMix :: Bundles :: avro-ipc (81)
+---------------------------------------------
+Status: Installed
+Unsatisfied Requirements:
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet)(version>=2.5.0)(!(version>=3.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet.http)(version>=2.5.0)(!(version>=3.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.data)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.file)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.generic)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.io)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.reflect)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.specific)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.util)(version>=1.7.0)(!(version>=2.0.0)))
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity)
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.app)
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.context)
+[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.exception)
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.bootstrap)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.buffer)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.group)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.socket.nio)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.frame)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.oneone)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.execution)(version>=3.4.0)(!(version>=4.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.bio)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.nio)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.servlet)(version>=6.1.0)(!(version>=7.0.0)))
+[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.resource)(version>=6.1.0)(!(version>=7.0.0)))
+{code}
h2. Dynamic import
The {{bundle:dynamic-import}} command allows you to enable or disable the dynamic import of a given bundle:
{code}
-karaf@root> bundle:dynamic-import 41
-Enabling dynamic imports on bundle org.apache.karaf.shell.config [41]
+karaf@root()> bundle:dynamic-import 77
+Enabling dynamic imports on bundle org.apache.karaf.config.core [77]
{code}
-h2. OSGi framework
+The purpose of dynamic import is to allow a bundle to be wired up to packages that may not be knwon about in advance.
+When a class is requested, if it cannot be solved via the bundle's existing imports, the dynamic import allows other
+bundles to be considered for a wiring import to be added.
-The {{system:framework}} command allows to display the current OSGi framework in use, and enable / disable debugging inside the OSGi framework.
+The {{bundle:dynamic-import}} command allows or doesn't allow this behaviour.
-{code}
-karaf@root> dev:framework
-Current OSGi framework is Felix
-karaf@root> dev:framework -debug
-Enabling debug for OSGi framework (Felix)
-- set felix.log.level=4 in etc/config.properties
+h2. OSGi framework
-Restart Karaf now to enable Felix debug logging
-karaf@root> dev:framework -nodebug
-Disabling debug for OSGi framework (Felix)
-- removed felix.log.level from etc/config.properties
+The {{system:framework}} command allows to display the current OSGi framework in use, and enable/disable debugging inside the OSGi framework.
-Restart Karaf now to disable Felix debug logging
+{code}
+karaf@root()> system:framework
+Current OSGi framework is felix
+karaf@root()> system:framework -debug
+Enabling debug for OSGi framework (felix)
+karaf@root()> system:framework -nodebug
+Disabling debug for OSGi framework (felix)
{code}
-h2. Print stack trace
+h2. Stack traces printout
-The {{shell:stack-traces-print}} command prints the full stack trace in the console when the execution of a command
+The {{shell:stack-traces-print}} command prints the full stack trace when the execution of a command
throws an exception.
-You can enable or disable this behavior by passing true (to enable) or false (to disable) on the command on the fly:
+You can enable or disable this behaviour by passing true (to enable) or false (to disable) on the command on the fly:
{code}
-karaf@root> shell:stack-traces-print
-karaf@root> bundles:start
-Error executing command bundles:start: argument ids is required
-CommandException: Argument ids is required
- at DefaultActionPreparator.prepare(DefaultActionPreparator.java:284)
- at AbstractCommand.execute(AbstractCommand.java:34)
+karaf@root()> stack-traces-print
+Printing of stacktraces set to true
+karaf@root()> bundle:start
+java.lang.RuntimeException: Access to system bundle 0 denied. You can override with -f
+ at org.apache.karaf.bundle.command.BundlesCommand.assertNoSystemBundles(BundlesCommand.java:57)
+ at org.apache.karaf.bundle.command.BundlesCommand.doExecute(BundlesCommand.java:48)
+ at org.apache.karaf.bundle.command.BundlesCommandWithConfirmation.doExecute(BundlesCommandWithConfirmation.java:41)
+ at org.apache.karaf.shell.console.AbstractAction.execute(AbstractAction.java:33)
+ at org.apache.karaf.shell.console.OsgiCommandSupport.execute(OsgiCommandSupport.java:39)
+ at org.apache.karaf.shell.commands.basic.AbstractCommand.execute(AbstractCommand.java:33)
+ at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
+ at java.lang.reflect.Method.invoke(Method.java:601)
+ at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54)
+ at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119)
+ at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source)
+ at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
+ at java.lang.reflect.Method.invoke(Method.java:601)
+ at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54)
+ at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119)
+ at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source)
at org.apache.felix.gogo.runtime.CommandProxy.execute(CommandProxy.java:78)
- at org.apache.felix.gogo.runtime.Closure.executeCmd(Closure.java:474)
- at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:400)
+ at org.apache.felix.gogo.runtime.Closure.executeCmd(Closure.java:477)
+ 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:79)
- at org.apache.karaf.shell.console.jline.Console.run(Console.java:180)
- at java.lang.Thread.run(Thread.java:619)
-karaf@root> shell:stack-traces-print false
-karaf@root> bundles:start
-Error executing command bundles:start: argument ids is required
-{code}
-
-h2. Karaf restart
-
-The {{system:shutdown}} -r command allows you to restart the running Karaf instance:
-
-{code}
-karaf@root> system:shutdown -r
-karaf@root>
- __ __ ____
- / //_/____ __________ _/ __/
- / ,< / __ `/ ___/ __ `/ /_
- / /| |/ /_/ / / / /_/ / __/
- /_/ |_|\__,_/_/ \__,_/_/
-
- Apache Karaf (2.99.99-SNAPSHOT)
-
-Hit '<tab>' for a list of available commands
-and '[cmd] --help' for help on a specific command.
-Hit '<ctrl-d>' or 'system:shutdown' to shutdown Karaf.
-
-karaf@root>
+ at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89)
+ at org.apache.karaf.shell.console.impl.jline.ConsoleImpl$DelegateSession.execute(ConsoleImpl.java:497)
+ at org.apache.karaf.shell.console.impl.jline.ConsoleImpl.run(ConsoleImpl.java:198)
+ at java.lang.Thread.run(Thread.java:722)
+ at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.doRun(ConsoleFactoryService.java:118)
+ at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3$1.run(ConsoleFactoryService.java:109)
+ at java.security.AccessController.doPrivileged(Native Method)
+ at org.apache.karaf.jaas.modules.JaasHelper.doAs(JaasHelper.java:47)
+ at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.run(ConsoleFactoryService.java:107)
+karaf@root()> stack-traces-print false
+Printing of stacktraces set to false
+karaf@root()> bundle:start
+Error executing command: Access to system bundle 0 denied. You can override with -f
{code}
h2. Bundle tree
@@ -109,42 +178,50 @@ The {{bundle:tree-show}} command shows the bundle dependency tree based on the w
ID.
{code}
-karaf@root> dev:show-tree 40
-Bundle org.apache.karaf.diagnostic.command [40] is currently ACTIVE
-
-org.apache.karaf.diagnostic.command [40]
-+- org.apache.aries.blueprint [10]
-| +- org.apache.aries.util [8]
-| +- org.apache.felix.configadmin [5]
-| +- org.apache.aries.proxy [7]
-| | +- org.apache.aries.util [8]
-| | +- org.apache.servicemix.bundles.asm [9]
-| | +- org.ops4j.pax.logging.pax-logging-api [3]
-| +- org.ops4j.pax.logging.pax-logging-api [3]
-+- org.apache.karaf.shell.console [22]
-| +- org.apache.aries.blueprint [10]
-| +- org.ops4j.pax.logging.pax-logging-api [3]
-| +- org.apache.karaf.jaas.modules [13]
-| +- org.apache.aries.blueprint [10]
-| +- org.apache.felix.configadmin [5]
-| +- org.apache.karaf.jaas.config [29]
-| | +- org.apache.aries.blueprint [10]
-| | +- org.ops4j.pax.logging.pax-logging-api [3]
-| +- org.ops4j.pax.logging.pax-logging-api [3]
-+- org.apache.karaf.diagnostic.core [23]
+karaf@root()> bundle:tree-show 40
+Bundle org.ops4j.pax.url.wrap [40] is currently ACTIVE
+
+org.ops4j.pax.url.wrap [40]
++- org.ops4j.base.util.property [14]
++- org.ops4j.pax.url.commons [49]
+| +- org.ops4j.base.util.property [14]
+| +- org.ops4j.pax.logging.pax-logging-api [23]
+| +- org.ops4j.pax.swissbox.property [31]
+| | +- org.ops4j.base.util.property [14]
+| | +- org.ops4j.base.lang [41]
+| +- org.apache.felix.configadmin [43]
+| | +- org.ops4j.pax.logging.pax-logging-api [23]
+| +- org.ops4j.base.lang [41]
++- org.ops4j.pax.logging.pax-logging-api [23]
++- org.ops4j.pax.swissbox.bnd [25]
+| +- biz.aQute.bndlib [30]
+| | +- org.apache.servicemix.bundles.junit [36]
+| +- org.ops4j.pax.logging.pax-logging-api [23]
+| +- org.ops4j.base.lang [41]
++- org.apache.felix.configadmin [43]
++- org.ops4j.base.net [29]
+| +- org.ops4j.base.monitors [37]
+| +- org.ops4j.base.lang [41]
++- org.ops4j.base.lang [41]
{code}
-h2. Watching and updating bundle
+h2. 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.
-The {{bundle:watch}} watches the local maven repository and updates changed bundles. It's especially helpful in development mode.
+The {{bundle:watch}} allows you to configure a set of URLs to monitore. All bundles bundles whose location matches the
+given URL will be automatically updated. It avoids needing to manually update the bundles or even copy the bundle to the
+system folder.
-It allows you to configure a set of URLs that will be monitored. All bundles whose location matches the given URL
-will be automatically updated. It avoids needing to manually update the bundles or even copy the bundle to the system folder.
+{warning}
+Only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically.
+{warning}
-Note that only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically, so if you do:
+The following command:
{code}
karaf@root> dev:watch *
{code}
-it will actually monitor all bundles that have a location matching mvn:* that have '-SNAPSHOT' in their URL.
+will monitore all bundles that have a location matching mvn:* and having '-SNAPSHOT' in their URL.
[2/4] git commit: [KARAF-2511] Review and update the scripting page
of the developers guide
Posted by jb...@apache.org.
[KARAF-2511] Review and update the scripting 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/900c6122
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/900c6122
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/900c6122
Branch: refs/heads/master
Commit: 900c612233e71e6e5d9d52970e3c7e5c9b8a8d5f
Parents: b8d6e0e
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Mon Dec 23 21:11:18 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Mon Dec 23 21:11:18 2013 +0100
----------------------------------------------------------------------
.../main/webapp/developers-guide/scripting.conf | 151 +++++++++++++------
1 file changed, 105 insertions(+), 46 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/900c6122/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
index fc574b2..afe2135 100644
--- a/manual/src/main/webapp/developers-guide/scripting.conf
+++ b/manual/src/main/webapp/developers-guide/scripting.conf
@@ -1,63 +1,99 @@
-h1. Shell syntax
+h1. Scripting
-h2. Easy to use interactively - no unnecessary syntax
+In the console section of the users guide, we introduced the scripting support.
+
+h2. Assignation
+
+You already know the first usage of scripting: execution of command.
{code}
-// simple command
-karaf@root> echo hello world
+karaf@root()> echo hello world
hello world
+{code}
-// session variables
-karaf@root> msg = "hello world"
+You can also assign value to session variables:
+
+{code}
+karaf@root()> msg = "hello world"
hello world
-karaf@root> echo $msg
+{code}
+
+Once you have assigned a value to a variable, you can display this value using the "resolved" variable name:
+
+{code}
+karaf@root()> echo $msg
hello world
+{code}
+
+The () are execution quotes (like the backquotes when you use bash on Unix).
-// execution quotes () - similar to bash backquotes
-karaf@root> ($.context bundle 1) location
-mvn:org.ops4j.pax.url/pax-url-mvn/1.1.3
{code}
+karaf@root()> ($.context bundle 1) location
+mvn:org.apache.karaf.jaas/org.apache.karaf.jaas.modules/3.0.1-SNAPSHOT
+{code}
+
+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.
h2. List, maps, pipes and closures
+Using [], you can define array variable:
+
{code}
-// lists - []
-karaf@root> list = [1 2 a b]
+karaf@root()> list = [1 2 a b]
1
2
a
b
-karaf@root> map = [Jan=1 Feb=2 Mar=3]
+{code}
+
+You can also create a map if you put variables assignation in the array:
+
+{code}
+karaf@root()> map = [Jan=1 Feb=2 Mar=3]
Jan 1
Feb 2
Mar 3
+{code}
-// 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
+Using the | character, you can pipe output from a command as an input to another one.
-// closures - {}
-karaf@root> echo2 = { echo xxx $args yyy }
+For instance, you can access to the bundles context variables and send it as input to the grep command:
+
+{code}
+karaf@root()> ($.context bundles) | grep -i felix
+ 0|Active | 0|org.apache.felix.framework (4.2.1)
+ 21|Active | 11|org.apache.felix.fileinstall (3.2.6)
+ 43|Active | 10|org.apache.felix.configadmin (1.6.0)
+ 51|Active | 30|org.apache.felix.gogo.runtime (0.10.0)
+{code}
+
+You can assign name to script execution. It's what we use for alias:
+
+{code}
+karaf@root()> echo2 = { echo xxx $args yyy }
echo xxx $args yyy
-karaf@root> echo2 hello world
+karaf@root()> echo2 hello world
xxx hello world yyy
{code}
-h2. Startup scripts
+h2. 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.
+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.
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
+Apache Karaf console provides a set of implicit constants and variables that you can use in your script.
+
+* {{$.context}} to access a bundle context
+* {{$.variables}} to access the list of defined variables
+* {{$.commands}} to access the list of defined commands
+
+The variables starting with a # that are defined as Function (such as closures) will be executed automatically:
-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
@@ -68,22 +104,32 @@ ii
karaf@root>
{code}
-h2. Scripting
+h2. Built-in variables and commands
+
+Apache Karaf console provides built-in variable very useful for scripting:
+
+* {{$args}} retrieves the list of script parameters, given to the closure being executed
+* {{$1 .. $999}} retrieves the nth argument of the closure
+* {{$it}} (same as {{$1}}) is used in a loop to access the current iterator value
+
+Apache Karaf console provides commands for scripting:
+
+* {{shell:if}}
+* {{shell:new}}
+* {{shell:each}}
+* ...
-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
+h2. Leveraging existing Java capabilities (via reflection)
-The {{shell}} scope contains very useful command for scripting such as {{if}}, {{new}}, {{each}}.
+Apache Karaf console supports loading and execution of Java classes.
+
+The {{$karaf.lastException}} implicit variable contains the latest Exception thrown.
-h2. Leverages existing Java capabilities, via reflection
{code}
-// exception handling - console shows summary, but full context available
-karaf@root> ($.context bundle) loadClass foo
+karaf@root()> ($.context bundle) loadClass foo
Error executing command: foo not found by org.apache.karaf.shell.console [17]
-karaf@root> $karaf.lastException printStackTrace
+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)
@@ -104,20 +150,30 @@ java.lang.ClassNotFoundException: foo not found by org.apache.karaf.shell.consol
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)
+{code}
+
+It's possible to create objects to create commands "on the fly":
-// 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
+{code}
+karaf@root()> addcommand system (($.context bundle) loadClass java.lang.System)
+karaf@root()> system:getproperty karaf.name
root
+{code}
-// create new objects
+It means that you can create object using the {{new}} directive, and call methods on the objects:
+
+{code}
karaf@root> map = (new java.util.HashMap)
karaf@root> $map put 0 0
karaf@root> $map
0 0
{code}
-h2. Real examples
+h2. Examples
+
+The following examples show some scripts defined in {{etc/shell.init.script}}.
+
+The first example show a script to add a value into a configuration list:
{code}
#
@@ -128,13 +184,13 @@ h2. Real examples
#
config-add-to-list = {
config:edit $1 ;
- a = (config:proplist | grep --color never $2 | tac) ;
+ a = (config:property-list | 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:property-set $2 $3
} {
- config:propappend $2 ", $3"
+ config:property-append $2 ", $3"
} ;
config:update
} {
@@ -143,6 +199,9 @@ config-add-to-list = {
}
{code}
+This second example shows a script to wait for an OSGi service, up to a given timeout, and combine this script in
+other scripts:
+
{code}
#
# Wait for the given OSGi service to be available
[3/4] git commit: [KARAF-2511] Review and update the connect page of
the developers guide
Posted by jb...@apache.org.
[KARAF-2511] Review and update the connect 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/9a0d8d03
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/9a0d8d03
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/9a0d8d03
Branch: refs/heads/master
Commit: 9a0d8d033d9ff033a7f2e5dc53acfe940f129cb1
Parents: 900c612
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Mon Dec 23 21:27:48 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Mon Dec 23 21:27:48 2013 +0100
----------------------------------------------------------------------
.../main/webapp/developers-guide/connect.conf | 41 +++++++++++++++++---
1 file changed, 35 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/9a0d8d03/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
index 0253960..5afdf7c 100644
--- a/manual/src/main/webapp/developers-guide/connect.conf
+++ b/manual/src/main/webapp/developers-guide/connect.conf
@@ -1,11 +1,20 @@
+h1. 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.
-h1. Programmatically connect to the console
+h2. 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.
+You can write a Apache Karaf remote console client in Java (or other language).
-{pygmentize:java}
+Accessing to a remote Apache Karaf console means writing a SSH client. This SSH client can be in pure Java or in
+another language.
+
+For instance, the {{bin/client}} script starts a SSH client written in Java.
+
+The following code is a simple code to create a SSH client:
+
+{code:lang=java}
import org.apache.sshd.ClientChannel;
import org.apache.sshd.ClientSession;
import org.apache.sshd.SshClient;
@@ -45,9 +54,29 @@ public class Main {
}
}
-{pygmentize}
+{code}
-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].
+h2. To the management layer
+The Apache Karaf management layer uses JMX. Apache Karaf embeds a JMX MBeanServer that you can use remotely.
+In order to use the MBeanServer remotely, you have to write a JMX client.
+The following example shows a simple JMX client stopping Apache Karaf remotely via the JMX layer:
+
+{code:lang=java}
+javax.management.*;
+
+public class Main {
+
+ public static void main(String[] args) throws Exception {
+ JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root");
+ JMXConnector connector = JMXConnectorFactory.connect(url, null);
+ MBeanServerConnection mbeanServer = connector.getMBeanServerConnection();
+ ObjectName systemMBean = new ObjectName("org.apache.karaf:type=system,name=karaf-root");
+ mbeanServer.invoke(systemMBean, "halt", null, null);
+ connector.close();
+ }
+
+}
+{code}
\ No newline at end of file
[4/4] git commit: [KARAF-2511] Review and update the branding page of
the developers guide
Posted by jb...@apache.org.
[KARAF-2511] Review and update the branding 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/40810dee
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/40810dee
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/40810dee
Branch: refs/heads/master
Commit: 40810dee0541d4cc1030189d8a1bee97928001ec
Parents: 9a0d8d0
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Mon Dec 23 21:53:09 2013 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Mon Dec 23 21:53:09 2013 +0100
----------------------------------------------------------------------
.../main/webapp/developers-guide/branding.conf | 136 +++++++++++++++----
1 file changed, 109 insertions(+), 27 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf/blob/40810dee/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
index bb7e065..2ce1a53 100644
--- a/manual/src/main/webapp/developers-guide/branding.conf
+++ b/manual/src/main/webapp/developers-guide/branding.conf
@@ -1,20 +1,25 @@
+h1. Branding
+h2. Console
-h1. Branding the Console
+You can "brand" the Apache Karaf 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:
-By branding, it means that you can define your own welcome message and console prompt.
+* the welcome message (motd or Message Of The Day) displayed when you start the console
+* the prompt displayed to the users
-h2. Create your branding bundle
+h2. Branding bundle
-At startup, Karaf is looking for a bundle which exports the {{org.apache.karaf.branding}} package containing a
-{{branding.properties}} file.
+At startup, Apache 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.
+Basically, a branding bundle is a very simple bundle, just containing a {{org/apache/karaf/branding/branding.properties}}
+file.
-The Maven POM of your branding bundle should look like this:
+It's easy to create such branding bundle using Apache Maven.
+
+The following {{pom.xml}} creates a branding bundle:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
@@ -33,7 +38,7 @@ The Maven POM of your branding bundle should look like this:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
- <version>2.2</version>
+ <version>2.4.0</version>
<extensions>true</extensions>
<configuration>
<instructions>
@@ -53,9 +58,16 @@ The Maven POM of your branding bundle should look like this:
</project>
{code}
-Now, add a {{src/main/resources/org/apache/karaf/branding/branding.properties}} similar to:
+You can put your {{branding.properties}} file in the project resources ({{src/main/resources/org/apache/karaf/branding/branding.properties}}):
+
+{code}
+welcome = This is my Karaf brand\r\n
+prompt = Hey ${USER}>
+{code}
-{{code}}
+For instance, the default Apache Karaf branding properties file contains:
+
+{code}
welcome = \
\u001B[36m __ __ ____ \u001B[0m\r\n\
\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\
@@ -67,13 +79,11 @@ welcome = \
\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}}
+Hit '\u001B[1m<ctrl-d>\u001B[0m' or type '\u001B[1msystem:shutdown\u001B[0m' or '\u001B[1mlogout\u001B[0m' to shutdown Karaf.\r\n
+{code}
As you can see, the {{branding.properties}} contains two properties:
-* welcome is the welcome message displayed when you start Karaf.
+* welcome is the welcome message displayed when you start Apache Karaf console.
* 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.
@@ -94,22 +104,94 @@ prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICAT
prompt = my-user@my-karaf>
{code}
-h2. Configuring Karaf to use the branding bundle
+h2. Installing 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:
+Thanks to the {{pom.xml}}, we can use {{mvn}} to build the branding bundle:
+{code}
+mvn install
+{code}
- org.osgi.framework.system.packages.extra = \
- org.apache.karaf.branding
+You just have to drop the file in the {{lib}} directory:
-h2. Installing the branding bundle
+{code}
+cp branding.jar /opt/apache-karaf-3.0.0/lib/karaf-branding.jar
+{code}
+
+You can now start Apache Karaf to see your branded console.
+
+h2. WebConsole
-Build your branding bundle:
+It's also possible to brand the Apache Karaf WebConsole.
+
+You have to create a bundle, fragment of the Apache Karaf WebConsole.
+
+This WebConsole branding bundle contains a {{META-INF/webconsole.properties}} containing branding properties:
{code}
-mvn install
+#
+# This file contains branding properties to overwrite the default
+# branding of the Apache Felix Web Console when deployed in an
+# Apache Karaf application.
+
+
+webconsole.brand.name = My Web Console
+
+webconsole.product.name = My Karaf
+webconsole.product.url = http://karaf.apache.org/
+webconsole.product.image = /res/karaf/imgs/logo.png
+
+webconsole.vendor.name = The Apache Software Foundation
+webconsole.vendor.url = http://www.apache.org
+webconsole.vendor.image = /res/karaf/imgs/logo.png
+
+webconsole.favicon = /res/karaf/imgs/favicon.ico
+webconsole.stylesheet = /res/karaf/ui/webconsole.css
+
{code}
-and simply drop the generated jar file into the Karaf lib directory.
+The bundle also provides the css stylesheet and images defined in this properties file.
+
+As for console, you can use the following {{pom.xml}} to create the WebConsole branding bundle:
+
+{code}
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>my.group.id</groupId>
+ <artifactId>branding</artifactId>
+ <packaging>bundle</packaging>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <version>2.4.0</version>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Bundle-DocURL>http://felix.apache.org/site/apache-karaf.html</Bundle-DocURL>
+ <Fragment-Host>org.apache.karaf.webconsole.console;bundle-version="[3,4)"</Fragment-Host>
+ <Export-Package>!*</Export-Package>
+ <Import-Package>
+ javax.servlet;version=2.4,
+ javax.servlet.http;version=2.4,
+ !org.apache.felix.webconsole*,
+ org.apache.aries.blueprint,
+ org.osgi.service.blueprint.container,
+ org.osgi.service.blueprint.reflect,
+ *
+ </Import-Package>
+ </instructions>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
+{code}
-Start Karaf and you will see your branded Karaf console.
+With the {{webconsole}} feature installed, you can install this bundle (using {{bundle:install}} or by editing the
+{{etc/startup.properties}}), you will see the WebConsole with your branding.
\ No newline at end of file