diff --git a/docs/src/reference/docbook/message-history.xml b/docs/src/reference/docbook/message-history.xml index d6345c578d..29fb6c60cf 100644 --- a/docs/src/reference/docbook/message-history.xml +++ b/docs/src/reference/docbook/message-history.xml @@ -3,29 +3,28 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> Message History - 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.) - 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. +
Message History Configuration - To enable Message History all you need is define message-history element in your configuration. + To enable Message History all you need is to define the message-history element in your configuration. ]]> 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 - List<Properties>. - 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 - List<Properties>. ]]> + The above configuration will produce a very simple Message History structure: + To get access to Message History all you need is access the MessageHistory header. For example: historyIterator = message.getHeaders().get(MessageHistory.HEADER_NAME, MessageHistory.class).iterator(); @@ -51,14 +52,19 @@ Properties chainHistory = historyIterator.next(); assertEquals("sampleChain", chainHistory.get("name"));]]> - Some times you might not want to track all of the components. To accomplish this all you need is provide tracked-components 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 tracked-components attribute and specify + a comma-delimited list of component names and/or patterns that match the components you want to track. ]]> - 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. - 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.