components/camel-ruby/src/main/docs/ruby.adoc

[[Ruby-Ruby]]
Ruby
~~~~

Camel supports http://www.ruby-lang.org/en/[Ruby] 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 Ruby expression use the following Java code

[source,java]
-----------------------------------
... ruby("someRubyExpression") ... 
-----------------------------------

For example you could use the *ruby* 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]

[[Ruby-Example]]
Example
^^^^^^^

In the sample below we use Ruby to create a
link:predicate.html[Predicate] use in the route path, to route exchanges
from admin users to a special queue.

[source,java]
-------------------------------------------------------------------------------------
    from("direct:start")
        .choice()
            .when().ruby("$request.headers['user'] == 'admin'").to("seda:adminQueue")
        .otherwise()
            .to("seda:regularQueue");
-------------------------------------------------------------------------------------

And a Spring DSL sample as well:

[source,xml]
----------------------------------------------------------------
    <route>
        <from uri="direct:start"/>
        <choice>
            <when>
                <ruby>$request.headers['user'] == 'admin'</ruby>
                <to uri="seda:adminQueue"/>
            </when>
            <otherwise>
                <to uri="seda:regularQueue"/>
            </otherwise>
        </choice>
    </route>
----------------------------------------------------------------

[[Ruby-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.

[[Ruby-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:

[[Ruby-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]
{% raw %}
--------------------------------------------------------------------------------------------------------------
.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'))")
-------------------------------------------------------------------------------

[[Ruby-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")
-------------------------------------------------------------------

[[Ruby-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
-------------------------------------------------------------

[[Ruby-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>
---------------------------------------