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

INT-1264, added docs for Message History

Browse Source
This commit is contained in:
Oleg Zhurakousky
2010-08-31 20:38:34 +00:00
parent 1587ab461d
commit ff8a986abc
2 changed files with 65 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
src/docbkx/index.xml
View File

@@ -72,6 +72,7 @@
<xi:include href="./bridge.xml"/>
<xi:include href="./gateway.xml"/>
<xi:include href="./message-publishing.xml"/>
<xi:include href="./message-history.xml"/>
<xi:include href="./file.xml"/>
<xi:include href="./jdbc.xml"/>
<xi:include href="./jms.xml"/>

64
src/docbkx/message-history.xml Normal file
View File

@@ -0,0 +1,64 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="message-history">
<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.)
</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 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.
</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.
<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. 
</para>
<para>
<programlisting language="xml"><![CDATA[<int:gateway id="sampleGateway" 
service-interface="org.springframework.integration.history.sample.SampleGateway"
default-request-channel="bridgeInChannel"/>
<int:chain id="sampleChain" input-channel="chainChannel" output-channel="filterChannel">
<int:header-enricher>
<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();
assertTrue(historyIterator.hasNext());
Properties gatewayHistory = historyIterator.next();
assertEquals("sampleGateway", gatewayHistory.get("name"));
assertTrue(historyIterator.hasNext());
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.
<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.
</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.
</note>
</section>
</chapter>