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

INT-1833 added documentation about Mail filtering functionality

Browse Source
This commit is contained in:
Oleg Zhurakousky
2011-05-02 16:09:56 -04:00
parent be9b57a81a
commit 720efa502f
1 changed files with 47 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/src/reference/docbook/mail.xml
View File

@@ -199,5 +199,52 @@
warning by the channel adapter.
</para>
</section>
<section id="mail-filtering">
<title>Email Message Filtering</title>
<para>
Very often you may encounter a requirement to filter incoming messages
(e.g., You want to only read emails that have 'Spring Integration' in the <emphasis>Subject</emphasis> line). This
could be easily accomplished by connecting Inbound Mail adapter with an expression-based <emphasis>Filter</emphasis>. Although it would work, there is a
downside to this approach. Since messages would be filtered after going through inbound mail adapter all such messages would be marked as read (SEEN) or
Un-read (depending on the value of <code>should-mark-messages-as-read</code> attribute). However in reality what would be more useful is to mark messages
as SEEN only if they passed the filtering criteria. This is very similar to looking at your email client while scrolling through all the
messages in the preview pane, but only flagging messages as SEEN that were actually opened and read.
</para>
<para>
In Spring Integration 2.0.3 we've introduced <code>mail-filter-expression</code> attribute on <code>inbound-channel-adapter</code> and
<code>imap-idle-channel-adapter</code>. This attribute allows you to provide an expression which is a combination of SpEL and Regular Expression.
For example if you would like to read only emails that contain 'Spring Integration' in the Subject line, you would configure <code>mail-filter-expression</code> attribute
like this this: <code>mail-filter-expression="subject matches '(?i).*Spring Integration.*"</code>
</para>
<para>
Since <classname>javax.mail.internet.MimeMessage</classname> is the root context of SpEL Evaluation Context, you can filter on any value available
through MimeMessage including the actual body of the message. This one is particularly important since reading the body of the message would
typically result in such message to be marked as SEEN by default, but since we now setting PEAK flag of every incomming message to 'true', only
messages that were explicitly marked as SEEN will be seen as read.
</para>
<para>
So in the below example only messages that match the filter expression will be output by this adapter and only those messages will be marked as SEEN.
In this case based on the <code>mail-filter-expression</code> only messages that contain 'Spring Integration' in the subject line will be
produced by this adapter.
<programlisting language="xml"><![CDATA[<int-mail:imap-idle-channel-adapter id="customAdapter"
store-uri="imaps://some_google_address:${password}@imap.gmail.com/INBOX"
channel="receiveChannel"
should-mark-messages-as-read="true"
java-mail-properties="javaMailProperties"
mail-filter-expression="subject matches '(?i).*Spring Integration.*'"/>]]></programlisting>
</para>
<para>
Another reasonable question is what happens on the next poll, or idle event, or what happens when such adapter is restarted.
Will there be a potential duplication of massages to be filtered? In other words if on the last retrieval where you had 5 new messages and only 1 passed
the filter what would happen with the other 4. Would they go through the filtering logic again on the next poll or idle? After all they were not marked
as SEEN. The actual answer is no. They would not be subject of duplicate processing due to another flag (RECENT) that is set by the Email server and
is used by Spring Integration mail search filter. Folder implementations set this flag to indicate that this message is new to this folder, that is,
it has arrived since the last time this folder was opened. In other while our adapter may peek at the email it also lets the email server know that
such email was touched and therefore will be marked as RECENT by the email server.
</para>
</section>
</chapter>