Added scripting-languages page in docs
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/ff99845f Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/ff99845f Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/ff99845f Branch: refs/heads/master Commit: ff99845fba4cce8a8cd6d43e64313bbd15653b23 Parents: 007620e Author: Andrea Cosentino <anco...@gmail.com> Authored: Tue May 24 09:09:50 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Tue May 24 09:09:50 2016 +0200 ---------------------------------------------------------------------- docs/user-manual/en/SUMMARY.md | 1 + docs/user-manual/en/scripting-languages.adoc | 177 ++++++++++++++++++++++ 2 files changed, 178 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/ff99845f/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 6ed7fce..253cb46 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -250,6 +250,7 @@ * [Ognl](ognl.adoc) * [Ruby](ruby.adoc) * [SQL](josql.adoc) + * [Scripting languages](scripting-languages.adoc) * Data Formats * [BeanIO](beanio.adoc) http://git-wip-us.apache.org/repos/asf/camel/blob/ff99845f/docs/user-manual/en/scripting-languages.adoc ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/scripting-languages.adoc b/docs/user-manual/en/scripting-languages.adoc new file mode 100644 index 0000000..e62c1ad --- /dev/null +++ b/docs/user-manual/en/scripting-languages.adoc @@ -0,0 +1,177 @@ +[[ScriptingLanguages-ScriptingLanguages]] +Scripting Languages +~~~~~~~~~~~~~~~~~~~ + +Camel supports a number of scripting languages which can be used to +create an link:expression.html[Expression] or +link:predicate.html[Predicate] via the standard +http://jcp.org/en/jsr/detail?id=223[JSR 223] which is a standard part of +Java 6. + +The following scripting languages are integrated into the DSL: + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|Language |DSL keyword + +|EL |`el` + +|Groovy |`groovy` + +|JavaScript |`javaScript` + +|JoSQL |`sql` + +|JXPath |`jxpath` + +|MVEL |`mvel` + +|OGNL |`ognl` + +|PHP |`php` + +|Python |`python` + +|Ruby |`ruby` + +|XPath |`xpath` + +|XQuery |`xquery` +|======================================================================= + +However any http://jcp.org/en/jsr/detail?id=223[JSR 223] scripting +language can be used using the generic DSL methods. + +[[ScriptingLanguages-ScriptContext]] +ScriptContext +^^^^^^^^^^^^^ + +The JSR-223 scripting languages ScriptContext is pre configured with the +following attributes all set at `ENGINE_SCOPE`: + +[width="100%",cols="30%,30%,40%",options="header",] +|======================================================================= +|Attribute |Type |Value + +|context |`org.apache.camel.CamelContext` |The Camel Context ( It cannot be used in groovy) + +|camelContext |`org.apache.camel.CamelContext` |The Camel Context + +|exchange |`org.apache.camel.Exchange` |The current Exchange + +|request |`org.apache.camel.Message` |The message (IN message) + +|response |`org.apache.camel.Message` |*Deprecated*: The OUT message. The OUT message if null by default. Use +IN message instead. + +|properties |`org.apache.camel.builder.script.PropertiesFunction` |*Camel 2.9:* Function with a `resolve` method to make it easier to use +Camels link:properties.html[Properties] component from scripts. See +further below for example. +|======================================================================= + +See link:scripting-languages.html[Scripting Languages] for the list of +languages with explicit DSL support. + +[[ScriptingLanguages-AdditionalargumentstoScriptingEngine]] +Additional arguments to ScriptingEngine +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.8* + +You can provide additional arguments to the `ScriptingEngine` using a +header on the Camel message with the key `CamelScriptArguments`. +See this example: + +[[ScriptingLanguages-Usingpropertiesfunction]] +Using properties function +^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.9* + +If you need to use the link:properties.html[Properties] component from a +script to lookup property placeholders, then its a bit cumbersome to do +so. For example to set a header name myHeader with a value from a property +placeholder, which key is provided in a header named "foo". + +{% raw %} +[source,java] +-------------------------------------------------------------------------------------------------------------- +.setHeader("myHeader").groovy("context.resolvePropertyPlaceholders('{{' + request.headers.get('foo') + '}}')") +-------------------------------------------------------------------------------------------------------------- +{% endraw %} + +From Camel 2.9 onwards you can now use the properties function and the +same example is simpler: + +[source,java] +------------------------------------------------------------------------------- +.setHeader("myHeader").groovy("properties.resolve(request.headers.get('foo'))") +------------------------------------------------------------------------------- + +[[ScriptingLanguages-Loadingscriptfromexternalresource]] +Loading script from external resource +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.11* + +You can externalize the script and have Camel load it from a resource +such as `"classpath:"`, `"file:"`, or `"http:"`. + + This is done using the following syntax: `"resource:scheme:location"`, +eg to refer to a file on the classpath you can do: + +[source,java] +------------------------------------------------------------------- +.setHeader("myHeader").groovy("resource:classpath:mygroovy.groovy") +------------------------------------------------------------------- + +[[ScriptingLanguages-Howtogettheresultfrommultiplestatementsscript]] +How to get the result from multiple statements script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.14* + +As the scripteengine evale method just return a Null if it runs a +multiple statments script. Camel now look up the value of script result +by using the key of "result" from the value set. If you have multiple +statements script, you need to make sure you set the value of result +variable as the script return value. + +[source,text] +------------------------------------------------------------- +bar = "baz"; +# some other statements ... +# camel take the result value as the script evaluation result +result = body * 2 + 1 +------------------------------------------------------------- + +Â + +[[ScriptingLanguages-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use scripting languages in your camel routes you need to add the a +dependency on *camel-script* which integrates the JSR-223 scripting +engine. + +If you use maven you could just add the following to your pom.xml, +substituting the version number for the latest & greatest release (see +link:download.html[the download page for the latest versions]). + +[source,xml] +--------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-script</artifactId> + <version>x.x.x</version> +</dependency> +--------------------------------------- + +[[ScriptingLanguages-SeeAlso]] +See Also +~~~~~~~~ + +* link:languages.html[Languages] +* link:dsl.html[DSL] +* link:xml-configuration.html[Xml Configuration] +