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

INT-1552 doc polishing

Browse Source
This commit is contained in:
Mark Fisher
2010-11-22 14:14:46 -05:00
parent 5873ee98eb
commit 0ac31584fc
1 changed files with 23 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/src/reference/docbook/message-history.xml
View File

@@ -3,29 +3,28 @@
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Message History</title>
<para>
The key benefit of messaging architecture is loose coupling where participating components do not maintain any awareness about one another. This fact
alone makes you architecture extremely flexible  allowing you to change components without affecting the rest of the flow, change messaging routs,  
message consuming styles (polling vs event driven) etc...
However, this unassuming style of architecture could prove to be problematic when things go wrong. For example, if something happened
you would probably like to get as much information about the message as you can (its origin, where it was etc.)
The key benefit of a messaging architecture is loose coupling where participating components do not maintain any awareness about one another. This fact
alone makes your application extremely flexible, allowing you to change components without affecting the rest of the flow, change messaging routes,  
message consuming styles (polling vs event driven), and so on.
However, this unassuming style of architecture could prove to be difficult when things go wrong. When debugging,
you would probably like to get as much information about the message as you can (its origin, channels it has traversed, etc.)
</para>
<para>
Message History is one of those patterns that could help by giving you an option to maintain some level of awareness of a
Message History is one of those patterns that helps by giving you an option to maintain some level of awareness of a
message path either for debugging purposes or to maintain an audit trail.
Spring integration provides a simple way to configure your message flows to maintain Message History by adding Message History header to a
Message every time a message goes through a tracked component.
Spring integration provides a simple way to configure your message flows to maintain the Message History by adding a header to the
Message and updating that header every time a message passes through a tracked component.
</para>
<section id="message-history-config">
<title>Message History Configuration</title>
<para>
To enable Message History all you need is define <code>message-history</code> element in your configuration.
To enable Message History all you need is to define the <code>message-history</code> element in your configuration.
<programlisting language="xml"><![CDATA[<int:message-history/>]]></programlisting>
</para>
<para>
Now every named component (component that has an 'id' defined) will be tracked.
The framework will set the '$history' header in your Message who's value is  very simple - <classname>List&lt;Properties&gt;</classname>.
The need for this simple structure is mandated by the loosely coupled architecture of messaging systems where the framework
must not require you to share any dependencies outside of Java itself. 
The framework will set the 'history' header in your Message. Its value is very simple - <classname>List&lt;Properties&gt;</classname>.
</para>
<para>
<programlisting language="xml"><![CDATA[<int:gateway id="sampleGateway" 
@@ -37,9 +36,11 @@
<int:header name="baz" value="baz"/>
</int:header-enricher>
</int:chain>]]></programlisting>
The above configuration will produce a very simple Message History structure:
<programlisting language="java"><![CDATA[[{name=sampleGateway, type=gateway, timestamp=1283281668091},
{name=sampleChain, type=chain, timestamp=1283281668094}]]]></programlisting>
To get access to Message History all you need is access the MessageHistory header. For example:
<programlisting language="java"><![CDATA[Iterator<Properties> historyIterator =
message.getHeaders().get(MessageHistory.HEADER_NAME, MessageHistory.class).iterator();
@@ -51,14 +52,19 @@ Properties chainHistory = historyIterator.next();
assertEquals("sampleChain", chainHistory.get("name"));]]></programlisting>
</para>
<para>
Some times you might not want to track all of the components. To accomplish this all you need is provide <code>tracked-components</code> attribute where you can specify
comma delimited list of component names and/or patterns you want to track.
You might not want to track all of the components. To limit the history to certain components based on their names,
all you need is provide the <code>tracked-components</code> attribute and specify
a comma-delimited list of component names and/or patterns that match the components you want to track.
<programlisting language="xml"><![CDATA[<int:message-history tracked-components="*Gateway, sample*, foo"/>]]></programlisting>
In the above example, Message History will only be maintained for all of the components that end with 'Gateway', all components that start with 'sample' and 'foo' component.
In the above example, Message History will only be maintained for all of the components that end with 'Gateway', start with 'sample',
or match the name 'foo' exactly.
</para>
<note>
Remember, that by definition History is immutable (you can't re-write history,although some try), therefore Message History can not
be changed once written. Every attempt will end in exception.
Remember that by definition the Message History header is immutable (you can't re-write history, although some try). Therefore, when writing
Message History values, the components are either creating brand new Messages (when the component is an origin), or they are copying the
history from a request Message, modifying it and setting the new list on a reply Message. In either case, the values can be appended even
if the Message itself is crossing thread boundaries. That means that the history values can greatly simplify debugging in an
asynchronous message flow.
</note>
</section>
</section>