GH-9613: Expose AbstractMailReceiver.setFlaggedAsFallback()

Fixes: #9613
Issue link: #9613

Sometimes even if `\Recent` or user flag is not supported by mail server, the `\Flagged` is also undesirable

* Expose `AbstractMailReceiver.setFlaggedAsFallback()` to disable setting `\Flagged` on the message as fallback
* As well as expose `MailInboundChannelAdapterSpec.flaggedAsFallback()`
* Document the new option

Author: artembilan

spring-integration-mail/src/main/java/org/springframework/integration/mail/AbstractMailReceiver.java

@@ -114,6 +114,8 @@ public abstract class AbstractMailReceiver extends IntegrationObjectSupport impl
 
 	private boolean autoCloseFolder = true;
 
+	private boolean flaggedAsFallback = true;
+
 	private volatile Store store;
 
 	private volatile Folder folder;
@@ -293,6 +295,16 @@ public void setAutoCloseFolder(boolean autoCloseFolder) {
 		this.autoCloseFolder = autoCloseFolder;
 	}
 
+	/**
+	 * Whether the {@link Flags.Flag#FLAGGED} flag should be added to the message
+	 * when {@code \Recent} or user flags are not supported on mail server.
+	 * @param flaggedAsFallback {@code false} to not add {@link Flags.Flag#FLAGGED} flag as a fallback.
+	 * @since 6.4
+	 */
+	public void setFlaggedAsFallback(boolean flaggedAsFallback) {
+		this.flaggedAsFallback = flaggedAsFallback;
+	}
+
 	protected Folder getFolder() {
 		return this.folder;
 	}
@@ -544,7 +556,7 @@ private void setMessageFlags(Message[] filteredMessages) throws MessagingExcepti
 					siFlags.add(this.userFlag);
 					message.setFlags(siFlags, true);
 				}
-				else {
+				else if (this.flaggedAsFallback) {
 					this.logger.debug("USER flags are not supported by this mail server. " +
 							"Flagging message with system flag");
 					message.setFlag(Flags.Flag.FLAGGED, true);
@@ -554,10 +566,6 @@ private void setMessageFlags(Message[] filteredMessages) throws MessagingExcepti
 		}
 	}
 
-	/**
-	 * Will filter Messages thru selector. Messages that did not pass selector filtering criteria
-	 * will be filtered out and remain on the server as never touched.
-	 */
 	private MimeMessage[] filterMessagesThruSelector(Message[] messages) throws MessagingException {
 		List<MimeMessage> filteredMessages = new LinkedList<>();
 		for (Message message1 : messages) {
@@ -567,13 +575,13 @@ private MimeMessage[] filterMessagesThruSelector(Message[] messages) throws Mess
 						this.selectorExpression.getValue(this.evaluationContext, message, Boolean.class))) {
 					filteredMessages.add(message);
 				}
-				else if (this.logger.isDebugEnabled()) {
+				else {
 					if (message.isExpunged()) {
 						this.logger.debug("Expunged message discarded and will not be further processed.");
 					}
 					else {
 						String subject = message.getSubject();
-						this.logger.debug("Fetched email with subject '" + subject +
+						this.logger.debug(() -> "Fetched email with subject '" + subject +
 								"' will be discarded by the matching filter and will not be flagged as SEEN.");
 					}
 				}
@@ -586,7 +594,7 @@ else if (this.logger.isDebugEnabled()) {
 	}
 
 	/**
-	 * Fetches the specified messages from this receiver's folder. Default
+	 * Fetch the specified messages from this receiver's folder. Default
 	 * implementation {@link Folder#fetch(Message[], FetchProfile) fetches}
 	 * every {@link jakarta.mail.FetchProfile.Item}.
 	 * @param messages the messages to fetch
@@ -601,7 +609,7 @@ protected void fetchMessages(Message[] messages) throws MessagingException {
 	}
 
 	/**
-	 * Deletes the given messages from this receiver's folder.
+	 * Delete the given messages from this receiver's folder.
 	 * @param messages the messages to delete
 	 * @throws MessagingException in case of JavaMail errors
 	 */

spring-integration-mail/src/main/java/org/springframework/integration/mail/dsl/MailInboundChannelAdapterSpec.java

@@ -269,6 +269,19 @@ public S autoCloseFolder(boolean autoCloseFolder) {
 		return _this();
 	}
 
+	/**
+	 * Whether the {@link jakarta.mail.Flags.Flag#FLAGGED} flag should be added to the message
+	 * when {@code \Recent} or user flags are not supported on mail server.
+	 * @param flaggedAsFallback {@code false} to not add {@link jakarta.mail.Flags.Flag#FLAGGED} flag as a fallback.
+	 * @return the spec.
+	 * @since 6.4
+	 */
+	public S flaggedAsFallback(boolean flaggedAsFallback) {
+		assertReceiver();
+		this.receiver.setFlaggedAsFallback(flaggedAsFallback);
+		return _this();
+	}
+
 	@Override
 	public Map<Object, String> getComponentsToRegister() {
 		return Collections.singletonMap(this.receiver, this.receiver.getComponentName());

src/reference/antora/modules/ROOT/pages/mail.adoc

@@ -328,7 +328,7 @@ The following example configures an IMAP `idle` mail channel:
 
 You can provide `javaMailProperties` by creating and populating a regular `java.utils.Properties` object -- for example, by using the `util` namespace provided by Spring.
 
-IMPORTANT: If your username contains the '@' character, use '%40' instead of '@' to avoid parsing errors from the underlying JavaMail API.
+IMPORTANT: If your username contains the `@` character, use `%40` instead of `@` to avoid parsing errors from the underlying JavaMail API.
 
 The following example shows how to configure a `java.util.Properties` object:
 
@@ -459,8 +459,11 @@ If `shouldMarkMessagesAsRead` is true, the IMAP adapters set the `\Seen` flag.
 In addition, when an email server does not support the `\Recent` flag, the IMAP adapters mark messages with a user flag (by default, `spring-integration-mail-adapter`), as long as the server supports user flags.
 If not, `Flag.FLAGGED` is set to `true`.
 These flags are applied regardless of the `shouldMarkMessagesRead` setting.
+However, starting with version 6.4, the `\Flagged` can be disabled, too.
+The `AbstractMailReceiver` exposes a `setFlaggedAsFallback(boolean flaggedAsFallback)` option to skip setting `\Flagged`.
+In some scenarios such a flag on the message in mailbox is not desirable, regardless `\Recent` or user flag is not suppoerted as well.
 
-As discussed in xref:mail.adoc#search-term[null], the default `SearchTermStrategy` ignore messages that are so flagged.
+As discussed in xref:mail.adoc#search-term[`SearchTerm`], the default `SearchTermStrategy` ignore messages that are so flagged.
 
 Starting with version 4.2.2, you can set the name of the user flag by using `setUserFlag` on the `MailReceiver`.
 Doing so lets multiple receivers use a different flag (as long as the mail server supports user flags).
@@ -473,12 +476,12 @@ Very often, you may encounter a requirement to filter incoming messages (for exa
 You can accomplish this by connecting an 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 the inbound mail adapter, all such messages would be marked as read (`SEEN`) or unread (depending on the value of `should-mark-messages-as-read` attribute).
-However, in reality, it be more useful to mark messages as `SEEN` only if they pass the filtering criteria.
+However, in reality, it is more useful to mark messages as `SEEN` only if they pass the filtering criteria.
 This is similar to looking at your email client while scrolling through all the messages in the preview pane, but only flagging messages that were actually opened and read as `SEEN`.
 
 Spring Integration 2.0.4 introduced the `mail-filter-expression` attribute on `inbound-channel-adapter` and `imap-idle-channel-adapter`.
 This attribute lets you provide an expression that is a combination of SpEL and a regular expression.
-For example if you would like to read only emails that contain 'Spring Integration' in the subject line, you would configure the `mail-filter-expression` attribute like as follows: `mail-filter-expression="subject matches '(?i).*Spring Integration.*"`.
+For example if you would like to read only emails that contain 'Spring Integration' in the subject line, you would configure the `mail-filter-expression` attribute like as follows: `mail-filter-expression="subject matches '(?i).\*Spring Integration.*"`.
 
 Since `jakarta.mail.internet.MimeMessage` is the root context of the 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 typically results in such messages being marked as `SEEN` by default.

src/reference/antora/modules/ROOT/pages/whats-new.adoc

@@ -97,3 +97,9 @@ See xref:zip.adoc[Zip Support] for more information.
 
 The Python scripts evaluation is now migrated to the GraalVM Polyglot.
 See xref:scripting.adoc[Scripting Support] for more information.
+
+[[x6.4-mail-changes]]
+=== Mail Changes
+
+The `AbstractMailReceiver` exposes an option to disable setting `Flags.Flag.FLAGGED` into a received message as fallback flag.
+See xref:mail.adoc[Mail Support] for more information.