Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

INT-3126: Document DefaultScriptVariableGenerator

Browse Source 
JIRA: https://jira.springsource.org/browse/INT-3126
This commit is contained in:
Artem Bilan
2013-10-09 14:45:22 +03:00
committed by Gary Russell
parent 01b470f0c7
commit 0f3ac4d867
4 changed files with 45 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
spring-integration-scripting/src/main/java/org/springframework/integration/scripting/DefaultScriptVariableGenerator.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2011 the original author or authors.
* Copyright 2002-2013 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -24,6 +24,10 @@ import org.springframework.integration.Message;
import org.springframework.util.CollectionUtils;
/**
* A default {@link ScriptVariableGenerator} implementation; used by script processors.
* The result of {@link #generateScriptVariables(Message)} is a {@link Map} of any provided {@code variables}
* plus {@code payload} and {@code headers} from the {@code Message} argument.
*
* @author Oleg Zhurakousky
* @author Mark Fisher
* @since 2.0.2
@@ -53,7 +57,7 @@ public class DefaultScriptVariableGenerator implements ScriptVariableGenerator {
if (!CollectionUtils.isEmpty(this.variableMap)) {
for (Map.Entry<String, Object> entry : this.variableMap.entrySet()) {
scriptVariables.put(entry.getKey(), entry.getValue());
}
}
}
return scriptVariables;
}

5
spring-integration-scripting/src/main/java/org/springframework/integration/scripting/ScriptVariableGenerator.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2011 the original author or authors.
* Copyright 2002-2013 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -21,6 +21,9 @@ import java.util.Map;
import org.springframework.integration.Message;
/**
* Strategy interface to provide a {@link Map} of variables to the script execution context.
* Variables may be extracted from the {@link Message} argument.
*
* @author Oleg Zhurakousky
* @since 2.0.2
*/

2
src/reference/docbook/groovy.xml
View File

@@ -57,6 +57,8 @@
Setting a custom GroovyObjectCustomizer is not mutually exclusive with <code>&lt;variable&gt;</code> sub-elements or
the <code>script-variable-generator</code> attribute. It can also be provided when defining an inline script.
For more information regarding <code>&lt;variable&gt;</code> and <code>script-variable-generator</code>, see the
paragraph '<emphasis>Script variable bindings</emphasis>' of <xref linkend="scripting-config"/>.
</para>
</section>

61
src/reference/docbook/scripting.xml
View File

@@ -8,26 +8,26 @@
<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
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
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
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>
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>
@@ -50,28 +50,30 @@
&lt;/int:filter&gt;
&lt;int:filter input-channel="inlineScriptInput"&gt;
&lt;int-script:script lang="groovy"&gt;&lt;![CDATA[
&lt;int-script:script lang="groovy"&gt;
&lt;![CDATA[
return payload == 'good'
]]&gt;&lt;/int-script:script&gt;
]]&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
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
<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>
<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.
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>
@@ -82,12 +84,12 @@
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
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"/>
@@ -96,29 +98,32 @@
</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
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
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>
If a <code>script-variable-generator</code> is not provided, script components use
<classname>org.springframework.integration.scripting.DefaultScriptVariableGenerator</classname>, which merges
any provided <code>&lt;variable&gt;</code>s with <emphasis>payload</emphasis> and <emphasis>headers</emphasis>
variables from the <code>Message</code> in its <code>generateScriptVariables(Message)</code> method.
<important>
You cannot provide both the <code>script-variable-generator</code> attribute and <code>&lt;variable&gt;</code> sub-element(s)
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>