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

Full editing pass for the Reference Guide

Browse Source 
I went through all the Asciidoc files to correct spelling, grammar,
punctuation, and usage. Wherever possible, I also made it more clear and more concise.
I also added links wherever they were reasonable.

Accommodating changes that came while I was editing

Various folks made changes (one of which I recommended) to the documents
while I spent a month editing.
I had to edit that new and changed content as well, so I need this second commit.

Accommodating Artem's requested changes for `aggregator.adoc`

Artem reviewed `aggregator.adoc` as a starting point, so that
he could get some questions answered.
I have made the changes he requested (and answered his questions on Github).
This commit is contained in:
Jay Bryant
2018-06-28 13:43:24 -05:00
committed by Artem Bilan
parent 11d39b7da1
commit f3bf2a68d6
87 changed files with 14163 additions and 13464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
src/reference/asciidoc/scripting.adoc
View File

@@ -1,34 +1,32 @@
[[scripting]]
=== Scripting support
=== Scripting Support
With Spring Integration 2.1 we've added support for the http://jcp.org/aboutJava/communityprocess/pr/jsr223/[JSR223 Scripting for Java specification], 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 http://java.sun.com/developer/technicalArticles/J2SE/Desktop/scripting/[documentation]
Spring Integration 2.1 added support for the http://jcp.org/aboutJava/communityprocess/pr/jsr223/[JSR223 Scripting for Java specification], introduced in Java version 6.
It lets you 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, see the https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/api.html[documentation]
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.
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 http://www.groovy-lang.org/[Groovy] and http://jruby.org/[JRuby] 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.
The http://www.groovy-lang.org/[Groovy] and http://jruby.org/[JRuby] projects provide JSR233 support in their standard distributions.
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.
A particular implementation's compatibility with Spring Integration depends on how well it conforms to the specification and the implementer's interpretation of the specification.
TIP: If you plan to use Groovy as your scripting language, we recommended you use <<groovy,Spring-Integration's Groovy Support>> as it offers additional features specific to Groovy.
_However you will find this section relevant as well_.
However, this section is relevant as well.
[[scripting-config]]
==== Script configuration
==== Script Configuration
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 `ScriptExecutingMessageProcessor` which will bind the Message Payload to a variable named `payload` and the Message Headers to a `headers` 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:
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 that contains the script.
To enable scripting support, Spring Integration defines a `ScriptExecutingMessageProcessor`, which binds the message payload to a variable named `payload` and the message headers to a `headers` variable, both accessible within the script execution context.
All you need to do is write a script that uses these variables.
The following pair of examples show sample configurations that create filters:
_Filter_
.Filter
====
[source,xml]
----
<int:filter input-channel="referencedScriptInput">
@@ -43,83 +41,104 @@ _Filter_
</int-script:script>
</int:filter>
----
====
Here, you see that the script can be included inline or can reference a resource location via the `location` attribute.
Additionally the `lang` attribute corresponds to the language name (or JSR223 alias)
As the preceding examples show, the script can be included inline or can be included by reference to a resource location (by using the `location` attribute).
Additionally, the `lang` attribute corresponds to the language name (or its JSR223 alias)
Other Spring Integration endpoint elements which support scripting include _router_, _service-activator_, _transformer_, and _splitter_.
Other Spring Integration endpoint elements that support scripting include `router`, `service-activator`, `transformer`, and `splitter`.
The scripting configuration in each case would be identical to the above (besides the endpoint element).
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 `refresh-check-delay` attribute on the _script_ element:
Another useful feature of scripting support is the ability to update (reload) scripts without having to restart the application context.
To do so, specify the `refresh-check-delay` attribute on the `script` element, as the following example shows:
====
[source,xml]
----
<int-script:script location="..." refresh-check-delay="5000"/>
----
====
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.
In the preceding example, the script location is checked for updates every 5 seconds.
If the script is updated, any invocation that occurs later than 5 seconds since the update results in running the new script.
Consider the following example:
====
[source,xml]
----
<int-script:script location="..." refresh-check-delay="0"/>
----
====
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.
In the preceding example, the context is updated with any script modifications as soon as such modification occurs, providing a simple mechanism for 'real-time' configuration.
Any negative value means the script is not reloaded after initialization of the application context.
This is the default behavior.
The following example shows a script that never updates:
IMPORTANT: Inline scripts can not be reloaded.
====
[source,xml]
----
<int-script:script location="..." refresh-check-delay="-1"/>
----
====
_Script variable bindings_
IMPORTANT: Inline scripts can not be reloaded.
[[scripting-script-variable-bindings]]
===== Script Variable Bindings
Variable bindings are required to enable the script to reference variables externally provided to the script's execution context.
As we have seen, `payload` and `headers` are used as binding variables by default.
You can bind additional variables to a script via `<variable>` sub-elements:
By default, `payload` and `headers` are used as binding variables.
You can bind additional variables to a script by using `<variable>` elements, as the following example shows:
====
[source,xml]
----
<script:script lang="js" location="foo/bar/MyScript.js">
<script:variable name="foo" value="foo"/>
<script:variable name="bar" value="bar"/>
<script:variable name="foo" value="thing1"/>
<script:variable name="bar" value="thing2"/>
<script:variable name="date" ref="date"/>
</script:script>
----
====
As shown in the above example, you can bind a script variable either to a scalar value or a Spring bean reference.
Note that `payload` and `headers` will still be included as binding variables.
As shown in the preceding example, you can bind a script variable either to a scalar value or to a Spring bean reference.
Note that `payload` and `headers` are still included as binding variables.
With _Spring Integration 3.0_, in addition to the `variable` sub-element, the `variables` attribute has been introduced.
This attribute and `variable` sub-elements aren't mutually exclusive and you can combine them within one `script` component.
However variables must be unique, regardless of where they are defined.
Also, since _Spring Integration 3.0_, variable bindings are allowed for inline scripts too:
With Spring Integration 3.0, in addition to the `variable` element, the `variables` attribute has been introduced.
This attribute and the `variable` elements are not mutually exclusive, and you can combine them within one `script` component.
However, variables must be unique, regardless of where they are defined.
Also, since Spring Integration 3.0, variable bindings are allowed for inline scripts, too, as the following example shows:
====
[source,xml]
----
<service-activator input-channel="input">
<script:script lang="ruby" variables="foo=FOO, date-ref=dateBean">
<script:variable name="bar" ref="barBean"/>
<script:variable name="baz" value="bar"/>
<script:script lang="ruby" variables="thing1=THING1, date-ref=dateBean">
<script:variable name="thing2" ref="thing2Bean"/>
<script:variable name="thing3" value="thing2"/>
<![CDATA[
payload.foo = foo
payload.foo = thing1
payload.date = date
payload.bar = bar
payload.baz = baz
payload.bar = thing2
payload.baz = thing3
payload
]]>
</script:script>
</service-activator>
----
====
The example above shows a combination of an inline script, a `variable` sub-element and a `variables` attribute.
The `variables` attribute is a comma-separated value, where each segment contains an '=' separated pair of the variable and its value.
The variable name can be suffixed with `-ref`, as in the `date-ref` variable above.
That means that the binding variable will have the name `date`, but the value will be a reference to the `dateBean` bean from the application context.
This may be useful when using _Property Placeholder Configuration_ or command line arguments.
The preceding example shows a combination of an inline script, a `variable` element, and a `variables` attribute.
The `variables` attribute contains a comma-separated value, where each segment contains an '=' separated pair of the variable and its value.
The variable name can be suffixed with `-ref`, as in the `date-ref` variable in the preceding example.
That means that the binding variable has the name, `date`, but the value is a reference to the `dateBean` bean from the application context.
This may be useful when using property placeholder configuration or command-line arguments.
If you need more control over how variables are generated, you can implement your own Java class using the `ScriptVariableGenerator` strategy:
If you need more control over how variables are generated, you can implement your own Java class that uses the `ScriptVariableGenerator` strategy, which is defined by the following interface:
====
[source,java]
----
public interface ScriptVariableGenerator {
@@ -128,11 +147,14 @@ public interface ScriptVariableGenerator {
}
----
====
This interface requires you to implement the method `generateScriptVariables(Message)`.
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 `ScriptVariableGenerator` and reference it with the `script-variable-generator` attribute:
This interface requires you to implement the `generateScriptVariables(Message)` method.
The message argument lets you access any data available in the message payload and headers, and the return value is the `Map` of bound variables.
This method is called every time the script is executed for a message.
The following example shows how to provide an implementation of `ScriptVariableGenerator` and reference it with the `script-variable-generator` attribute:
====
[source,xml]
----
<int-script:script location="foo/bar/MyScript.groovy"
@@ -140,7 +162,9 @@ All you need to do is provide an implementation of `ScriptVariableGenerator` and
<bean id="variableGenerator" class="foo.bar.MyScriptVariableGenerator"/>
----
====
If a `script-variable-generator` is not provided, script components use `DefaultScriptVariableGenerator`, which merges any provided `<variable>` s with _payload_ and _headers_ variables from the `Message` in its `generateScriptVariables(Message)` method.
If a `script-variable-generator` is not provided, script components use `DefaultScriptVariableGenerator`, which merges any provided `<variable>` elements with `payload` and `headers` variables from the `Message` in its `generateScriptVariables(Message)` method.
IMPORTANT: You cannot provide both the `script-variable-generator` attribute and `<variable>` sub-element(s) as they are mutually exclusive.
IMPORTANT: You cannot provide both the `script-variable-generator` attribute and `<variable>` element(s).
They are mutually exclusive.