INT-4224: Improve Direct Handler Binding Docs

JIRA: https://jira.spring.io/browse/INT-4224

Explain when `ref` can can be used on certain endpoints.

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

@@ -141,7 +141,7 @@ public abstract class AbstractStandardMessageHandlerFactoryBean
 
 	private void checkReuse(AbstractMessageProducingHandler replyHandler) {
 		Assert.isTrue(!referencedReplyProducers.contains(replyHandler),
-				"An AbstractReplyProducingMessageHandler may only be referenced once (" +
+				"An AbstractMessageProducingMessageHandler may only be referenced once (" +
 				replyHandler.getComponentName() + ") - use scope=\"prototype\"");
 		referencedReplyProducers.add(replyHandler);
 	}

src/reference/asciidoc/filter.adoc

@@ -74,6 +74,8 @@ If you want rejected messages to be routed to a specific channel, provide that r
     output-channel="output" discard-channel="rejectedMessages"/>
 ----
 
+Also see <<advising-filters>>.
+
 NOTE: Message Filters are commonly used in conjunction with a Publish Subscribe Channel.
 Many filter endpoints may be subscribed to the same channel, and they decide whether or not to pass the Message to the next endpoint which could be any of the supported types (e.g.
 Service Activator).
@@ -90,6 +92,11 @@ However if the custom filter implementation is scoped to a single `<filter>` ele
 
 NOTE: Using both the `ref` attribute and an inner handler definition in the same `<filter>` configuration is not allowed, as it creates an ambiguous condition, and an Exception will be thrown.
 
+IMPORTANT: If the "ref" attribute references a bean that extends `MessageFilter` (such as filters provided by the framework itself), the configuration is optimized by injecting the output channel into the filter bean directly.
+In this case, each "ref" must be to a separate bean instance (or a `prototype`-scoped bean), or use the inner `<bean/>` configuration type.
+However, this optimization only applies if you don't provide any filter-specific attributes in the filter XML definition.
+If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.
+
 With the introduction of SpEL support, Spring Integration added the `expression` attribute to the filter element.
 It can be used to avoid Java entirely for simple filters.
 [source,xml]

src/reference/asciidoc/router.adoc

@@ -806,6 +806,12 @@ However if the custom router implementation should be scoped to a single definit
 
 NOTE: Using both the `ref` attribute and an inner handler definition in the same `<router>` configuration is not allowed, as it creates an ambiguous condition, and an Exception will be thrown.
 
+IMPORTANT: If the "ref" attribute references a bean that extends `AbstractMessageProducingHandler` (such as routers provided by the framework itself), the configuration is optimized referencing the router directly.
+In this case, each "ref" must be to a separate bean instance (or a `prototype`-scoped bean), or use the inner `<bean/>` configuration type.
+However, this optimization only applies if you don't provide any router-specific attributes in the router XML definition.
+If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.
+
+
 _Routers and the Spring Expression Language (SpEL)_
 
 Sometimes the routing logic may be simple and writing a separate class for it and configuring it as a bean may seem like overkill.

src/reference/asciidoc/service-activator.adoc

@@ -80,7 +80,7 @@ public class MyBean {
 }
 ----
 
-Using a "ref" attribute is generally recommended if the custom Service Activator handler implementation can be reused in other `<service-activator>` definitions.
+Using a `ref` attribute is generally recommended if the custom Service Activator handler implementation can be reused in other `<service-activator>` definitions.
 However if the custom Service Activator handler implementation is only used within a single definition of the `<service-activator>`, you can provide an inner bean definition:
 [source,xml]
 ----
@@ -92,6 +92,10 @@ However if the custom Service Activator handler implementation is only used with
 
 NOTE: Using both the "ref" attribute and an inner handler definition in the same `<service-activator>` configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
 
+IMPORTANT: If the "ref" attribute references a bean that extends `AbstractMessageProducingHandler` (such as handlers provided by the framework itself), the configuration is optimized by injecting the output channel into the handler directly.
+In this case, each "ref" must be to a separate bean instance (or a `prototype`-scoped bean), or use the inner `<bean/>` configuration type.
+If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.
+
 _Service Activators and the Spring Expression Language (SpEL)_
 
 Since Spring Integration 2.0, Service Activators can also benefit from SpEL (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html).

src/reference/asciidoc/splitter.adoc

@@ -112,6 +112,11 @@ However if the custom splitter handler implementation should be scoped to a sing
 
 NOTE: Using both a `ref` attribute and an inner handler definition in the same `<int:splitter>` configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
 
+IMPORTANT: If the "ref" attribute references a bean that extends `AbstractMessageProducingHandler` (such as splitters provided by the framework itself), the configuration is optimized by injecting the output channel into the handler directly.
+In this case, each "ref" must be to a separate bean instance (or a `prototype`-scoped bean), or use the inner `<bean/>` configuration type.
+However, this optimization only applies if you don't provide any splitter-specific attributes in the splitter XML definition.
+If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.
+
 ===== Configuring a Splitter with Annotations
 
 The `@Splitter` annotation is applicable to methods that expect either the`Message` type or the message payload type, and the return values of the method should be a `Collection` of any type.

src/reference/asciidoc/transformer.adoc

@@ -33,7 +33,7 @@ The "ref" may either point to an Object that contains the @Transformer annotatio
 <beans:bean id="testTransformerBean" class="org.foo.TestTransformer" />
 ----
 
-Using a "ref" attribute is generally recommended if the custom transformer handler implementation can be reused in other `<transformer>` definitions.
+Using a `ref` attribute is generally recommended if the custom transformer handler implementation can be reused in other `<transformer>` definitions.
 However if the custom transformer handler implementation should be scoped to a single definition of the `<transformer>`, you can define an inner bean definition:
 [source,xml]
 ----
@@ -45,7 +45,11 @@ However if the custom transformer handler implementation should be scoped to a s
 
 NOTE: Using both the "ref" attribute and an inner handler definition in the same `<transformer>` configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
 
-The method that is used for transformation may expect either the `Message` type or the payload type of inbound Messages.
+IMPORTANT: If the "ref" attribute references a bean that extends `AbstractMessageProducingHandler` (such as transformers provided by the framework itself), the configuration is optimized by injecting the output channel into the handler directly.
+In this case, each "ref" must be to a separate bean instance (or a `prototype`-scoped bean), or use the inner `<bean/>` configuration type.
+If you inadvertently reference the same message handler from multiple beans, you will get a configuration exception.
+
+When using a POJO, the method that is used for transformation may expect either the `Message` type or the payload type of inbound Messages.
 It may also accept Message header values either individually or as a full map by using the `@Header` and `@Headers` parameter annotations respectively.
 The return value of the method can be any type.
 If the return value is itself a `Message`, that will be passed along to the transformer's output channel.