INT-3351: Add @Poller for Messaging Annotations

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

INT-3351: Polishing according PR comments

* Add `property-placeholder` support for `@Poller`
* Change `ref` to `value`
* Add JavaDoc for `array` workaround
* Add docs

INT-3351: Polishing and fixes

INT-3351 More Tests

INT-3351: PR comments

INT-3351 Final Polishing

src/reference/docbook/configuration.xml

@@ -314,19 +314,8 @@ public class FooService {
       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>
-      <note>
-        When configuring the "inputChannel" and "outputChannel" with annotations, the "inputChannel"
-        <emphasis>must</emphasis> be a reference to a <interfacename>SubscribableChannel</interfacename> instance.
-        Otherwise, it would be necessary to also provide the full poller configuration via annotations, and those
-        settings (e.g. the trigger for scheduling the poller) should be externalized rather than hard-coded within
-        an annotation. If the input channel that you want to receive Messages from is indeed a
-        <interfacename>PollableChannel</interfacename> instance, one option to consider is the Messaging Bridge.
-        Spring Integration's "bridge" element can be used to connect a PollableChannel directly to a
-        SubscribableChannel. Then, the polling metadata is externally configured, but the annotation option is
-        still available. For more detail see <xref linkend="bridge"/>.
-      </note>
     </para>
-	  <para>
+	 <para>
 		  The processing of these annotations creates the same beans (<classname>EventDrivenConsumer</classname>s and
 		  <interfacename>MessageHandler</interfacename>s) as with similar xml components. The bean names are generated
 		  with this pattern:
@@ -335,6 +324,67 @@ public class FooService {
 		  the <interfacename>MessageHandler</interfacename> bean. The
 		  <interfacename>MessageHandler</interfacename>s are also eligible to be tracked by <xref linkend="message-history"/>.
 	  </para>
+	  <para>
+		  <emphasis role="bold">@Poller</emphasis>
+	  </para>
+	  <para>
+		  Before <emphasis>Spring Integration 4.0</emphasis>, the above Messaging Annotations required that the
+		  <code>inputChannel</code> was a reference to a <interfacename>SubscribableChannel</interfacename>.
+		  For <interfacename>PollableChannel</interfacename>s there was need to use a <code>&lt;int:bridge/&gt;</code>,
+		  to configure a <code>&lt;int:poller/&gt;</code> to make the composite endpoint - a <classname>PollingConsumer</classname>.
+		  Starting with <emphasis>version 4.0</emphasis>,
+		  the <interfacename>@Poller</interfacename> annotation has been introduced to allow the configuration of
+		  <code>poller</code> attributes directly on the above Messaging Annotations:
+		  <programlisting language="java"><![CDATA[public class AnnotationService {
+
+	@Transformer(inputChannel = "input", outputChannel = "output",
+		poller = @Poller(maxMessagesPerPoll = "${poller.maxMessagesPerPoll}", fixedDelay = "${poller.fixedDelay}"))
+	public String handle(String payload) {
+		...
+	}
+}]]></programlisting>
+		  This annotation provides only simple <classname>PollerMetadata</classname> options. The
+		  <interfacename>@Poller</interfacename>'s attributes <code>maxMessagesPerPoll</code>, <code>fixedDelay</code>,
+		  <code>fixedRate</code> and <code>cron</code> can be configured with <emphasis>property-placeholder</emphasis>s.
+		  If it is necessary to provide more polling options (e.g. transaction, advice-chain, error-handler), the
+		  <classname>PollerMetadata</classname> should be configured as a generic bean with its bean name used for
+		  <interfacename>@Poller</interfacename>'s <code>value</code> attribute. In this case, no other attributes are allowed
+		  (they would be specified on the <classname>PollerMetadata</classname> bean).
+		  Note, if <code>inputChannel</code> is <interfacename>PollableChannel</interfacename> and
+		  no <interfacename>@Poller</interfacename> is configured,
+		  the default <classname>PollerMetadata</classname> will be used, if it is present in the application context.
+		  To declare the default poller using <code>@Configuration</code>, use:
+		  <programlisting language="java"><![CDATA[@Bean(name = PollerMetadata.DEFAULT_POLLER)
+public PollerMetadata defaultPoller() {
+	PollerMetadata pollerMetadata = new PollerMetadata();
+	pollerMetadata.setTrigger(new PeriodicTrigger(10));
+	return pollerMetadata;
+}]]></programlisting>
+		  With this endpoint using the default poller:
+		  <programlisting language="java"><![CDATA[public class AnnotationService {
+
+	@Transformer(inputChannel = "aPollableChannel", outputChannel = "output")
+	public String handle(String payload) {
+		...
+	}
+}]]></programlisting>
+		  To use a named poller, use:
+		  <programlisting language="java"><![CDATA[@Bean
+public PollerMetadata myPoller() {
+	PollerMetadata pollerMetadata = new PollerMetadata();
+	pollerMetadata.setTrigger(new PeriodicTrigger(1000));
+	return pollerMetadata;
+}]]></programlisting>
+		  With this endpoint using the default poller:
+		  <programlisting language="java"><![CDATA[public class AnnotationService {
+
+	@Transformer(inputChannel = "aPollableChannel", outputChannel = "output"
+						poller = @Poller("myPoller")
+	public String handle(String payload) {
+		...
+	}
+}]]></programlisting>
+	  </para>
     <para>
         Also see <xref linkend="advising-with-annotations"/>.
     </para>

src/reference/docbook/whats-new.xml

@@ -142,6 +142,16 @@
 				For more information, see <xref linkend="redis-lock-registry"/> and <xref linkend="aggregator"/>.
 			</para>
 		</section>
+		<section id="4.0-poller-annotation">
+			<title>@Poller</title>
+			<para>
+				Annotation-based messaging configuration can now have a <code>poller</code> attribute.
+				This means that methods annotated with (<interfacename>@ServiceActivator</interfacename>,
+				<interfacename>@Aggregator</interfacename> etc.) can now use an <code>inputChannel</code> that
+				is a reference to a <interfacename>PollableChannel</interfacename>.
+				For more information, see <xref linkend="annotations"/>.
+			</para>
+		</section>
 	</section>
 
 	<section id="4.0-general">