From 67f8ea1336629fe66b7d3288cef786a2071a7cd3 Mon Sep 17 00:00:00 2001
From: Artem Bilan <abilan@gopivotal.com>
Date: Mon, 28 Apr 2014 21:46:48 +0300
Subject: [PATCH] INT-3375: Docs for Messaging Annotations

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

INT-3375 Doc Polishing
---
 src/reference/docbook/configuration.xml | 143 ++++++++++++++++++++++--
 src/reference/docbook/whats-new.xml     |  29 +++++
 2 files changed, 164 insertions(+), 8 deletions(-)

diff --git a/src/reference/docbook/configuration.xml b/src/reference/docbook/configuration.xml
index 081641b2f7..9cc9a234c1 100644
--- a/src/reference/docbook/configuration.xml
+++ b/src/reference/docbook/configuration.xml
@@ -231,6 +231,8 @@ public class FooService {
 		<listitem>@Splitter</listitem>
 		<listitem>@Transformer</listitem>
 		<listitem>@InboundChannelAdapter</listitem>
+		<listitem>@BridgeFrom</listitem>
+		<listitem>@BridgeTo</listitem>
       </itemizedlist>
     </para>
     <para>The behavior of each is described in its own chapter or section within
@@ -310,11 +312,6 @@ public class FooService {
     }
 
 }</programlisting>
-      That provides a pure annotation-driven alternative to the XML configuration. However, it is generally recommended
-      to use XML for the endpoints, since it is easier to keep track of the overall configuration in a single, external
-      location (and besides the namespace-based XML configuration is not very verbose). If you do prefer to provide
-      channels with the annotations however, you just need to enable a SI Annotations BeanPostProcessor. The following element should
-      be added: <programlisting language="xml"><![CDATA[<int:annotation-config/>]]></programlisting>
     </para>
 	 <para>
 		  The processing of these annotations creates the same beans (<classname>AbstractEndpoint</classname>s and
@@ -432,9 +429,139 @@ public String foo() {
 		The first example requires that the default poller has been declared elsewhere in the application
 		context.
 	</para>
-    <para>
-        Also see <xref linkend="advising-with-annotations"/>.
-    </para>
+	<section id="meta-annotations">
+	  <title>Messaging Meta-Annotations</title>
+	  <para>
+		  Starting with <emphasis>version 4.0</emphasis>, all Messaging Annotations can be configured as
+		  meta-annotations and all user-defined Messaging Annotations can define the same attributes
+		  to override their default values. In addition, meta-annotations can be configured hierarchically:
+		  <programlisting language="java"><![CDATA[@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@ServiceActivator(inputChannel = "annInput", outputChannel = "annOutput")
+public @interface MyServiceActivator {
+
+	String[] adviceChain = { "annAdvice" };
+}
+
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@MyServiceActivator
+public @interface MyServiceActivator1 {
+
+	String inputChannel();
+
+	String outputChannel();
+}
+...
+
+@MyServiceActivator1(inputChannel = "inputChannel", outputChannel = "outputChannel")
+public Object service(Object payload) {
+   ...
+}]]></programlisting>
+		  This allows users to set defaults for various attributes and enables isolation of
+		  framework Java dependencies to user annotations, avoiding their use in user classes.
+		  If the framework finds a method with a user annotation that has a framework meta-annotation,
+		  it is treated as if the method was annotated directly with the framework annotation.
+	  </para>
+	</section>
+	<section>
+	  <title>Annotations on @Beans</title>
+	  <para>
+		  Starting with <emphasis>version 4.0</emphasis>, Messaging Annotations can be configured on
+		  <classname>@Bean</classname> method definitions in <interfacename>@Configuration</interfacename> classes,
+		  to produce Message Endpoints based on the beans, not methods. It is useful when <code>@Bean</code>
+		  definitions are "out of the box"
+		  <interfacename>MessageHandler</interfacename>s (<classname>AggregatingMessageHandler</classname>,
+		  <classname>DefaultMessageSplitter</classname> etc.), <interfacename>Transformer</interfacename>s
+		  (<classname>JsonToObjectTransformer</classname>, <classname>ClaimCheckOutTransformer</classname> etc.),
+		  <interfacename>MessageSource</interfacename>s (<classname>FileReadingMessageSource</classname>,
+		  <classname>RedisStoreMessageSource</classname> etc.):
+		  <programlisting language="java"><![CDATA[@Configuration
+@EnableIntegration
+public class MyFlowConfiguration {
+
+	@Bean
+	@InboundChannelAdapter(value = "inputChannel", poller = @Poller(fixedDelay = "1000"))
+	public MessageSource<String> consoleSource() {
+		return CharacterStreamReadingMessageSource.stdin();
+	}
+
+	@Bean
+	@Transformer(inputChannel = "inputChannel", outputChannel = "httpChannel")
+	public ObjectToMapTransformer toMapTransformer() {
+		return new ObjectToMapTransformer();
+	}
+
+	@Bean
+	@ServiceActivator(inputChannel = "httpChannel")
+	public MessageHandler httpHandler() {
+		HttpRequestExecutingMessageHandler handler = new HttpRequestExecutingMessageHandler("http://foo/service");
+		handler.setExpectedResponseType(String.class);
+		handler.setOutputChannelName("outputChannel");
+		return handler;
+	}
+
+	@Bean
+	@ServiceActivator(inputChannel = "outputChannel")
+	public LoggingHandler loggingHandler() {
+		return new LoggingHandler("info");
+	}
+
+}]]></programlisting>
+	  The meta-annotation rules work on <classname>@Bean</classname> methods as well
+	  (<code>@MyServiceActivator</code> above can be applied to a <code>@Bean</code> definition).
+	    <note>
+			When using these annotations on consumer <code>@Bean</code> definitions, if the bean definition
+			returns an appropriate <interfacename>MessageHandler</interfacename> (depending on the
+			annotation type), attributes such as <code>outputChannel, requiresReply</code> etc, must
+			be set on the <code>@Bean</code> itself. The only annotation
+			attributes used are <code>adviceChain, autoStartup, inputChannel, phase, poller</code>, all
+			other attributes are for the handler.
+	    </note>
+	    <important>
+			When using these annotations on <code>@Bean</code> definitions, the <code>inputChannel</code>
+			must reference a declared bean; channels are not automatically declared in this case.
+	    </important>
+	  </para>
+	</section>
+	<section>
+	  <title>Creating a Bridge with Annotations</title>
+	  <para>
+		  Starting with <emphasis>version 4.0</emphasis>, the Messaging Annotation and Java configuration provides
+		  <classname>@BridgeFrom</classname> and <classname>@BridgeTo</classname> <classname>@Bean</classname> method
+		  annotations to mark <interfacename>MessageChannel</interfacename> beans in
+		  <interfacename>@Configuration</interfacename> classes. This is just for completeness, providing
+		  a convenient mechanism to declare a
+		  <classname>BridgeHandler</classname> and its Message Endpoint configuration:
+		  <programlisting language="java"><![CDATA[@Bean
+public PollableChannel bridgeFromInput() {
+	return new QueueChannel();
+}
+
+@Bean
+@BridgeFrom(value = "bridgeFromInput", poller = @Poller(fixedDelay = "1000"))
+public MessageChannel bridgeFromOutput() {
+	return new DirectChannel();
+}
+@Bean
+public QueueChannel bridgeToOutput() {
+	return new QueueChannel();
+}
+
+@Bean
+@BridgeTo("bridgeToOutput")
+public MessageChannel bridgeToInput() {
+	return new DirectChannel();
+}]]></programlisting>
+	These annotations can be used as meta-annotations as well.
+	  </para>
+	</section>
+	<section>
+	  <title>Advising Annotated Endpoints</title>
+      <para>
+        See <xref linkend="advising-with-annotations"/>.
+      </para>
+    </section>
   </section>
 
   <section id="message-mapping-rules">
diff --git a/src/reference/docbook/whats-new.xml b/src/reference/docbook/whats-new.xml
index 349ace4e79..521c2f1249 100644
--- a/src/reference/docbook/whats-new.xml
+++ b/src/reference/docbook/whats-new.xml
@@ -193,6 +193,26 @@
 				<xref linkend="sftp-inbound"/>.
 			</para>
 		</section>
+		<section id="4.0-bridge-annotations">
+			<title>@BridgeFrom and @BridgeTo Annotations</title>
+			<para>
+				Annotation and Java configuration has introduced <classname>@BridgeFrom</classname> and
+				<classname>@BridgeTo</classname> <classname>@Bean</classname> method annotations to mark
+				<interfacename>MessageChannel</interfacename> beans in
+				<interfacename>@Configuration</interfacename> classes.
+				For more information, see <xref linkend="annotations"/>.
+			</para>
+		</section>
+		<section id="4.0-meta-messaging-annotations">
+			<title>Meta Messaging Annotations</title>
+			<para>
+				Messaging Annotations (<classname>@ServiceActivator</classname>, <classname>@Router</classname>,
+				<classname>@MessagingGateway</classname> etc.) can now be configured as meta-annotations for user-defined
+				Messaging Annotations. In addition the user-defined annotations can have the same attributes
+				(<code>inputChannel</code>, <code>@Poller</code>, <code>autoStartup</code> etc.).
+				For more information, see <xref linkend="annotations"/>.
+			</para>
+		</section>
 	</section>
 
 	<section id="4.0-general">
@@ -350,5 +370,14 @@
 				See <xref linkend="tcp-events"/> for more information.
 			</para>
 		</section>
+		<section id="4.0-bean-messaging-annotations">
+			<title>Messaging Annotations on @Bean Definitions</title>
+			<para>
+				Messaging Annotations (<classname>@ServiceActivator</classname>, <classname>@Router</classname>,
+				<classname>@InboundChannelAdapter</classname> etc.) can now be configured on <classname>@Bean</classname>
+				definitions in <interfacename>@Configuration</interfacename> classes.
+				For more information, see <xref linkend="annotations"/>.
+			</para>
+		</section>
 	</section>
 </chapter>