spring-integration/src/reference/docbook/scripting.xml

<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="scripting" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:ns5="http://www.w3.org/1999/xhtml"
         xmlns:ns4="http://www.w3.org/1998/Math/MathML"
         xmlns:ns3="http://www.w3.org/2000/svg"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Scripting support</title>

  <para>With Spring Integration 2.1 we've added support for the <ulink url="http://jcp.org/aboutJava/communityprocess/pr/jsr223/">
  JSR223 Scripting for Java specification</ulink>, 
  introduced in Java version 6. This allows you to use scripts written in any supported language including 
  Ruby/JRuby, Javascript and Groovy to provide the logic for various integration components similar to the way 
  the Spring Expression Language (SpEL) is used in Spring Integration. For more information about JSR223 please refer to the 
  <ulink url="http://java.sun.com/developer/technicalArticles/J2SE/Desktop/scripting/">documentation</ulink>
    <important>
    Note that this feature requires Java 6 or higher. Sun developed a JSR223 reference implementation which works with 
    Java 5 but it is not officially supported and we have not tested it with Spring Integration.
    </important>
  </para>
  <para>
  In order to use a JVM scripting language, a JSR223 implementation for that language must be included in your class path. Java 6 natively
  supports Javascript. The <ulink url="http://groovy.codehaus.org">Groovy</ulink> and 
  <ulink url="http://jruby.org/">JRuby</ulink> projects provide JSR233 support in their standard distribution.
   Other language implementations may be available or under development. Please refer to the appropriate project website for more information.
   <important>
   Various JSR223 language implementations have been developed by third parties. A particular implementation's compatibility 
   with Spring Integration depends on how well it conforms to the specification and/or the implementer's interpretation of the specification. 
    </important>  
  <tip>If you plan to use Groovy as your scripting language, we recommended you use <xref linkend="groovy">Spring-Integration's Groovy Support</xref> 
  as it offers additional features specific to Groovy. <emphasis>However you will find this section relevant as well</emphasis>.
  </tip>
</para>

  <section id="scripting-config">
    <title>Script configuration</title>

    <para>Depending on the complexity of your integration requirements
    scripts may be provided inline as CDATA in XML configuration or as a
    reference to a Spring resource containing the script. To enable scripting support
    Spring Integration defines a
    <classname>ScriptExecutingMessageProcessor</classname> which will
    bind the  Message Payload to a
    variable named <code>payload</code> and the Message Headers to a <code>headers</code>
    variable, both accessible within the script execution context. All that is left for you to do is
    write a script that uses these variables. Below are a couple of sample configurations:</para>

    <para><emphasis>Filter</emphasis> <programlisting language="xml">&lt;int:filter input-channel="referencedScriptInput"&gt;
   &lt;int-script:script lang="ruby" location="some/path/to/ruby/script/RubyFilterTests.rb"/&gt;
&lt;/int:filter&gt;

&lt;int:filter input-channel="inlineScriptInput"&gt;
     &lt;int-script:script lang="groovy"&gt;&lt;![CDATA[
     return payload == 'good'
   ]]&gt;&lt;/int-script:script&gt;
&lt;/int:filter&gt;</programlisting>

    Here, you see that the script can be included inline
    or can reference a resource location via the <code>location</code> attribute. Additionally the <code>lang</code> attribute 
    corresponds to the language name (or JSR223 alias)</para>

    <para>Other Spring Integration endpoint elements which support scripting include <emphasis>router</emphasis>, <emphasis>service-activator</emphasis>,
    <emphasis>transformer</emphasis>, and <emphasis>splitter</emphasis>. The scripting configuration in each case would be identical to the above 
    (besides the endpoint element).
    </para>

    <para>Another useful feature of Scripting support is the ability to update (reload) scripts without 
    having to restart the Application Context. To accomplish this, specify the <code>refresh-check-delay</code> 
    attribute on the <emphasis>script</emphasis> element:

    <programlisting language="xml">&lt;int-script:script location="..." refresh-check-delay="5000"/&gt;</programlisting>

    In the above example, the script location will be checked for updates every 5 seconds. If the script is updated,
    any invocation that occurs later than 5 seconds since the update will result in execution of the new script. 

    <programlisting language="xml">&lt;int-script:script location="..." refresh-check-delay="0"/&gt;</programlisting>

    In the above example the context will be updated with any script modifications
    as soon as such modification occurs, providing a simple mechanism for 'real-time' configuration.

	Any negative number value means the script will not be reloaded after initialization of the application context.
	This is the default behavior. <important>Inline scripts can not be reloaded.</important></para>

    <programlisting language="xml">&lt;int-script:script location="..." refresh-check-delay="-1"/&gt;</programlisting>
        
    <para><emphasis>Script variable bindings</emphasis> </para>
    
    <para>
    Variable bindings are required to enable the script to reference variables externally provided to the script's execution context. 
    As we have seen, <code>payload</code> and <code>headers</code> are used as binding variables by default. You can bind additional variables 
    to a script via <code>&lt;variable&gt;</code> sub-elements:
	<programlisting language="xml"><![CDATA[<script:script lang="js" location="foo/bar/MyScript.js">
	<script:variable name="foo" value="foo"/>
	<script:variable name="bar" value="bar"/>
	<script:variable name="date" ref="date"/>
</script:script>]]></programlisting>
	As shown in the above example, you can bind a script variable either to a scalar value or a Spring bean reference. Note that
	<code>payload</code> and <code>headers</code> will still be included as binding variables.
	
  </para>
  <para>
    If you need more control over how variables are generated, you can implement your own Java class 
    using the <classname>ScriptVariableGenerator</classname> strategy:
  <programlisting language="java"><![CDATA[public interface ScriptVariableGenerator {
  
	Map<String, Object> generateScriptVariables(Message<?> message);
	
}]]></programlisting>

	This interface requires you to implement the method <code>generateScriptVariables(Message)</code>. The Message
	argument allows you to access any data available in the Message payload and headers and the return value is
	the Map of bound variables. This method will be called every time the script is executed for a Message. All you need to do is 
    provide an implementation of <classname>ScriptVariableGenerator</classname> and reference it with the <code>script-variable-generator</code>
	attribute:
   <programlisting language="xml"><![CDATA[<int-script:script location="foo/bar/MyScript.groovy"
				script-variable-generator="variableGenerator"/>

<bean id="variableGenerator" class="foo.bar.MyScriptVariableGenerator"/>]]></programlisting>
	
	  <important>
	  You cannot provide both the <code>script-variable-generator</code> attribute and <code>&lt;variable&gt;</code> sub-element(s) 
	  as they are mutually exclusive. Also, custom variable bindings cannot be used with an inline script.
	  </important>
	</para>
 </section>
</section>