Merge pull request #549 from ghillert/INT-2574

src/reference/docbook/channel-adapter.xml

@@ -13,7 +13,7 @@
   </para>
 
   <section id="channel-adapter-namespace-inbound">
-    <title>Configuring Inbound Channel Adapter</title>
+    <title>Configuring An Inbound Channel Adapter</title>
     <para>
       An "inbound-channel-adapter" element can invoke any method on a Spring-managed Object and send a non-null return
       value to a <interfacename>MessageChannel</interfacename> after converting it to a <classname>Message</classname>.
@@ -38,43 +38,45 @@
     <important>
     	<para><emphasis>Poller Configuration</emphasis> </para>
     	<para>
-    	Some <code>inbound-channel-adapter</code> types are backed by a <classname>SourcePollingChannelAdapter</classname> which 
+    	Some <code>inbound-channel-adapter</code> types are backed by a <classname>SourcePollingChannelAdapter</classname> which
-    	means they contain Poller configuration which will poll the <classname>MessageSource</classname> (invoke a custom method 
+    	means they contain Poller configuration which will poll the <classname>MessageSource</classname> (invoke a custom method
-    	which produces the value that becomes a <classname>Message</classname> payload) based on the configuration 
+    	which produces the value that becomes a <classname>Message</classname> payload) based on the configuration
-    	specified in the Poller. 
+    	specified in the Poller.
     	</para>
-    	<para>For example:
+		<para>
-    	
+			For example:
+		</para>
     	<programlisting language="xml"><![CDATA[<int:poller max-messages-per-poll="1" fixed-rate="1000"/>
 
 <int:poller max-messages-per-poll="10" fixed-rate="1000"/>]]></programlisting>
-		In the the first configuration the polling task will be invoked once per poll and during such task (poll) 
+		<para>
-		the method (which results in the production of the Message) will be invoked once based on the 
+		In the the first configuration the polling task will be invoked once per poll and during such task (poll)
-		<code>max-messages-per-poll</code> attribute value. In the second configuration the polling task will be invoked 
+		the method (which results in the production of the Message) will be invoked once based on the
-		10 times per poll or until it returns 'null' thus possibly producing 10 Messages per poll while each poll happens 
+		<code>max-messages-per-poll</code> attribute value. In the second configuration the polling task will be invoked
+		10 times per poll or until it returns 'null' thus possibly producing 10 Messages per poll while each poll happens
 		at 1 second intervals.
 		However what if the configuration looks like this:
+		</para>
 		<programlisting language="xml"><![CDATA[<int:poller fixed-rate="1000"/>]]></programlisting>
-		Note there is no <code>max-messages-per-poll</code> specified. As you'll learn later the identical poller configuration 
+		<para>
-		in the <classname>PollingConsumer</classname> (e.g., service-activator, filter, router etc.) would have a default 
+		Note there is no <code>max-messages-per-poll</code> specified. As you'll learn later the identical poller configuration
-		value of -1 for <code>max-messages-per-poll</code> which means "execute poling task non-stop unless polling method 
+		in the <classname>PollingConsumer</classname> (e.g., service-activator, filter, router etc.) would have a default
+		value of -1 for <code>max-messages-per-poll</code> which means "execute poling task non-stop unless polling method
 		returns null (e.g., no more Messages in the QueueChannel)" and then sleep for 1 second.
     	</para>
     	<para>
     	However in the SourcePollingChannelAdapter it is a bit different.
-		The default value for <code>max-messages-per-poll</code> will be set to 1 by default unless you explicitly set it to 
+		The default value for <code>max-messages-per-poll</code> will be set to 1 by default unless you explicitly set it to
-		a negative value (e.g., -1). It is done so to make sure that poller can react to a LifeCycle events (e.g., start/stop) 
+		a negative value (e.g., -1). It is done so to make sure that poller can react to a LifeCycle events (e.g., start/stop)
-        and prevent it from potentially spinning in the infinite loop if the implementation of the custom 
+        and prevent it from potentially spinning in the infinite loop if the implementation of the custom
 		method of the <classname>MessageSource</classname> has a potential to never return null and happened to be non-interruptible.
     	</para>
     	<para>
-    	However if you are sure that your method can return null and you need the behavior where you want to poll 
+    	However if you are sure that your method can return null and you need the behavior where you want to poll
-    	for as many sources as available per each poll, then you should explicitly set <code>max-messages-per-poll</code> 
+    	for as many sources as available per each poll, then you should explicitly set <code>max-messages-per-poll</code>
     	to negative value.
+		</para>
 		<programlisting language="xml"><![CDATA[<int:poller max-messages-per-poll="-1" fixed-rate="1000"/>]]></programlisting>
-
-    	</para>
-    	
     </important>
   </section>
 

src/reference/docbook/jdbc.xml

@@ -49,10 +49,12 @@
     row in the query result. Optionally, this can be changed by adding a reference to
     a <classname>RowMapper</classname> instance (see the
     <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/jdbc.html">Spring
-    JDBC</ulink> documentation for more detailed information about row mapping).<note>
+    JDBC</ulink> documentation for more detailed information about row mapping).
-        <para>If you want to convert rows in the SELECT query result to
+	</para>
-        individual messages you can use a downstream splitter.</para>
+	<note>
-      </note></para>
+		If you want to convert rows in the SELECT query result to
+		individual messages you can use a downstream splitter.
+	</note>
 
     <para>The inbound adapter also requires a reference to either
     a <classname>JdbcTemplate</classname> instance or
@@ -105,6 +107,46 @@
       the transaction rolls back and the input data is reverted to its
       original state.</para>
     </section>
+	<section id="jdbc-max-rows-per-poll-versus-max-messages-per-poll">
+		<title>Max-rows-per-poll versus Max-messages-per-poll</title>
+		<para>
+			The <emphasis>JDBC Inbound Channel Adapter</emphasis> defines an attribute
+			<emphasis>max-rows-per-poll</emphasis>. When you
+			specify the adapter's <emphasis>Poller</emphasis>, you can also
+			define a property called <emphasis>max-messages-per-poll</emphasis>. While
+			these two attributes look similar, their meaning is
+			quite different.
+		</para>
+		<para><emphasis>max-messages-per-poll</emphasis> specifies the number of times
+			the query is executed per polling interval, whereas <emphasis>max-rows-per-poll</emphasis>
+			specifies the number of rows returned for each execution.
+		</para>
+		<para>
+			Under normal circumstances, you would likely not want to set the Poller's
+			<emphasis>max-messages-per-poll</emphasis> property when using
+			the <emphasis>JDBC Inbound Channel Adapter</emphasis>. Its default value
+			is <emphasis>1</emphasis>, which means that the <emphasis>JDBC
+			Inbound Channel Adapter's</emphasis>
+			<emphasis><ulink url="http://static.springsource.org/spring-integration/api/org/springframework/integration/jdbc/JdbcPollingChannelAdapter.html#receive()">receive()</ulink></emphasis>
+			method is executed exactly once for each poll interval.
+		</para>
+		<para>
+			Setting the <emphasis>max-messages-per-poll</emphasis>
+			attribute to a larger value means that the query is executed that many times
+			back to back.
+			For more information regarding the <emphasis>max-messages-per-poll</emphasis>
+			attribute, please see <xref linkend="channel-adapter-namespace-inbound"/>.
+		</para>
+		<para>
+			In contrast, the <emphasis>max-rows-per-poll</emphasis> attribute,
+			if greater than <emphasis>0</emphasis>, specifies
+			the maximum number of rows that will be used from the query result set,
+			per execution of the <emphasis>receive()</emphasis> method.
+			If the attribute is set to <emphasis>0</emphasis>, then all rows will
+			be included in the resulting message. If not explicitly set, the
+			attribute defaults to <emphasis>0</emphasis>.
+		</para>
+	</section>
   </section>
 
   <section id="jdbc-outbound-channel-adapter">
@@ -799,6 +841,15 @@
                          </para>
                     </callout>
               </calloutlist></para>
+			<note>
+				When you declare a Poller, you may notice the Poller's
+				<emphasis>max-messages-per-poll</emphasis> attribute. For information about
+				how it relates to the <emphasis>max-rows-per-poll</emphasis> attribute
+				of the <emphasis>Stored Procedure Inbound Channel Adapter</emphasis>,
+				please see <xref linkend="jdbc-max-rows-per-poll-versus-max-messages-per-poll"/>
+				for a thourough discussion. The meaning of the attributes
+				is the same as for the <emphasis>JDBC Inbound Channel Adapter</emphasis>.
+			</note>
 	    </section>
         <section id="stored-procedure-outbound-channel-adapter">
             <title>Stored Procedure Outbound Channel Adapter</title>