From 720efa502fa46698b588696cb4f8fedb1ca75962 Mon Sep 17 00:00:00 2001 From: Oleg Zhurakousky Date: Mon, 2 May 2011 16:09:56 -0400 Subject: [PATCH] INT-1833 added documentation about Mail filtering functionality --- docs/src/reference/docbook/mail.xml | 47 +++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/src/reference/docbook/mail.xml b/docs/src/reference/docbook/mail.xml index 107f840009..7e865ca656 100644 --- a/docs/src/reference/docbook/mail.xml +++ b/docs/src/reference/docbook/mail.xml @@ -199,5 +199,52 @@ warning by the channel adapter. + +
+ Email Message Filtering + + 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 Subject line). This + could be easily accomplished by connecting Inbound Mail adapter with an expression-based Filter. 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 should-mark-messages-as-read 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. + + + In Spring Integration 2.0.3 we've introduced mail-filter-expression attribute on inbound-channel-adapter and + imap-idle-channel-adapter. 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 mail-filter-expression attribute + like this this: mail-filter-expression="subject matches '(?i).*Spring Integration.*" + + + Since javax.mail.internet.MimeMessage 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. + + + + 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 mail-filter-expression only messages that contain 'Spring Integration' in the subject line will be + produced by this adapter. + + ]]> + + + 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. + +