You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/04/02 14:55:46 UTC
[2/3] camel git commit: Added camel-groovy and groovy-dsl docs to
gitbook
Added camel-groovy and groovy-dsl docs to gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/0550185a
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/0550185a
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/0550185a
Branch: refs/heads/master
Commit: 0550185a33ec59cd24b065b9133c81d92e1e1421
Parents: c7c5510
Author: Andrea Cosentino <an...@gmail.com>
Authored: Sat Apr 2 14:37:17 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Sat Apr 2 14:37:17 2016 +0200
----------------------------------------------------------------------
.../camel-groovy/src/main/docs/groovy-dsl.adoc | 402 +++++++++++++++++++
.../camel-groovy/src/main/docs/groovy.adoc | 204 ++++++++++
docs/user-manual/en/SUMMARY.md | 2 +
3 files changed, 608 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/0550185a/components/camel-groovy/src/main/docs/groovy-dsl.adoc
----------------------------------------------------------------------
diff --git a/components/camel-groovy/src/main/docs/groovy-dsl.adoc b/components/camel-groovy/src/main/docs/groovy-dsl.adoc
new file mode 100644
index 0000000..8f3c126
--- /dev/null
+++ b/components/camel-groovy/src/main/docs/groovy-dsl.adoc
@@ -0,0 +1,402 @@
+[[GroovyDSL-AbouttheGroovyDSL]]
+About the Groovy DSL
+^^^^^^^^^^^^^^^^^^^^
+
+The Groovy DSL implementation is built on top of the existing Java-based
+link:dsl.html[DSL], but it additionally allows to use Groovy language
+features in your routes, particularly
+http://www.groovy-lang.org/closures.html[Closures] acting as
+link:processor.html[Processor], link:expression.html[Expression],
+link:predicate.html[Predicate], or link:aggregator.html[Aggregation
+Strategy]. +
+ With the Groovy DSL you write your RouteBuilder classes entirely in
+Groovy, while the link:scripting-languages.html[scripting component]
+allows to embed small scripts into Java routes. The Groovy DSL requires
+Groovy 2.0 or newer and is available as of *Camel 2.11*.
+
+[[GroovyDSL-Introduction]]
+Introduction
+^^^^^^^^^^^^
+
+Because Groovy is syntactically very similar to Java, you can write your
+Groovy routes just like Java routes. The same Java DSL classes are being
+used, with the exception that some of the DSL classes get extended with
+a bunch of new methods at runtime. This is achieved by turning
+camel-groovy into a Groovy
+http://docs.codehaus.org/display/GROOVY/Creating+an+extension+module[Extension
+Module] that defines extension methods on existing classes.
+
+The majority of the extension methods allow
+http://www.groovy-lang.org/closures.html[Closures] to be used as
+parameters e.g. for expressions, predicates, processors. The following
+example reverses a string in the message body and then prints the value
+to System.out:
+
+*MyRouteBuilder.groovy*
+
+[source,java]
+-----------------------------------------
+...
+ from('direct:test')
+ .transform { it.in.body.reverse() }
+ .process { println it.in.body }
+...
+-----------------------------------------
+
+The corresponding route in Java would look something like this:
+
+*MyRouteBuilder.java*
+
+[source,java]
+-----------------------------------------------------------------------------------------
+...
+ from("direct:test")
+ .transform(new Expression() {
+ @Override
+ public Object evaluate(Exchange e) {
+ return new StringBuffer(e.getIn().getBody().toString()).reverse().toString();
+ }
+ })
+ .process(new Processor() {
+ @Override
+ public void process(Exchange e) {
+ System.out.println(e.getIn().getBody());
+ }
+ });
+...
+-----------------------------------------------------------------------------------------
+
+[[GroovyDSL-DevelopingwiththeGroovyDSL]]
+Developing with the Groovy DSL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To be able to use the Groovy DSL in your camel routes you need to add
+the a dependency on *camel-groovy* which implements the Groovy DSL.
+
+If you use Maven you can just add the following to your pom.xml,
+substituting the version number for the latest & greatest release (see
+the download page for the latest versions).
+
+[source,xml]
+---------------------------------------
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-groovy</artifactId>
+ <version>2.11.0</version>
+</dependency>
+---------------------------------------
+
+Additionally you need to make sure that the Groovy classes will be
+compiled. You can either use gmaven for this or, particularly with mixed
+projects containing Java and Groovy code, you might want to use the
+http://groovy.codehaus.org/Groovy-Eclipse+compiler+plugin+for+Maven[Groovy
+Eclipse compiler]:
+
+[source,xml]
+--------------------------------------------------------
+ <plugin>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <compilerId>groovy-eclipse-compiler</compilerId>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.codehaus.groovy</groupId>
+ <artifactId>groovy-eclipse-compiler</artifactId>
+ <version>2.7.0-01</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+--------------------------------------------------------
+
+As Eclipse user, you might want to configure the Maven Eclipse plugin in
+a way so that your project is set up correctly for using
+http://groovy.codehaus.org/Eclipse+Plugin[Eclipse Plugin for Groovy]
+when `mvn eclipse:eclipse` is executed:
+
+[source,xml]
+----------------------------------------------------------------------------------------
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-eclipse-plugin</artifactId>
+ <configuration>
+ <additionalProjectnatures>
+ <projectnature>org.eclipse.jdt.groovy.core.groovyNature</projectnature>
+ </additionalProjectnatures>
+ <classpathContainers>
+ <classpathContainer>org.eclipse.jdt.launching.JRE_CONTAINER</classpathContainer>
+ <classpathContainer>GROOVY_DSL_SUPPORT</classpathContainer>
+ </classpathContainers>
+ </configuration>
+ </plugin>
+----------------------------------------------------------------------------------------
+
+[[GroovyDSL-UsingClosuresinyourroutes]]
+Using Closures in your routes
++++++++++++++++++++++++++++++
+
+Groovy closures can be used to write concise implementations of Camel
+processors, expressions, predicates, and aggregation strategies. It is
+recommended to keep more complicated implementations of these objects in
+their own classes, e.g. to be able to test them more easily and not to
+clutter up your routes with business logic.
+
+[[GroovyDSL-ProcessorClosures]]
+Processor Closures
+
+All Java DSL parameters of type `org.apache.camel.Processor` can be
+replaced by a closure that accepts an object of type
+`org.apache.camel.Exchange` as only parameter. The return value of the
+closure is disregarded. All closures may also refer to variables not
+listed in their parameter list. Example:
+
+[source,java]
+------------------------------------------------------------------------------
+...
+ private String someValue
+...
+ from('direct:test')
+ .process { Exchange exchange -> println (exchange.in.body + someValue) }
+ .process { println (it.in.body + someValue) } // equivalent
+...
+------------------------------------------------------------------------------
+
+[[GroovyDSL-ExpressionClosures]]
+Expression Closures
+
+All Java DSL parameters of type `org.apache.camel.Expression` can be
+replaced by a closure that accepts an object of type
+`org.apache.camel.Exchange` as only parameter. The return value of the
+closure is the result of the expression. Example:
+
+[source,java]
+-----------------------------------------------------
+...
+ private String someValue
+...
+ from('direct:test')
+ .transform { it.in.body.reverse() + someValue }
+ .setHeader("myHeader") { someValue.reverse() }
+...
+-----------------------------------------------------
+
+[[GroovyDSL-PredicateClosures]]
+Predicate Closures
+
+All Java DSL parameters of type `org.apache.camel.Predicate` can be
+replaced by a closure that accepts an object of type
+`org.apache.camel.Exchange` as only parameter. The return value of the
+closure is translated into a boolean value representing the result of
+the predicate. Example:
+
+[source,java]
+------------------------------------------------------
+...
+ private String someValue
+
+ // This time, the closure is stored in a variable
+ def pred = { Exchange e -> e.in.body != someValue }
+...
+ from('direct:test')
+ .filter(pred)
+...
+------------------------------------------------------
+
+[[GroovyDSL-AggregationStrategyClosures]]
+Aggregation Strategy Closures
+
+Java DSL parameters of type
+`org.apache.camel.processor.aggregate.AggregationStrategy` can be
+replaced by a closure that accepts two objects of type
+`org.apache.camel.Exchange` representing the two Exchanges to be
+aggregated. The return value of the closure must be the aggregated
+Exchange. Example:
+
+[source,java]
+-------------------------------------------------------------------------
+...
+ private String separator
+...
+ from('direct:test1')
+ .enrich('direct:enrich') { Exchange original, Exchange resource ->
+ original.in.body += resource.in.body + separator
+ original // don't forget to return resulting exchange
+ }
+...
+-------------------------------------------------------------------------
+
+[[GroovyDSL-Genericclosurebridges]]
+Generic closure bridges
+
+In addition to the above-mentioned DSL extensions, you can use closures
+even if no DSL method signature with closure parameters is available.
+Assuming there's no `filter(Closure)` method, you could instead write:
+
+[source,java]
+---------------------------------------------------------
+...
+ private String someValue
+
+ // This time, the closure is stored in a variable
+ def pred = { Exchange e -> e.in.body != someValue }
+...
+ from('direct:test')
+ // predicate(Closure) -> org.apache.camel.Predicate
+ .filter(predicate(pred))
+...
+---------------------------------------------------------
+
+Similarly, `expression(Closure)` returns a Camel expression,
+`processor(Closure)` returns a Processor, and `aggregator(Closure)`
+returns an AggregationStrategy.
+
+[[GroovyDSL-UsingGroovyXMLprocessing]]
+Using Groovy XML processing
++++++++++++++++++++++++++++
+
+Groovy provides special http://groovy-lang.org/processing-xml.html[XML
+processing support] through its `XmlParser`, `XmlNodePrinter` and
+`XmlSlurper` classes. camel-groovy provides two
+link:data-format.html[data formats] to use these classes directly in
+your routes.
+
+*Unmarshal XML with XmlParser*
+
+[source,java]
+-----------------------------------------------------
+...
+ from('direct:test1')
+ .unmarshal().gnode()
+ // message body is now of type groovy.util.Node
+...
+-----------------------------------------------------
+
+By default, XML processing is _namespace-aware_. You can change this by
+providing a boolean `false` parameter.
+
+*Unmarshal XML with XmlSlurper*
+
+[source,java]
+---------------------------------------------------------------------------
+...
+ from('direct:test1')
+ .unmarshal().gpath(false) // explicitly namespace-unaware
+ // message body is now of type groovy.util.slurpersupport.GPathResult
+...
+---------------------------------------------------------------------------
+
+Currently, marshalling is only supported for `groovy.util.Node` objects.
+
+*Marshal XML with XmlNodePrinter*
+
+[source,java]
+------------------------------------------------------
+...
+ from('direct:test1')
+ // message body must be of type groovy.util.Node
+ .marshal().gnode()
+...
+------------------------------------------------------
+
+[[GroovyDSL-UsingGroovyGStrings]]
+Using Groovy GStrings
++++++++++++++++++++++
+
+Groovy
+http://docs.groovy-lang.org/latest/html/documentation/index.html#all-strings[GStrings]
+are declared inside double-quotes and can contain arbitrary Groovy
+expressions like accessing properties or calling methods, e.g.
+
+[source,java]
+-----------------------------------------
+def x = "It is currently ${ new Date() }"
+-----------------------------------------
+
+Because GStrings aren't Strings, camel-groovy adds the necessary
+link:type-converter.html[TypeConverter] to automatically turn them into
+the required type.
+
+[[GroovyDSL-CustomDSLextensions]]
+Custom DSL extensions
++++++++++++++++++++++
+
+You can easily define your custom extensions - be it as a Java DSL
+extension for your Groovy routes or for any other class unrelated to
+Camel. All you have to do is to write your extension methods and provide
+a extension module descriptor - the details are described in the
+http://www.groovy-lang.org/metaprogramming.html#_extension_modules[Groovy
+documentation]. And as long as you don't require other extension
+methods, you can even use plain Java code to achieve this! +
+ As an example, let's write two DSL extensions to make commonly used DSL
+methods more concise:
+
+*MyExtension.java*
+
+[source,java]
+-------------------------------------------------------------------------------------------------------------------------------
+import org.apache.camel.Endpoint;
+import org.apache.camel.Predicate;
+
+public final class MyExtension {
+ private MyExtension() {
+ // Utility Class
+ }
+
+ // Set the id of a route to its consumer URI
+ public static RouteDefinition fromId(RouteDefinition delegate, String uri) {
+ return delegate.from(uri).routeId(uri);
+ }
+
+ public static RouteDefinition fromId(RouteDefinition delegate, Endpoint endpoint) {
+ return delegate.from(endpoint).routeId(endpoint.getEndpointUri());
+ }
+
+ // Make common choice pattern more concise
+
+ public static ProcessorDefinition<?> fork(ProcessorDefinition<?> delegate, String uri1, String uri2, Predicate predicate) {
+ return delegate.choice().when(predicate).to(uri1).otherwise().to(uri2);
+ }
+
+}
+-------------------------------------------------------------------------------------------------------------------------------
+
+Add a corresponding extension module descriptor to `META-INF/services`:
+
+*META-INF/services/org.codehaus.groovy.runtime.ExtensionModule*
+
+[source,java]
+----------------------------
+moduleName=my-extension
+moduleVersion=2.11
+extensionClasses=MyExtension
+staticExtensionClasses=
+----------------------------
+
+And now your Groovy route can look like this:
+
+*MyRoute.groovy*
+
+[source,java]
+------------------------------------------------------------
+...
+ fromId('direct:test1')
+ .fork('direct:null','direct:not-null',body().isNull())
+...
+------------------------------------------------------------
+
+Using the plain Java DSL, the route would look something like this:
+
+*MyRoute.java*
+
+[source,java]
+-----------------------------------
+...
+ from("direct:test1")
+ .routeId("direct:test1")
+ .choice()
+ .when(body().isNull())
+ .to("direct:null")
+ .otherwise()
+ .to("direct:not-null");
+...
+-----------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/0550185a/components/camel-groovy/src/main/docs/groovy.adoc
----------------------------------------------------------------------
diff --git a/components/camel-groovy/src/main/docs/groovy.adoc b/components/camel-groovy/src/main/docs/groovy.adoc
new file mode 100644
index 0000000..87014fa
--- /dev/null
+++ b/components/camel-groovy/src/main/docs/groovy.adoc
@@ -0,0 +1,204 @@
+[[Groovy-Groovy]]
+Groovy
+~~~~~~
+
+Camel supports http://groovy.codehaus.org/[Groovy] among other
+link:scripting-languages.html[Scripting Languages] to allow an
+link:expression.html[Expression] or link:predicate.html[Predicate] to be
+used in the link:dsl.html[DSL] or link:xml-configuration.html[Xml
+Configuration].
+
+To use a Groovy expression use the following Java code
+
+[source,java]
+---------------------------------------
+... groovy("someGroovyExpression") ...
+---------------------------------------
+
+For example you could use the *groovy* function to create an
+link:predicate.html[Predicate] in a link:message-filter.html[Message
+Filter] or as an link:expression.html[Expression] for a
+link:recipient-list.html[Recipient List]
+
+[[Groovy-Options]]
+Groovy Options
+^^^^^^^^^^^^^^
+
+// component options: START
+// component options: END
+
+// endpoint options: START
+// endpoint options: END
+
+[[Groovy-CustomizingGroovyShell]]
+Customizing Groovy Shell
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes you may need to use custom `GroovyShell` instance in your
+Groovy expressions. To provide custom `GroovyShell`, add implementation
+of the `org.apache.camel.language.groovy.GroovyShellFactory` SPI
+interface to your Camel registry. For example after adding the following
+bean to your Spring context...
+
+[source,java]
+----------------------------------------------------------------------
+public class CustomGroovyShellFactory implements GroovyShellFactory {
+
+ public GroovyShell createGroovyShell(Exchange exchange) {
+ ImportCustomizer importCustomizer = new ImportCustomizer();
+ importCustomizer.addStaticStars("com.example.Utils");
+ CompilerConfiguration configuration = new CompilerConfiguration();
+ configuration.addCompilationCustomizers(importCustomizer);
+ return new GroovyShell(configuration);
+ }
+
+}
+----------------------------------------------------------------------
+
+...Camel will use your custom GroovyShell instance (containing your
+custom static imports), instead of the default one.
+
+[[Groovy-Example]]
+Example
+^^^^^^^
+
+[source,java]
+------------------------------------------------------------------------------------------------
+// lets route if a line item is over $100
+from("queue:foo").filter(groovy("request.lineItems.any { i -> i.value > 100 }")).to("queue:bar")
+------------------------------------------------------------------------------------------------
+
+And the Spring DSL:
+
+[source,xml]
+-----------------------------------------------------------------------------
+ <route>
+ <from uri="queue:foo"/>
+ <filter>
+ <groovy>request.lineItems.any { i -> i.value > 100 }</groovy>
+ <to uri="queue:bar"/>
+ </filter>
+ </route>
+-----------------------------------------------------------------------------
+
+[[Groovy-ScriptContext]]
+ScriptContext
+^^^^^^^^^^^^^
+
+The JSR-223 scripting languages ScriptContext is pre configured with the
+following attributes all set at `ENGINE_SCOPE`:
+
+[width="100%",cols="10%,10%,80%",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.
+
+[[Groovy-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:
+
+[[Groovy-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".
+
+[source,java]
+------------------------------------------------------------------------------------------------------------------------------
+.setHeader("myHeader").groovy(""context.resolvePropertyPlaceholders( + '{{' + request.headers.get('foo') + '}}' + ")")
+------------------------------------------------------------------------------------------------------------------------------
+
+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'))")
+---------------------------------------------------------------------------------------
+
+[[Groovy-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")
+-------------------------------------------------------------------
+
+[[Groovy-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
+-------------------------------------------------------------
+
+[[Groovy-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>
+---------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/0550185a/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 22118b3..ba794ad 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -141,6 +141,8 @@
* [Google Mail](google-mail.adoc)
* [Gora](gora.adoc)
* [Grape](grape.adoc)
+ * [Groovy](groovy.adoc)
+ * [Groovy DSL](groovy-dsl.adoc)
* [Ironmq](ironmq.adoc)
* [JMS](jms.adoc)
* [JMX](jmx.adoc)