From aded1d56df53335ecc5bfd7a79acf9633c80fb79 Mon Sep 17 00:00:00 2001
From: Mark Fisher <markfisher@vmware.com>
Date: Fri, 14 Nov 2008 01:03:07 +0000
Subject: [PATCH] Added discussion of the inbound Mail support (INT-459)

---
 spring-integration-reference/src/mail.xml | 36 +++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/spring-integration-reference/src/mail.xml b/spring-integration-reference/src/mail.xml
index df20eadf0b..ee9c863be0 100644
--- a/spring-integration-reference/src/mail.xml
+++ b/spring-integration-reference/src/mail.xml
@@ -36,6 +36,26 @@
     </para>
   </section>
 
+  <section id="mail-inbound">
+    <title>Mail-Receiving Channel Adapter</title>
+    <para>
+      Spring Integration also provides support for inbound email with the
+      <classname>MailReceivingMessageSource</classname>. It delegates to a configured instance of Spring
+      Integration's own <interfacename>MailReceiver</interfacename> interface, and there are two implementations:
+      <classname>Pop3MailReceiver</classname> and <classname>ImapMailReceiver</classname>. The easiest way to
+      instantiate either of these is by passing the 'uri' for a Mail store to the receiver's constructor. For example:
+      <programlisting language="java"><![CDATA[ MailReceiver receiver = new Pop3MailReceiver("pop3://usr:pwd@localhost/INBOX");
+]]></programlisting>
+    </para>
+    <para>
+      Another option for receiving mail is the IMAP "idle" command (if supported by the mail server you are using).
+      Spring Integration provides the <classname>ImapIdleChannelAdapter</classname> which is itself a Message-producing
+      endpoint. It delegates to an instance of the <classname>ImapMailReceiver</classname> but enables asynchronous
+      reception of Mail Messages. There are examples in the next section of configuring both types of inbound Channel
+      Adapter with Spring Integration's namespace support in the 'mail' schema.
+    </para>
+  </section>
+
   <section id="mail-namespace">
     <title>Mail Namespace Support</title>
     <para>
@@ -61,6 +81,22 @@
         &lt;poller&gt; sub-element should be provided with either an interval-trigger or cron-trigger.
       </note>
     </para>
+    <para>
+      To configure an inbound Channel Adapter, you have the choice between polling or event-driven (assuming your
+      mail server supports IMAP IDLE - if not, then polling is the only option). A polling Channel Adapter simply
+      requires the store URI and the channel to send inbound Messages to. The URI may begin with "pop3" or "imap":
+      <programlisting language="xml"><![CDATA[ <mail:inbound-channel-adapter channel="mailIn"
+                               store-uri="imap://usr:pwd@imap.example.com/INBOX">
+     <poller max-messages-per-poll="3">
+         <interval-trigger interval="30" time-unit="SECONDS"/>
+     </poller>
+ </mail:inbound-channel-adapter>]]></programlisting>
+      If you do have IMAP idle support, then you may want to configure the "imap-idle-channel-adapter" element instead.
+      Since the "idle" command enables event-driven notifications, no poller is necessary for this adapter. It will
+      send a Message to the specified channel as soon as it receives the notification that new mail is available:
+      <programlisting language="xml"><![CDATA[ <mail:imap-idle-channel-adapter channel="mailIn"
+                                 store-uri="imaps://usr:pwd@imap.example.com:993/INBOX"/>]]></programlisting>
+    </para>
     <para>
       When using the namespace support, a <emphasis>header-enricher</emphasis> Message Transformer is also available.
       This simplifies the application of the headers mentioned above to any Message prior to sending to the