Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #549 from ghillert/INT-2574

Browse Source
This commit is contained in:
Gary Russell
2012-07-16 10:38:02 -04:00
parent c5d6980a5b 0d81837e1b
commit a90a7e8e0b
2 changed files with 79 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
src/reference/docbook/channel-adapter.xml
View File

@@ -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
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
specified in the Poller.
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
which produces the value that becomes a <classname>Message</classname> payload) based on the configuration
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)
the method (which results in the production of the Message) will be invoked once based on the
<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
<para>
In the the first configuration the polling task will be invoked once per poll and during such task (poll)
the method (which results in the production of the Message) will be invoked once based on the
<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
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
<para>
Note there is no <code>max-messages-per-poll</code> specified. As you'll learn later the identical poller configuration
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
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
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)
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
for as many sources as available per each poll, then you should explicitly set <code>max-messages-per-poll</code>
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>
to negative value.
</para>
<programlisting language="xml"><![CDATA[<int:poller max-messages-per-poll="-1" fixed-rate="1000"/>]]></programlisting>
</para>
</important>
</section>

59
src/reference/docbook/jdbc.xml
View File

@@ -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>
<para>If you want to convert rows in the SELECT query result to
individual messages you can use a downstream splitter.</para>
</note></para>
JDBC</ulink> documentation for more detailed information about row mapping).
</para>
<note>
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>