f30da932e8
This is a significant update to the build system, including the changes listed below. README.md has been updated with instructions on the most important day-to-day commands. - Eliminate buildSrc submodule In favor of using the new bundlor and docbook-reference plugins. The net effect is a large reduction in number of lines of build code. Common docbook resources, stylesheets, etc are stored directly in the docbook plugin. This means that --recursive is no longer required when cloning and there will never be a need to use `git submodule` commands. README files have been updated to reflect. Use of the new bundlor plugin also means the removal of template.mf files from the source tree in favor of an inline approach. See build.gradle for details. Bundlor 'import templates' are built up programmatically and kept physically close to gradle dependency declarations, leading to more convenience when changing these values and hopefully fewer errors / version inconsistencies over time. Certain tests depended on the presence of template.mf files, all of which have recently been removed from the source tree in favor of the new bundlor plugin which allows for inlining bundlor configuration within the Gradle build script. These tests now create temp files using the java.io.File API instead. - Upgrade to Gradle 1.0-milestone-6 The m6 release is significantly faster when resolving dependencies and has a number of valuable new features over the earlier m3 version. Review the release notes for Gradle 1.0-milestone-6 online for full details. - Switch to repo.springsource.org repository Previously the project build declared as many repositories as necessary to resolve all project dependencies. Now depending on a single 'virtual repository' defined within the SpringSource Artifactory instance at http://repo.springsource.org. Currently, the virtual repository in use is 'libs-milestone', which allows for the resolution of all "milestone-or-better" versions of all S2 and third-party dependencies. Should snapshot dependencies become required, this value may be changed from 'libs-milestone' to 'libs-snapshot'. To build only against GA releases, change the value to 'libs-release'. - New build plan(s) Spring Integration build plans have been updated to use the Artifactory Bamboo plugin and publish to repo.springsource.org. Build plans have names like 2.1.x to reflect the version under development, not necessarily the name of the branch, as this may change over time and across major releases. - Improve release process As mentioned above, Spring Integration will now use the Artifactory Bamboo plugin to publish releases and also use Artifactory's support for pushing builds directly into Maven Central via oss.sonatype.org. Generate poms that contain all necessary fields for onboarding at Maven central (scm, developers, organization, licenses, etc). Generate -source and -javadoc poms to comply with Maven Central onboarding rules (and for general good practice anyway). Generation of PGP signatures, sha1 and md5 checksums are all handled automatically by Artifactory. These are also requirements for automated entry into Maven Central. - Remove source-level pom generation Automatic generation of Maven poms suitable for use in building Spring Integration is no longer supported. Generation and publication of poms for the purpose of dependency management remains supported. Sonar support has to date depended on these poms, but will be switched over to use the Gradle Sonar plugin shortly. - Eliminate docs subproject Move docs/src to the root of the project and eliminate docs as a formal subproject. This simplifies the build in a number of ways, including removing the need for distinguishing between 'subprojects' and 'javaprojects' as well as allowing users to build both 'api' and 'reference' docs without qualifying with a ':docs' prefix. Also rename the src/info directory to src/dist to better reflect that these files are packaged with the distribution. For example, the readme.txt there is really the distribution readme, distinct from the README.md at the root of the project which is for building from source, etc.
266 lines
16 KiB
XML
266 lines
16 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="claim-check"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Claim Check</title>
|
|
|
|
<section id="claim-check-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
In the earlier sections we've covered several Content Enricher type components that help you deal with situations where a
|
|
message is missing a piece of data. We also discussed Content Filtering which lets you remove data items from a message.
|
|
However there are times when we want to hide data temporarily. For example, in a distributed system we may receive a
|
|
Message with a very large payload. Some intermittent message processing steps may not need access to this payload and some may only
|
|
need to access certain headers, so carrying the large Message payload through each processing step may cause performance degradation,
|
|
may produce a security risk, and may make debugging more difficult.
|
|
</para>
|
|
|
|
<para>
|
|
The <link href="http://www.eaipatterns.com/StoreInLibrary.html">Claim Check</link> pattern describes a mechanism that allows you
|
|
to store data in a well known place while only maintaining a pointer (Claim Check) to where that data is located. You can pass that
|
|
pointer around as a payload of a new Message thereby allowing any component within the message flow to get the actual data as soon as
|
|
it needs it. This approach is very similar to the Certified Mail process where you'll get a Claim Check in your mailbox and
|
|
would have to go to the Post Office to claim your actual package. Of course it's also the same idea as baggage-claim on a flight
|
|
or in a hotel.
|
|
</para>
|
|
|
|
<para>
|
|
Spring Integration provides two types of Claim Check transformers:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><emphasis>Incoming Claim Check Transformer</emphasis></listitem>
|
|
<listitem><emphasis>Outgoing Claim Check Transformer</emphasis></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Convenient namespace-based mechanisms are available to configure them.
|
|
</para>
|
|
|
|
</section>
|
|
<section id="claim-check-in">
|
|
<title>Incoming Claim Check Transformer</title>
|
|
|
|
<para>
|
|
An <emphasis>Incoming Claim Check Transformer</emphasis> will transform an incoming Message by storing it in the Message Store
|
|
identified by its <code>message-store</code> attribute.
|
|
</para>
|
|
|
|
<programlisting language="xml"><![CDATA[<int:claim-check-in id="checkin"
|
|
input-channel="checkinChannel"
|
|
message-store="testMessageStore"
|
|
output-channel="output"/>]]></programlisting>
|
|
|
|
<para>
|
|
In the above configuration the Message that is received on the <code>input-channel</code> will be persisted to the
|
|
Message Store identified with the <code>message-store</code> attribute and indexed with generated ID. That ID is the
|
|
Claim Check for that Message.
|
|
The Claim Check will also become the payload of the new (transformed) Message that will be sent to the <code>output-channel</code>.
|
|
</para>
|
|
|
|
<para>
|
|
Now, lets assume that at some point you do need access to the actual Message. You can of course access the Message Store
|
|
manually and get the contents of the Message, or you can use the same approach as before except now you will be transforming
|
|
the Claim Check to the actual Message by using an <emphasis>Outgoing Claim Check Transformer</emphasis>.
|
|
</para>
|
|
<para>
|
|
Here is an overview of all available parameters of an Incoming Claim
|
|
Check Transformer:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[<int:claim-check-in auto-startup="true" ]]><co id="claimcheck-in-xml01-co" linkends="claimcheck-in-xml01" /><![CDATA[
|
|
id="" ]]><co id="claimcheck-in-xml02-co" linkends="claimcheck-in-xml02" /><![CDATA[
|
|
input-channel="" ]]><co id="claimcheck-in-xml03-co" linkends="claimcheck-in-xml03" /><![CDATA[
|
|
message-store="messageStore" ]]><co id="claimcheck-in-xml04-co" linkends="claimcheck-in-xml04" /><![CDATA[
|
|
order="" ]]><co id="claimcheck-in-xml05-co" linkends="claimcheck-in-xml05" /><![CDATA[
|
|
output-channel="" ]]><co id="claimcheck-in-xml06-co" linkends="claimcheck-in-xml06" /><![CDATA[
|
|
send-timeout=""> ]]><co id="claimcheck-in-xml07-co" linkends="claimcheck-in-xml07" /><![CDATA[
|
|
<int:poller></int:poller> ]]><co id="claimcheck-in-xml08-co" linkends="claimcheck-in-xml08" /><![CDATA[
|
|
</int:claim-check-in>]]></programlisting>
|
|
|
|
<para>
|
|
<calloutlist>
|
|
<callout arearefs="claimcheck-in-xml01-co" id="claimcheck-in-xml01">
|
|
<para>Lifecycle attribute signaling if this component should
|
|
be started during Application Context startup. Defaults
|
|
to true. Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-in-xml02-co" id="claimcheck-in-xml02">
|
|
<para>Id identifying the underlying bean definition (<classname>MessageTransformingHandler</classname>).
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-in-xml03-co" id="claimcheck-in-xml03">
|
|
<para>The receiving Message channel of this endpoint.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-in-xml04-co" id="claimcheck-in-xml04">
|
|
<para>Reference to the MessageStore to be used by this Claim
|
|
Check transformer. If not specified, the default reference
|
|
will be to a bean named <emphasis>messageStore</emphasis>.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-in-xml05-co" id="claimcheck-in-xml05">
|
|
<para>Specifies the order for invocation when this endpoint is
|
|
connected as a subscriber to a channel. This is particularly
|
|
relevant when that channel is using a <emphasis>failover</emphasis>
|
|
dispatching strategy. It has no effect when this endpoint
|
|
itself is a Polling Consumer for a channel with a queue.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-in-xml06-co" id="claimcheck-in-xml06">
|
|
<para>Identifies the Message channel where Message will be sent
|
|
after its being processed by this endpoint.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-in-xml07-co" id="claimcheck-in-xml07">
|
|
<para>Specify the maximum amount of time in milliseconds to wait
|
|
when sending a reply Message to the output channel. By default
|
|
the send will block for one second.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-in-xml08-co" id="claimcheck-in-xml08">
|
|
<para>Defines a poller. Element is not available inside
|
|
a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="claim-check-out">
|
|
<title>Outgoing Claim Check Transformer</title>
|
|
|
|
<para>
|
|
An <emphasis>Outgoing Claim Check Transformer</emphasis> allows you to transform a Message with a Claim Check payload
|
|
into a Message with the original content as its payload.
|
|
</para>
|
|
|
|
<programlisting language="xml"><![CDATA[<int:claim-check-out id="checkout"
|
|
input-channel="checkoutChannel"
|
|
message-store="testMessageStore"
|
|
output-channel="output"/>]]></programlisting>
|
|
|
|
<para>
|
|
In the above configuration, the Message that is received on the <code>input-channel</code> should have a Claim Check as its payload
|
|
and the <emphasis>Outgoing Claim Check Transformer</emphasis> will transform it into a Message with the original payload by simply
|
|
querying the Message store for a Message identified by the provided Claim Check. It then sends the newly checked-out Message to the
|
|
<code>output-channel</code>.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an overview of all available parameters of an Outgoing Claim
|
|
Check Transformer:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[<int:claim-check-out auto-startup="true" ]]><co id="claimcheck-out-xml01-co" linkends="claimcheck-out-xml01" /><![CDATA[
|
|
id="" ]]><co id="claimcheck-out-xml02-co" linkends="claimcheck-out-xml02" /><![CDATA[
|
|
input-channel="" ]]><co id="claimcheck-out-xml03-co" linkends="claimcheck-out-xml03" /><![CDATA[
|
|
message-store="messageStore" ]]><co id="claimcheck-out-xml04-co" linkends="claimcheck-out-xml04" /><![CDATA[
|
|
order="" ]]><co id="claimcheck-out-xml05-co" linkends="claimcheck-out-xml05" /><![CDATA[
|
|
output-channel="" ]]><co id="claimcheck-out-xml06-co" linkends="claimcheck-out-xml06" /><![CDATA[
|
|
remove-message="false" ]]><co id="claimcheck-out-xml07-co" linkends="claimcheck-out-xml07" /><![CDATA[
|
|
send-timeout=""> ]]><co id="claimcheck-out-xml08-co" linkends="claimcheck-out-xml08" /><![CDATA[
|
|
<int:poller></int:poller> ]]><co id="claimcheck-out-xml09-co" linkends="claimcheck-out-xml09" /><![CDATA[
|
|
</int:claim-check-out>]]></programlisting>
|
|
|
|
<para>
|
|
<calloutlist>
|
|
<callout arearefs="claimcheck-out-xml01-co" id="claimcheck-out-xml01">
|
|
<para>Lifecycle attribute signaling if this component should
|
|
be started during Application Context startup. Defaults
|
|
to true. Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml02-co" id="claimcheck-out-xml02">
|
|
<para>Id identifying the underlying bean definition (<classname>MessageTransformingHandler</classname>).
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml03-co" id="claimcheck-out-xml03">
|
|
<para>The receiving Message channel of this endpoint.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml04-co" id="claimcheck-out-xml04">
|
|
<para>Reference to the MessageStore to be used by this Claim
|
|
Check transformer. If not specified, the default reference
|
|
will be to a bean named <emphasis>messageStore</emphasis>.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml05-co" id="claimcheck-out-xml05">
|
|
<para>Specifies the order for invocation when this endpoint is
|
|
connected as a subscriber to a channel. This is particularly
|
|
relevant when that channel is using a <emphasis>failover</emphasis>
|
|
dispatching strategy. It has no effect when this endpoint
|
|
itself is a Polling Consumer for a channel with a queue.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml06-co" id="claimcheck-out-xml06">
|
|
<para>Identifies the Message channel where Message will be sent
|
|
after its being processed by this endpoint.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml07-co" id="claimcheck-out-xml07">
|
|
<para>If set to <code>true</code> the Message will be removed from the
|
|
MessageStore by this transformer. Useful when Message can
|
|
be "claimed" only once. Defaults to <code>false</code>.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml08-co" id="claimcheck-out-xml08">
|
|
<para>Specify the maximum amount of time in milliseconds to wait
|
|
when sending a reply Message to the output channel. By default
|
|
the send will block for one second.
|
|
Attribute is not available inside a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
<callout arearefs="claimcheck-out-xml09-co" id="claimcheck-out-xml09">
|
|
<para>Defines a poller. Element is not available inside
|
|
a <code>Chain</code> element.
|
|
<emphasis>Optional</emphasis>.</para>
|
|
</callout>
|
|
|
|
</calloutlist>
|
|
</para>
|
|
|
|
<para><emphasis>Claim Once</emphasis></para>
|
|
<para>
|
|
There are scenarios when a particular message must be claimed only once. As an analogy, consider the airplane luggage check-in/out process.
|
|
Checking-in your luggage on departure and and then claiming it on arrival is a classic example of such a scenario.
|
|
Once the luggage has been claimed, it can not be claimed again without first checking it back in. To accommodate such cases, we
|
|
introduced a <code>remove-message</code> boolean attribute on the <code>claim-check-out</code> transformer. This attribute is
|
|
set to <code>false</code> by default. However, if set to <code>true</code>, the claimed Message will be removed
|
|
from the MessageStore, so that it can no longer be claimed again.
|
|
</para>
|
|
<para>
|
|
This is also something to consider in terms of storage space, especially
|
|
in the case of the in-memory Map-based <classname>SimpleMessageStore</classname>, where failing to remove the Messages
|
|
could ultimately lead to an <classname>OutOfMemoryException</classname>.
|
|
Therefore, if you don't expect multiple claims to be made, it's recommended
|
|
that you set the <code>remove-message</code> attribute's value to <code>true</code>.
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[<int:claim-check-out id="checkout"
|
|
input-channel="checkoutChannel"
|
|
message-store="testMessageStore"
|
|
output-channel="output"
|
|
remove-message="true"/>]]></programlisting>
|
|
</section>
|
|
<section>
|
|
<title>A word on Message Store</title>
|
|
<para>
|
|
Although we rarely care about the details of the claim checks as long as they work, it is still worth knowing that
|
|
the current implementation of the actual Claim Check (the pointer) in Spring Integration is a UUID to ensure uniqueness.
|
|
</para>
|
|
<para>
|
|
<classname>org.springframework.integration.store.MessageStore</classname> is a strategy interface for storing and retrieving messages.
|
|
Spring Integration provides two convenient implementations of it. <classname>SimpleMessageStore</classname>: an in-memory, Map-based
|
|
implementation (the default, good for testing) and <classname>JdbcMessageStore</classname>: an implementation that uses a relational
|
|
database via JDBC.
|
|
</para>
|
|
</section>
|
|
</section>
|