spring-integration/src/reference/docbook/message-history.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="message-history"
    xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Message History</title>
  <para>
    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 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 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 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. Its value is very simple - <classname>List&lt;Properties&gt;</classname>.
    </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>
    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', start with 'sample',
    or match the name 'foo' exactly.
    </para>
    <para>
    Starting with <emphasis>version 4.0</emphasis>, you can also use the <code>@EnableMessageHistory</code> annotation
    in a <code>@Configuration</code> class. In addition, the <classname>MessageHistoryConfigurer</classname> bean
    is now exposed as a JMX MBean by the <classname>IntegrationMBeanExporter</classname>
    (see <xref linkend="jmx-mbean-exporter"/>), allowing the patterns to be changed at runtime.
    Note, however, that the bean must be stopped (turning off message history) in order to change the patterns.
    This feature might be useful to temporarily turn on history to analyze a system.
    The MBean's object name is <code>"&lt;domain&gt;:name=messageHistoryConfigurer,type=MessageHistoryConfigurer"</code>.
    </para>
    <important>
    If multiple beans (declared by <code>@EnableMessageHistory</code> and/or <code>&lt;message-history/&gt;</code>) they
    all must have identical component name patterns (when trimmed and sorted). <emphasis role="bold">Do not use a generic
	<code>&lt;bean/&gt;</code> definition for the <classname>MessageHistoryConfigurer</classname></emphasis>.
    </important>
    <note>
    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>