manual/src/main/asciidoc/developer-guide/scripting.adoc - karaf - Git at Google

 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //      http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //

 === Scripting

 In the console section of the users guide, we introduced the scripting support.

 ==== Assignation

 You already know the first usage of scripting: execution of command.

 ----
 karaf@root()> echo hello world
 hello world
 ----

 You can also assign a value to session variables:

 ----
 karaf@root()> msg = "hello world"
 hello world
 ----

 Once you have assigned a value to a variable, you can display this value using the "resolved" variable name:

 ----
 karaf@root()> echo $msg
 hello world
 ----

 The () are execution quotes (like the backquotes when you use bash on Unix).

 ----
 karaf@root()> ($.context bundle 1) location
 mvn:org.apache.karaf.jaas/org.apache.karaf.jaas.modules/4.0.0
 ----

 The `$.context` access the context variables in the current session.
 We access to the `bundle` variable (an array containing all bundles), and we want to display the bundle location for
 the bundle at the index 1 in the bundle array.

 ==== Expressions

 The shell has a built-in expression parser.  Expressions must be enclosed with the `%(...)` syntax.

 Examples:

 ----
 karaf@root()> %(1+2)
 3
 karaf@root()> a = 0
 0
 karaf@root()> %(a+=1)
 1
 karaf@root()> %(a+=1)
 2
 karaf@root()> b=1
 1
 karaf@root()> %(SQRT(a^2 + b^2))
 1.7320508
 ----

 ===== Mathematical Operators

 |===
 |Operator |Description

 |+
 | Additive operator

 |-
 | Subtraction operator

 |*
 | Multiplication operator

 |/
 | Division operator

 |%
 | Remainder operator (Modulo)

 |^
 | Power operator
 |===

 ===== Boolean Operators

 |===
 |Operator |Description

 |=
 | Equals

 |==
 | Equals

 |!=
 |Not equals

 |<>
 | Not equals

 |<
 | Less than

 |<=
 | Less than or equal to

 |>
 | Greater than

 |>=
 | Greater than or equal to

 |&&
 | Boolean and

 |\|\|
 |Boolean or
 |===

 ===== Supported Functions

 |===
 |Function |Description

 |NOT(_expression_)
 |Boolean negation, 1 (means true) if the expression is not zero

 |IF(_condition_,_value_if_true_,_value_if_false_)
 |Returns one value if the condition evaluates to true or the other if it evaluates to false

 |RANDOM()
 |Produces a random number between 0 and 1

 |MIN(_e1_,_e2_)
 |Returns the smaller of both expressions

 |MAX(_e1_,_e2_)
 |Returns the bigger of both expressions

 |ABS(_expression_)
 |Returns the absolute (non-negative) value of the expression

 |ROUND(_expression_,precision)
 |Rounds a value to a certain number of digits, uses the current rounding mode

 |FLOOR(_expression_)
 |Rounds the value down to the nearest integer

 |CEILING(_expression_)
 |Rounds the value up to the nearest integer

 |LOG(_expression_)
 |Returns the natural logarithm (base e) of an expression

 |SQRT(_expression_)
 |Returns the square root of an expression

 |SIN(_expression_)
 |Returns the trigonometric sine of an angle (in degrees)

 |COS(_expression_)
 |Returns the trigonometric cosine of an angle (in degrees)

 |TAN(_expression_)
 |Returns the trigonometric tangens of an angle (in degrees)

 |SINH(_expression_)
 |Returns the hyperbolic sine of a value

 |COSH(_expression_)
 |Returns the hyperbolic cosine of a value

 |TANH(_expression_)
 |Returns the hyperbolic tangens of a value

 |RAD(_expression_)
 |Converts an angle measured in degrees to an approximately equivalent angle measured in radians

 |DEG(_expression_)
 |Converts an angle measured in radians to an approximately equivalent angle measured in degrees
 |===

 Functions names are case insensitive.

 ===== Supported Constants

 |===
 |Constant |Description

 |PI
 |The value of _PI_, exact to 100 digits

 |TRUE
 |The value one

 |FALSE
 |The value zero
 |===

 ==== List, maps, pipes and closures

 Using [], you can define an array variable:

 ----
 karaf@root()> list = [1 2 a b]
 1
 2
 a
 b

 ----

 You can also create a map if you put variables assignation in the array:

 ----
 karaf@root()> map = [Jan=1 Feb=2 Mar=3]
 Jan                 1
 Feb                 2
 Mar                 3
 ----

 Using the | character, you can pipe output from a command as an input to another one.

 For instance, you can access to the bundles context variables and send it as input to the grep command:

 ----
 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)
 ----

 You can assign a name to a script execution. It's what we use for alias:

 ----
 karaf@root()> echo2 = { echo xxx $args yyy }
 echo xxx $args yyy
 karaf@root()> echo2 hello world
 xxx hello world yyy
 ----

 ==== Startup

 The `etc/shell.init.script` file is executed at startup in each shell session, allowing the definition of additional
 variables or aliases or even complex functions. It's like the bashrc or profile on Unix.

 ==== Constants and variables

 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:

 ----
 karaf@root> \#inc = { var = "${var}i" ; $var }
 var = "${var}i" ; $var
 karaf@root> echo $inc
 i
 karaf@root> echo $inc
 ii
 karaf@root>
 ----

 ==== Built-in variables and commands

 Apache Karaf console provides built-in variables that are 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`
 * ...

 See the link:commands[full list of `shell` commands] for details.

 ==== Leveraging existing Java capabilities (via reflection)

 Apache Karaf console supports loading and execution of Java classes.

 The `$karaf.lastException` implicit variable contains the latest Exception thrown.

 ----
 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)
 ----

 It's possible to create objects to create commands "on the fly":

 ----
 karaf@root()> addcommand system (($.context bundle) loadClass java.lang.System)
 karaf@root()> system:getproperty karaf.name
 root
 ----

 It means that you can create an object using the `new` directive, and call methods on the objects:

 ----
 karaf@root> map = (new java.util.HashMap)
 karaf@root> $map put 0 0
 karaf@root> $map
 0                   0
 ----

 ==== Examples

 The following examples show some scripts defined in `etc/shell.init.script`.

 The first example shows a script to add a value into a configuration list:

 ----
 #
 # 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: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:property-set $2 $3
     } {
       config:property-append $2 ", $3"
     } ;
     config:update
   } {
     config:cancel
   }
 }
 ----

 This second example shows a script to wait for an OSGi service, up to a given timeout, and combine this script in
 other scripts:

 ----
 #
 # 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))"
 }
 ----
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	//

	=== Scripting

	In the console section of the users guide, we introduced the scripting support.

	==== Assignation

	You already know the first usage of scripting: execution of command.

	----
	karaf@root()> echo hello world
	hello world
	----

	You can also assign a value to session variables:

	----
	karaf@root()> msg = "hello world"
	hello world
	----

	Once you have assigned a value to a variable, you can display this value using the "resolved" variable name:

	----
	karaf@root()> echo $msg
	hello world
	----

	The () are execution quotes (like the backquotes when you use bash on Unix).

	----
	karaf@root()> ($.context bundle 1) location
	mvn:org.apache.karaf.jaas/org.apache.karaf.jaas.modules/4.0.0
	----

	The `$.context` access the context variables in the current session.
	We access to the `bundle` variable (an array containing all bundles), and we want to display the bundle location for
	the bundle at the index 1 in the bundle array.

	==== Expressions

	The shell has a built-in expression parser. Expressions must be enclosed with the `%(...)` syntax.

	Examples:

	----
	karaf@root()> %(1+2)
	3
	karaf@root()> a = 0
	0
	karaf@root()> %(a+=1)
	1
	karaf@root()> %(a+=1)
	2
	karaf@root()> b=1
	1
	karaf@root()> %(SQRT(a^2 + b^2))
	1.7320508
	----

	===== Mathematical Operators

	\|===
	\|Operator \|Description

	\|+
	\| Additive operator

	\|-
	\| Subtraction operator

	\|*
	\| Multiplication operator

	\|/
	\| Division operator

	\|%
	\| Remainder operator (Modulo)

	\|^
	\| Power operator
	\|===

	===== Boolean Operators

	\|===
	\|Operator \|Description

	\|=
	\| Equals

	\|==
	\| Equals

	\|!=
	\|Not equals

	\|<>
	\| Not equals

	\|<
	\| Less than

	\|<=
	\| Less than or equal to

	\|>
	\| Greater than

	\|>=
	\| Greater than or equal to

	\|&&
	\| Boolean and

	\|\\|\\|
	\|Boolean or
	\|===

	===== Supported Functions

	\|===
	\|Function \|Description

	\|NOT(_expression_)
	\|Boolean negation, 1 (means true) if the expression is not zero

	\|IF(_condition_,_value_if_true_,_value_if_false_)
	\|Returns one value if the condition evaluates to true or the other if it evaluates to false

	\|RANDOM()
	\|Produces a random number between 0 and 1

	\|MIN(_e1_,_e2_)
	\|Returns the smaller of both expressions

	\|MAX(_e1_,_e2_)
	\|Returns the bigger of both expressions

	\|ABS(_expression_)
	\|Returns the absolute (non-negative) value of the expression

	\|ROUND(_expression_,precision)
	\|Rounds a value to a certain number of digits, uses the current rounding mode

	\|FLOOR(_expression_)
	\|Rounds the value down to the nearest integer

	\|CEILING(_expression_)
	\|Rounds the value up to the nearest integer

	\|LOG(_expression_)
	\|Returns the natural logarithm (base e) of an expression

	\|SQRT(_expression_)
	\|Returns the square root of an expression

	\|SIN(_expression_)
	\|Returns the trigonometric sine of an angle (in degrees)

	\|COS(_expression_)
	\|Returns the trigonometric cosine of an angle (in degrees)

	\|TAN(_expression_)
	\|Returns the trigonometric tangens of an angle (in degrees)

	\|SINH(_expression_)
	\|Returns the hyperbolic sine of a value

	\|COSH(_expression_)
	\|Returns the hyperbolic cosine of a value

	\|TANH(_expression_)
	\|Returns the hyperbolic tangens of a value

	\|RAD(_expression_)
	\|Converts an angle measured in degrees to an approximately equivalent angle measured in radians

	\|DEG(_expression_)
	\|Converts an angle measured in radians to an approximately equivalent angle measured in degrees
	\|===

	Functions names are case insensitive.

	===== Supported Constants

	\|===
	\|Constant \|Description

	\|PI
	\|The value of _PI_, exact to 100 digits

	\|TRUE
	\|The value one

	\|FALSE
	\|The value zero
	\|===

	==== List, maps, pipes and closures

	Using [], you can define an array variable:

	----
	karaf@root()> list = [1 2 a b]
	1
	2
	a
	b

	----

	You can also create a map if you put variables assignation in the array:

	----
	karaf@root()> map = [Jan=1 Feb=2 Mar=3]
	Jan 1
	Feb 2
	Mar 3
	----

	Using the \| character, you can pipe output from a command as an input to another one.

	For instance, you can access to the bundles context variables and send it as input to the grep command:

	----
	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)
	----

	You can assign a name to a script execution. It's what we use for alias:

	----
	karaf@root()> echo2 = { echo xxx $args yyy }
	echo xxx $args yyy
	karaf@root()> echo2 hello world
	xxx hello world yyy
	----

	==== Startup

	The `etc/shell.init.script` file is executed at startup in each shell session, allowing the definition of additional
	variables or aliases or even complex functions. It's like the bashrc or profile on Unix.

	==== Constants and variables

	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:

	----
	karaf@root> \#inc = { var = "${var}i" ; $var }
	var = "${var}i" ; $var
	karaf@root> echo $inc
	i
	karaf@root> echo $inc
	ii
	karaf@root>
	----

	==== Built-in variables and commands

	Apache Karaf console provides built-in variables that are 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`
	* ...

	See the link:commands[full list of `shell` commands] for details.

	==== Leveraging existing Java capabilities (via reflection)

	Apache Karaf console supports loading and execution of Java classes.

	The `$karaf.lastException` implicit variable contains the latest Exception thrown.

	----
	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)
	----

	It's possible to create objects to create commands "on the fly":

	----
	karaf@root()> addcommand system (($.context bundle) loadClass java.lang.System)
	karaf@root()> system:getproperty karaf.name
	root
	----

	It means that you can create an object using the `new` directive, and call methods on the objects:

	----
	karaf@root> map = (new java.util.HashMap)
	karaf@root> $map put 0 0
	karaf@root> $map
	0 0
	----

	==== Examples

	The following examples show some scripts defined in `etc/shell.init.script`.

	The first example shows a script to add a value into a configuration list:

	----
	#
	# 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: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:property-set $2 $3
	} {
	config:property-append $2 ", $3"
	} ;
	config:update
	} {
	config:cancel
	}
	}
	----

	This second example shows a script to wait for an OSGi service, up to a given timeout, and combine this script in
	other scripts:

	----
	#
	# 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))"
	}
	----