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

Merge pull request #156 from ghillert/INT-2205

Browse Source 
Fix documentation for Claim Check
This commit is contained in:
Mark Fisher
2011-10-31 10:11:27 -04:00
parent 2bd870200d cf23ab6143
commit ed48382498
1 changed files with 39 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/src/reference/docbook/claim-check.xml
View File

@@ -6,56 +6,56 @@
<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
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
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
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: <emphasis>Incoming Claim Check Transformer</emphasis> and
Spring Integration provides two types of Claim Check transformers: <emphasis>Incoming Claim Check Transformer</emphasis> and
<emphasis>Outgoing Claim Check Transformer</emphasis>. Convenient namespace-based mechanisms are available to configure them.
</para>
<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
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.
<programlisting language="xml"><![CDATA[<int:claim-check-in id="checkin"
input-channel="checkinChannel"
message-store="testMessageStore"
output-channel="output"/>]]></programlisting>
In the above configuration the Message that is received on the <code>input-channel</code> will be persisted to the
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>.
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
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>
</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.
@@ -64,40 +64,44 @@
message-store="testMessageStore"
output-channel="output"/>]]></programlisting>
In the above configuration, the Message that is received on the <code>input-channel</code> should have a Claim Check as its payload
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><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 the departure and and then claiming it on the arrival is a classic example of such a scenario.
Once the luggage was 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 also be removed
from the MessageStore so that it can no longer be claimed again. 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>. 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>false</code>.
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>
</para>
</section>
<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>
<emphasis>A word on Message Store</emphasis>
</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
<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>