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

INT-3417: Polishing Docs for MessageHeaders

Browse Source 
JIRA: https://jira.spring.io/browse/INT-3417

Polishing

Add note about using the accessor.
This commit is contained in:
Artem Bilan
2014-07-03 18:28:50 +03:00
committed by Gary Russell
parent 27b35e2264
commit 23c80906d8
7 changed files with 73 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
src/reference/docbook/aggregator.xml
View File

@@ -32,8 +32,8 @@
<para>Correlation determines how messages are grouped for aggregation.
In Spring Integration correlation is done by default based on the
<code>MessageHeaders.CORRELATION_ID</code> message
header. Messages with the same <code>MessageHeaders.CORRELATION_ID</code> will be grouped
<code>IntegrationMessageHeaderAccessor.CORRELATION_ID</code> message
header. Messages with the same <code>IntegrationMessageHeaderAccessor.CORRELATION_ID</code> will be grouped
together. However, the correlation strategy may be customized to allow
other ways of specifying how the messages should be grouped together by
implementing a <interfacename>CorrelationStrategy</interfacename> (see below).</para>
@@ -42,7 +42,7 @@
<interfacename>ReleaseStrategy</interfacename> is consulted.
The default release strategy for the Aggregator will release a group when all
messages included in a sequence are present, based on the
<code>MessageHeaders.SEQUENCE_SIZE</code> header.
<code>IntegrationMessageHeaderAccessor.SEQUENCE_SIZE</code> header.
This default strategy may be overridden by providing a reference to a
custom <interfacename>ReleaseStrategy</interfacename> implementation.</para>
</section>
@@ -125,13 +125,13 @@
<classname>AbstractCorrelatingMessageHandler</classname>
and it has a default value based on the <code>MessageHeaders.CORRELATION_ID</code> message header:
and it has a default value based on the <code>IntegrationMessageHeaderAccessor.CORRELATION_ID</code> message header:
<programlisting language="java"><![CDATA[public AbstractCorrelatingMessageHandler(MessageGroupProcessor processor, MessageGroupStore store,
CorrelationStrategy correlationStrategy, ReleaseStrategy releaseStrategy) {
...
this.correlationStrategy = correlationStrategy == null ?
new HeaderAttributeCorrelationStrategy(MessageHeaders.CORRELATION_ID) : correlationStrategy;
new HeaderAttributeCorrelationStrategy(IntegrationMessageHeaderAccessor.CORRELATION_ID) : correlationStrategy;
this.releaseStrategy = releaseStrategy == null ? new SequenceSizeReleaseStrategy() : releaseStrategy;
...
}]]></programlisting>
@@ -454,7 +454,7 @@ then you should simply provide an implementation of the <classname>ReleaseStrate
algorithm. The bean can be an implementation of the <interfacename>CorrelationStrategy</interfacename>
interface or a POJO. In the latter case the correlation-strategy-method attribute must be defined
as well. <emphasis>Optional (by default, the aggregator will use
the <code>MessageHeaders.CORRELATION_ID</code> header) </emphasis>.</para>
the <code>IntegrationMessageHeaderAccessor.CORRELATION_ID</code> header) </emphasis>.</para>
</callout>
<callout arearefs="aggxml11">
@@ -488,7 +488,7 @@ then you should simply provide an implementation of the <classname>ReleaseStrate
The bean can be an implementation of the <interfacename>ReleaseStrategy</interfacename> interface
or a POJO. In the latter case the release-strategy-method
attribute must be defined as well. <emphasis>Optional (by default, the
aggregator will use the <code>MessageHeaders.SEQUENCE_SIZE</code> header attribute)</emphasis>.</para>
aggregator will use the <code>IntegrationMessageHeaderAccessor.SEQUENCE_SIZE</code> header attribute)</emphasis>.</para>
</callout>
<callout arearefs="aggxml16">

4
src/reference/docbook/amqp.xml
View File

@@ -640,9 +640,7 @@ public Object handle(@Payload String payload, @Header(AmqpHeaders.CHANNEL) Chann
<para>
The Spring Integration AMPQ Adapters will map standard AMQP properties
automatically. These properties will be copied by default to and from
Spring Integration
<classname><ulink url="http://static.springsource.org/spring-integration/api/org/springframework/integration/MessageHeaders.html">MessageHeaders</ulink></classname>
using the
Spring Integration <classname>MessageHeaders</classname> using the
<classname><ulink url="http://static.springsource.org/spring-integration/api/org/springframework/integration/amqp/support/DefaultAmqpHeaderMapper.html">DefaultAmqpHeaderMapper</ulink></classname>.
</para>
<para>

2
src/reference/docbook/configuration.xml
View File

@@ -162,7 +162,7 @@
Specifically, the Exception will become the payload of a Spring Integration Message. That Message will
then be sent to a Message Channel that is resolved in a way that is similar to the 'replyChannel'
resolution. First, if the request Message being handled at the time the Exception occurred contains
an 'errorChannel' header (the header name is defined in the constant: MessageHeaders.ERROR_CHANNEL),
an 'errorChannel' header (the header name is defined in the constant: IntegrationMessageHeaderAccessor.ERROR_CHANNEL),
the ErrorMessage will be sent to that channel. Otherwise, the error handler will send to a "global"
channel whose bean name is "errorChannel" (this is also defined as a constant:
IntegrationContextUtils.ERROR_CHANNEL_BEAN_NAME).

4
src/reference/docbook/delayer.xml
View File

@@ -65,9 +65,9 @@
In the first case, the expression will evaluate to <code>null</code>; the second will result in
something like:
<programlisting language="java"><![CDATA[ org.springframework.expression.spel.SpelEvaluationException: EL1008E:(pos 8):
Field or property 'delay' cannot be found on object of type 'org.springframework.integration.MessageHeaders']]></programlisting>
Field or property 'delay' cannot be found on object of type 'org.springframework.messaging.MessageHeaders']]></programlisting>
So, if there is a possibility of the header being omitted, and you want to fall back to the default
delay, it is generally more efficient (and recommended) to use the
delay, it is generally more efficient (and recommended) to use the
<emphasis>Indexer</emphasis> syntax instead of <emphasis>dot property accessor</emphasis> syntax, because detecting
the null is faster than catching an exception.
</tip>

2
src/reference/docbook/jmx.xml
View File

@@ -221,7 +221,7 @@
<para>
If the <emphasis>reply-channel</emphasis> attribute is not provided,
the reply message will be sent to the channel that is identified
by the <interfacename>MessageHeaders.REPLY_CHANNEL</interfacename>
by the <interfacename>IntegrationMessageHeaderAccessor.REPLY_CHANNEL</interfacename>
header. That header is typically auto-created by the entry point
into a message flow, such as any <emphasis>Gateway</emphasis> component.
However, if the message flow was started by manually creating a

85
src/reference/docbook/message.xml
View File

@@ -80,10 +80,6 @@
<entry>TIMESTAMP</entry>
<entry>java.lang.Long</entry>
</row>
<row>
<entry>CORRELATION_ID</entry>
<entry>java.lang.Object</entry>
</row>
<row>
<entry>REPLY_CHANNEL</entry>
<entry>java.lang.Object (can be a String or MessageChannel)</entry>
@@ -92,22 +88,6 @@
<entry>ERROR_CHANNEL</entry>
<entry>java.lang.Object (can be a String or MessageChannel)</entry>
</row>
<row>
<entry>SEQUENCE_NUMBER</entry>
<entry>java.lang.Integer</entry>
</row>
<row>
<entry>SEQUENCE_SIZE</entry>
<entry>java.lang.Integer</entry>
</row>
<row>
<entry>EXPIRATION_DATE</entry>
<entry>java.lang.Long</entry>
</row>
<row>
<entry>PRIORITY</entry>
<entry>java.lang.Integer</entry>
</row>
</tbody>
</tgroup>
</table>
@@ -116,6 +96,58 @@
Many inbound and outbound adapter implementations will also provide and/or expect certain headers, and additional
user-defined headers can also be configured.
</para>
<section id="message-header-accessor">
<title>MessageHeaderAccessor API</title>
<para>
Since Spring Framework 4.0 and Spring Integration 4.0, the core Messaging abstraction has been moved to
the <emphasis>spring-messaging</emphasis> module and the new <classname>MessageHeaderAccessor</classname> API
has been introduced to provide additional abstraction over Messaging implementations. All Spring
Integration specific Message Headers constants are now declared in the
<classname>IntegrationMessageHeaderAccessor</classname>:
<table id="integration-message-headers-table">
<title>Pre-defined Message Headers</title>
<tgroup cols="2">
<colspec align="left" />
<thead>
<row>
<entry align="center">Header Name</entry>
<entry align="center">Header Type</entry>
</row>
</thead>
<tbody>
<row>
<entry>CORRELATION_ID</entry>
<entry>java.lang.Object</entry>
</row>
<row>
<entry>SEQUENCE_NUMBER</entry>
<entry>java.lang.Integer</entry>
</row>
<row>
<entry>SEQUENCE_SIZE</entry>
<entry>java.lang.Integer</entry>
</row>
<row>
<entry>EXPIRATION_DATE</entry>
<entry>java.lang.Long</entry>
</row>
<row>
<entry>PRIORITY</entry>
<entry>java.lang.Integer</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Convenient typed getters for these headers are provided on the
<classname>IntegrationMessageHeaderAccessor</classname> class:
<programlisting language="java"><![CDATA[IntegrationMessageHeaderAccessor accessor = new IntegrationMessageHeaderAccessor(message);
int sequenceNumber = accessor.getSequenceNumber();
Object correlationId = accessor.getCorrelationId();
...]]></programlisting>
</para>
</section>
<section id="message-id-generation">
<title>Message ID Generation</title>
<para>
@@ -129,22 +161,23 @@
</para>
<para>
A different UUID generation strategy can be selected by declaring a bean that implements
<interfacename>MessageHeaders.IdGenerator</interfacename> in the application context.
<interfacename>org.springframework.util.IdGenerator</interfacename> in the application context.
</para>
<important>
Only one UUID generation strategy can be used in a classloader. This means that if
two or more application contexts are running in the same classloader, they will share
the same strategy. If one of the contexts changes the strategy, it will be used by
all contexts. If two or more contexts in the same classloader declare a bean of type
<interfacename>MessageHeaders.IdGenerator</interfacename>, they must all be an instance
<interfacename>org.springframework.util.IdGenerator</interfacename>, they must all be an instance
of the same class, otherwise the context attempting to replace a custom strategy will
fail to initialize. If the strategy is the same, but parameterized, the strategy in the
first context to initialize will be used.
</important>
<para>
In addition to the default strategy, two additional <interfacename>IdGenerators</interfacename>
are provided; <classname>MessageHeaders.JdkIdGenerator</classname> uses the previous
<code>UUID.randomUUID()</code> mechanism; <classname>MessageHeaders.SimpleIncrementingIdGenerator</classname>
are provided; <classname>org.springframework.util.JdkIdGenerator</classname> uses the previous
<code>UUID.randomUUID()</code> mechanism;
<classname>org.springframework.integration.support.IdGenerators.SimpleIncrementingIdGenerator</classname>
can be used in cases where a UUID is not really needed and a simple incrementing
value is sufficient.
</para>
@@ -163,7 +196,7 @@ new GenericMessage&lt;T&gt;(T payload, Map&lt;String, Object&gt; headers)</progr
will copy the provided headers to the newly created Message.
</para>
<para>
There is also a convenient implementation of <interfacename>Message</interfacename> designed to communicate
There is also a convenient implementation of <interfacename>Message</interfacename> designed to communicate
error conditions. This implementation takes <classname>Throwable</classname> object as its payload:
<programlisting language="java">ErrorMessage message = new ErrorMessage(someThrowable);
@@ -229,7 +262,7 @@ assertEquals(123, message4.getHeaders().get("foo"));</programlisting>
assertEquals(5, importantMessage.getHeaders().getPriority());
Message&lt;Integer&gt; lessImportantMessage = MessageBuilder.fromMessage(importantMessage)
.setHeaderIfAbsent(MessageHeaders.PRIORITY, 2)
.setHeaderIfAbsent(IntegrationMessageHeaderAccessor.PRIORITY, 2)
.build();
assertEquals(2, lessImportantMessage.getHeaders().getPriority());

4
src/reference/docbook/resequencer.xml
View File

@@ -111,7 +111,7 @@
algorithm. The bean can be an implementation of the <interfacename>CorrelationStrategy</interfacename>
interface or a POJO. In the latter case the correlation-strategy-method attribute must be defined
as well. <emphasis>Optional (by default, the aggregator will use
the <code>MessageHeaders.CORRELATION_ID</code> header) </emphasis>.</para>
the <code>IntegrationMessageHeaderAccessor.CORRELATION_ID</code> header) </emphasis>.</para>
</callout>
<callout arearefs="resxml12-co" id="resxml12">
@@ -133,7 +133,7 @@
The bean can be an implementation of the <interfacename>ReleaseStrategy</interfacename> interface
or a POJO. In the latter case the release-strategy-method
attribute must be defined as well. <emphasis>Optional (by default, the
aggregator will use the <code>MessageHeaders.SEQUENCE_SIZE</code> header attribute)</emphasis>.</para>
aggregator will use the <code>IntegrationMessageHeaderAccessor.SEQUENCE_SIZE</code> header attribute)</emphasis>.</para>
</callout>
<callout arearefs="resxml15-co" id="resxml15">