components/camel-groovy/src/main/docs/groovy-language.adoc

[[groovy-language]]
= Groovy Language

*Since Camel 1.3*

Camel supports http://groovy.codehaus.org/[Groovy] among other
Scripting Languages to allow an
Expression or Predicate to be
used in the DSL or xref:manual::xml-configuration.adoc[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
Predicate in a xref:manual::filter-eip.adoc[Message Filter] or as an Expression for a
Recipient List

== Groovy Options



// language options: START
The Groovy language supports 1 options, which are listed below.



[width="100%",cols="2,1m,1m,6",options="header"]
|===
| Name | Default | Java Type | Description
| trim | true | Boolean | Whether to trim the value to remove leading and trailing whitespaces and line breaks
|===
// language options: END
// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-groovy-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 2 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.language.groovy.enabled* | Enable groovy language | true | Boolean
| *camel.language.groovy.trim* | Whether to trim the value to remove leading and trailing whitespaces and line breaks | true | Boolean
|===
// spring-boot-auto-configure options: END




== 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.

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

== 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` |Function with a `resolve` method to make it easier to use
Camels xref:properties-component.adoc[Properties] component from scripts. See
further below for example.
|=======================================================================

See Scripting Languages for the list of
languages with explicit DSL support.

== Additional arguments to ScriptingEngine

*Since 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:

== Using properties function

*Since Camel 2.9*

If you need to use the xref:properties-component.adoc[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(&#39;foo&#39;) + '}}' + ")")
------------------------------------------------------------------------------------------------------------------------------

You can use the properties function and the same example is simpler:

[source,java]
---------------------------------------------------------------------------------------
.setHeader("myHeader").groovy("properties.resolve(request.headers.get(&#39;foo&#39;))")
---------------------------------------------------------------------------------------

== Loading script from external resource

*Since 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")
-------------------------------------------------------------------

== How to get the result from multiple statements script

*Since 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
-------------------------------------------------------------

== Dependencies

To use scripting languages in your camel routes you need to add a
dependency on *camel-groovy*.

If you use Maven you could just add the following to your `pom.xml`,
substituting the version number for the latest and greatest release (see
the download page for the latest versions).

[source,xml]
---------------------------------------
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-groovy</artifactId>
  <version>x.x.x</version>
</dependency>
---------------------------------------