Doc Polishing.

Author: garyrussell

spring-integration-core/src/main/java/org/springframework/integration/annotation/IdempotentReceiver.java

@@ -23,10 +23,11 @@
 import java.lang.annotation.Target;
 
 /**
- * Indicate a method with the MessagingAnnotation (@code @ServiceActivator, @Router etc.)
- * to apply for the underlying {@link org.springframework.messaging.MessageHandler#handleMessage}
- * the {@link org.springframework.integration.handler.advice.IdempotentReceiverInterceptor} using
- * its id from the {@link #value()}.
+ * A {@code @Bean} that has a MessagingAnnotation (@code @ServiceActivator, @Router etc.)
+ * that also has this annotation, has an
+ * {@link org.springframework.integration.handler.advice.IdempotentReceiverInterceptor} applied
+ * to the associated {@link org.springframework.messaging.MessageHandler#handleMessage} method.
+ * The interceptor bean names are provided in the {@link #value()}.
  *
  * @author Artem Bilan
  * @since 4.1

spring-integration-core/src/main/java/org/springframework/integration/config/IdempotentReceiverAutoProxyCreator.java

@@ -33,8 +33,8 @@
 import org.springframework.util.PatternMatchUtils;
 
 /**
- * The {@link AbstractAutoProxyCreator} implementation to apply {@code IdempotentReceiverInterceptor}s
- * to the {@link MessageHandler}s mapped by their {@code endpoint beanName}.
+ * The {@link AbstractAutoProxyCreator} implementation that applies {@code IdempotentReceiverInterceptor}s
+ * to {@link MessageHandler}s mapped by their {@code endpoint beanName}.
  *
  * @author Artem Bilan
  * @since 4.1

spring-integration-core/src/main/java/org/springframework/integration/config/IdempotentReceiverAutoProxyCreatorInitializer.java

@@ -34,10 +34,11 @@
 import org.springframework.util.StringUtils;
 
 /**
- * The {@link IntegrationConfigurationInitializer} to populate {@link IdempotentReceiverAutoProxyCreator}
- * to the provided {@link ConfigurableListableBeanFactory} according to the existing
- * {@code IdempotentReceiverInterceptor} {@link BeanDefinition}s and their {@code mapping}
- * to the Consumer Endpoints.
+ * The {@link IntegrationConfigurationInitializer} that populates
+ * the {@link ConfigurableListableBeanFactory}
+ * with an {@link IdempotentReceiverAutoProxyCreator}
+ * when {@code IdempotentReceiverInterceptor} {@link BeanDefinition}s and their {@code mapping}
+ * to Consumer Endpoints are present.
  *
  * @author Artem Bilan
  * @since 4.1
@@ -77,10 +78,10 @@ else if (beanDefinition instanceof AnnotatedBeanDefinition) {
 						Object value = beanMethod.getAnnotationAttributes(annotationType).get("value");
 						if (value != null) {
 							String[] interceptors = (String[]) value;
-							/* MessageHandler beans, populated from the @Bean methods, have the complex id,
-							   including @Configuration bean name, method name and Messaging annotation name.
-							   Therefore we should provide here some pattern  closer to the real MessageHandler
-							   bean name.
+							/*
+							   MessageHandler beans, populated from @Bean methods, have a complex id,
+							   including @Configuration bean name, method name and the Messaging annotation name.
+							   The following pattern matches the bean name, regardless of the annotation name.
 							*/
 							String endpoint = beanDefinition.getFactoryBeanName() + "." + beanName + ".*";
 							for (String interceptor : interceptors) {

spring-integration-core/src/main/java/org/springframework/integration/handler/advice/IdempotentReceiverInterceptor.java

@@ -41,18 +41,18 @@
 /**
  * The {@link MethodInterceptor} implementation for the
  * <a href="http://www.eaipatterns.com/IdempotentReceiver.html">Idempotent Receiver</a>
- * EIP pattern.
+ * E.I. Pattern.
  * <p>
- * This {@link MethodInterceptor} works like {@code MessageFilter} if {@link #discardChannel}
+ * This {@link MethodInterceptor} works like a {@code MessageFilter} if {@link #discardChannel}
  * is provided or {@link #throwExceptionOnRejection} is set to {@code true}.
  * However if those properties aren't provided, this interceptor will create an new {@link Message}
- * with {@link IntegrationMessageHeaderAccessor#DUPLICATE_MESSAGE} header in case of the
+ * with a {@link IntegrationMessageHeaderAccessor#DUPLICATE_MESSAGE} header when the
  * {@code requestMessage} isn't accepted by {@link MessageSelector}.
  * <p>
  * The {@code idempotent filtering} logic depends on the provided {@link MessageSelector}.
   * <p>
- * This class is designed to be used just only for the {@link MessageHandler#handleMessage},
- * as well as the entire {@code Idempotent Receiver} pattern.
+ * This class is designed to be used only for the {@link MessageHandler#handleMessage},
+ * method.
  *
  * @author Artem Bilan
  * @since 4.1
@@ -79,7 +79,7 @@ public IdempotentReceiverInterceptor(MessageSelector messageSelector) {
 	}
 
 	/**
-	 * Specify the timeout value for sending to the intercepting target.
+	 * Specify the timeout value for sending to the discard channel.
 	 * @param timeout the timeout in milliseconds
 	 */
 	public void setTimeout(long timeout) {
@@ -90,12 +90,13 @@ public void setTimeout(long timeout) {
 	 * Specify whether this interceptor should throw a
 	 * {@link MessageRejectedException} when its selector does not accept a
 	 * Message. The default value is <code>false</code> meaning that rejected
-	 * Messages will be enriched with {@link IntegrationMessageHeaderAccessor#DUPLICATE_MESSAGE}
+	 * Messages will be discarded or
+	 * enriched with {@link IntegrationMessageHeaderAccessor#DUPLICATE_MESSAGE}
 	 * header and returned as normal to the {@code invocation.proceed()}.
-	 * Typically this value would not be <code>true</code> when
-	 * a discard channel is provided, but if so, it will still apply
-	 * (in such a case, the Message will be sent to the discard channel,
-	 * and <em>then</em> the exception will be thrown).
+	 * Typically this value would <em>not</em> be <code>true</code> when
+	 * a discard channel is provided, but if it is, it will cause the
+	 * exception to be thrown <em>after</em>
+	 * the Message is sent to the discard channel,
 	 * @param throwExceptionOnRejection true if an exception should be thrown.
 	 * @see #setDiscardChannel(MessageChannel)
 	 */
@@ -105,7 +106,7 @@ public void setThrowExceptionOnRejection(boolean throwExceptionOnRejection) {
 
 	/**
 	 * Specify a channel where rejected Messages should be sent. If the discard
-	 * channel is null (the default), rejected Messages will be enriched with
+	 * channel is null (the default), duplicate Messages will be enriched with
 	 * {@link IntegrationMessageHeaderAccessor#DUPLICATE_MESSAGE} header
 	 * and returned as normal to the {@code invocation.proceed()}. However,
 	 * the 'throwExceptionOnRejection' flag determines whether rejected Messages

spring-integration-core/src/main/java/org/springframework/integration/metadata/ExpressionMetadataKeyStrategy.java

@@ -27,7 +27,7 @@
 
 /**
  * The expression based {@link MetadataKeyStrategy} implementation.
- * The provided {@link Message} is used as a evaluation context root object.
+ * The provided {@link Message} is used as the evaluation context root object.
  *
  * @author Artem Bilan
  * @since 4.1

spring-integration-core/src/main/java/org/springframework/integration/selector/MetadataStoreSelector.java

@@ -17,29 +17,31 @@
 package org.springframework.integration.selector;
 
 import org.springframework.integration.core.MessageSelector;
+import org.springframework.integration.filter.MessageFilter;
+import org.springframework.integration.handler.advice.IdempotentReceiverInterceptor;
 import org.springframework.integration.metadata.ConcurrentMetadataStore;
 import org.springframework.integration.metadata.MetadataKeyStrategy;
 import org.springframework.integration.metadata.SimpleMetadataStore;
 import org.springframework.messaging.Message;
 import org.springframework.util.Assert;
 
 /**
- * The {@link MessageSelector} implementation around the {@link ConcurrentMetadataStore}
+ * The {@link MessageSelector} implementation using a {@link ConcurrentMetadataStore}
  * and {@link MetadataKeyStrategy}.
  * <p>
  * The {@link #accept} method extracts {@code metadataKey} from the provided {@code message}
- * using {@link MetadataKeyStrategy} and use {@code id} header as a {@code value}.
+ * using {@link MetadataKeyStrategy} and uses the {@code id} header as the {@code value}.
  * <p>
  * The successful result of the {@link #accept} method is based on the
- * {@link ConcurrentMetadataStore#putIfAbsent} return value. The {@code true} is returned
- * from this {@link MessageSelector} if {@code putIfAbsent} has returned {@code null}.
- * And at the same time it means that the value is placed to the {@code MetadataStore}.
+ * {@link ConcurrentMetadataStore#putIfAbsent} return value. {@code true} is returned
+ * {@link MessageSelector} if {@code putIfAbsent} returns {@code null}.
+ * And, at the same time it means that the value has been placed to the {@code MetadataStore}.
  * Otherwise the messages isn't accepted because there is already a value in the
  * {@code MetadataStore} associated with the {@code key}.
  * <p>
- * This {@link MessageSelector} is useful for the custom
+ * This {@link MessageSelector} is useful for an
  * <a href="http://www.eaipatterns.com/IdempotentReceiver.html">Idempotent Receiver</a>
- * implementation.
+ * implementation. It can be used in a {@link MessageFilter} or {@link IdempotentReceiverInterceptor}.
  *
  * @author Artem Bilan
  * @since 4.1

spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-4.1.xsd

@@ -4315,7 +4315,8 @@ The list of component name patterns you want to track (e.g.,  tracked-components
 					<xsd:documentation>
 						Consumer Endpoint name(s) or patterns. To specify more than one name(pattern) use ',' 
 						(e.g. endpoint="xxx, xxx*, *xxx, *xxx*, xxx*yyy").
-						The endpoint 'id' is used to retrieve the target 'MessageHandler' bean via '.handler' suffix,
+						The endpoint 'id' is used to retrieve the target endpoint's
+						'MessageHandler' bean (using its '.handler' suffix),
 						for which the 'IdempotentReceiverInterceptor' will be applied.
 					</xsd:documentation>
 				</xsd:annotation>
@@ -4328,7 +4329,7 @@ The list of component name patterns you want to track (e.g.,  tracked-components
 						</tool:annotation>
 					</xsd:appinfo>
 					<xsd:documentation>
-						The 'MessageSelector' reference. Used to identify if the message should be accepted
+						A 'MessageSelector' reference. Used to identify if the message should be accepted
 						by the target 'MessageHandler' endpoint.
 						Mutually exclusive with 'metadata-store' and 'key-strategy' or 'key-expression'.
 					</xsd:documentation>
@@ -4342,7 +4343,7 @@ The list of component name patterns you want to track (e.g.,  tracked-components
 						</tool:annotation>
 					</xsd:appinfo>
 					<xsd:documentation>
-						The 'MetadataStore' reference. Used for underlying
+						The 'MetadataStore' reference. Used for an underlying
 						'org.springframework.integration.selector.MetadataStoreSelector'.
 						Mutually exclusive with 'selector'.
 						Optional. By default 'MetadataStoreSelector' uses an internal 'SimpleMetadataStore'.
@@ -4357,9 +4358,9 @@ The list of component name patterns you want to track (e.g.,  tracked-components
 						</tool:annotation>
 					</xsd:appinfo>
 					<xsd:documentation>
-						The 'MetadataKeyStrategy' reference. Used for underlying
+						The 'MetadataKeyStrategy' reference. Used by the underlying
 						'org.springframework.integration.selector.MetadataStoreSelector'.
-						Evaluates an 'idempotentKey' against request Message.
+						Evaluates an 'idempotentKey' from the request Message.
 						Mutually exclusive with 'selector' and 'key-expression'.
 					</xsd:documentation>
 				</xsd:annotation>
@@ -4368,8 +4369,8 @@ The list of component name patterns you want to track (e.g.,  tracked-components
 				<xsd:annotation>
 					<xsd:documentation><![CDATA[
 					Expression to populate an 'org.springframework.integration.metadata.ExpressionMetadataKeyStrategy'.
-					Used for underlying 'org.springframework.integration.selector.MetadataStoreSelector'.
-					Evaluates an 'idempotentKey' against request Message as evaluation context root object.
+					Used by the underlying 'org.springframework.integration.selector.MetadataStoreSelector'.
+					Evaluates an 'idempotentKey' using the request Message as the evaluation context root object.
 					Mutually exclusive with 'selector' and 'key-strategy'.
 				]]></xsd:documentation>
 				</xsd:annotation>
@@ -4383,14 +4384,16 @@ The list of component name patterns you want to track (e.g.,  tracked-components
 					</xsd:appinfo>
 					<xsd:documentation>
 						Identifies the channel to send a message when 'IdempotentReceiverInterceptor' doesn't accept
-						the message.
+						the message. When omitted, duplicate messages are forwarded to the handler with a
+						'DUPLICATE_MESSAGE' header.
 					</xsd:documentation>
 				</xsd:annotation>
 			</xsd:attribute>
 			<xsd:attribute name="throw-exception-on-rejection" type="xsd:string">
 				<xsd:annotation>
 					<xsd:documentation>
 						Throw an exception if the 'IdempotentReceiverInterceptor' rejects the message (default false).
+						It is applied regardless of whether or not a discard channel is provided.
 					</xsd:documentation>
 				</xsd:annotation>
 			</xsd:attribute>

src/reference/docbook/whats-new.xml

@@ -44,10 +44,11 @@
 		<section id="4.1-idempotent-receiver">
 			<title>Idempotent Receiver Pattern</title>
 			<para>
-				The <emphasis>Idempotent Receiver</emphasis> EIP pattern implementation is now provided.
-				It is presented as <code>&lt;idempotent-receiver&gt;</code> component and
+				The <emphasis>Idempotent Receiver</emphasis> EIP implementation is now provided
+				via the <code>&lt;idempotent-receiver&gt;</code> component in XML, or the
 				<classname>IdempotentReceiverInterceptor</classname> and
-				<interfacename>IdempotentReceiver</interfacename> annotation pair.
+				<interfacename>IdempotentReceiver</interfacename> annotation when using Java
+				Configuration.
 				See <xref linkend="idempotent-receiver"/> and their JavaDocs for more information.
 			</para>
 		</section>