Improve Delayer docs around messageGroupId

* Mention in the Javadocs of the `DelayHandler`, `DelayerEndpointSpec`,
`BaseIntegrationFlowDefinition.delay()`, `GroovyIntegrationFlowDefinition.delay()`,
`KotlinIntegrationFlowDefinition.delay()` that `messageGroupId` is required option
* Explain in the docs why `messageGroupId` is required and why it cannot rely on a bean name

spring-integration-core/src/main/java/org/springframework/integration/dsl/BaseIntegrationFlowDefinition.java

@@ -1208,6 +1208,7 @@ public abstract class BaseIntegrationFlowDefinition<B extends BaseIntegrationFlo
 
 	/**
 	 * Populate a {@link DelayHandler} to the current integration flow position.
+	 * The {@link DelayerEndpointSpec#messageGroupId(String)} is required option.
 	 * @param endpointConfigurer the {@link Consumer} to provide integration endpoint options.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
 	 * @since 6.2

spring-integration-core/src/main/java/org/springframework/integration/dsl/DelayerEndpointSpec.java

@@ -36,11 +36,14 @@ import org.springframework.util.Assert;
 
 /**
  * A {@link ConsumerEndpointSpec} for a {@link DelayHandler}.
+ * The {@link #messageGroupId(String)} is required option.
  *
  * @author Artem Bilan
  * @author Gary Russell
  *
  * @since 5.0
+ *
+ * @see DelayHandler
  */
 public class DelayerEndpointSpec extends ConsumerEndpointSpec<DelayerEndpointSpec, DelayHandler> {
 
@@ -96,13 +99,12 @@ public class DelayerEndpointSpec extends ConsumerEndpointSpec<DelayerEndpointSpe
 		return _this();
 	}
 
-	public DelayerEndpointSpec delayExpression(Expression delayExpression) {
-		this.handler.setDelayExpression(delayExpression);
-		return this;
+	public DelayerEndpointSpec delayExpression(String delayExpression) {
+		return delayExpression(PARSER.parseExpression(delayExpression));
 	}
 
-	public DelayerEndpointSpec delayExpression(String delayExpression) {
-		this.handler.setDelayExpression(PARSER.parseExpression(delayExpression));
+	public DelayerEndpointSpec delayExpression(Expression delayExpression) {
+		this.handler.setDelayExpression(delayExpression);
 		return this;
 	}
 
@@ -225,12 +227,12 @@ public class DelayerEndpointSpec extends ConsumerEndpointSpec<DelayerEndpointSpe
 	 * @return the endpoint spec.
 	 */
 	public <P> DelayerEndpointSpec delayFunction(Function<Message<P>, Object> delayFunction) {
-		this.handler.setDelayExpression(new FunctionExpression<>(delayFunction));
-		return this;
+		return delayExpression(new FunctionExpression<>(delayFunction));
 	}
 
 	/**
 	 * Set a group id to manage delayed messages by this handler.
+	 * Required.
 	 * @param messageGroupId the group id for delayed messages.
 	 * @return the endpoint spec.
 	 * @since 6.2

spring-integration-core/src/main/java/org/springframework/integration/handler/DelayHandler.java

@@ -83,6 +83,17 @@ import org.springframework.util.ObjectUtils;
  * Message can be released as soon as five seconds from the current time). If the value is
  * a Date, it will be delayed at least until that Date occurs (i.e. the delay in that case
  * is equivalent to {@code headerDate.getTime() - new Date().getTime()}).
+ * <p>
+ * Delayed messages are stored in the {@link MessageGroupStore} as a dedicated group.
+ * If an external persistent store is provided, those delayed messages will be rescheduled
+ * after application startup.
+ * The {@link #messageGroupId} is required option and must be unique for each delayer
+ * configuration to avoid work-stealing from the store and unexpected releases.
+ * Different instances of the same delayer can point to the same message group in the store.
+ * The {@link #messageGroupId} cannot rely on a bean name which might be generated.
+ * After application restart the bean may get a different generated name and its delayed
+ * messages might be lost from reschedule since its group is not managed
+ * by the application anymore.
  *
  * @author Mark Fisher
  * @author Artem Bilan
@@ -90,7 +101,6 @@ import org.springframework.util.ObjectUtils;
  *
  * @since 1.0.3
  */
-
 @ManagedResource
 @IntegrationManagedResource
 public class DelayHandler extends AbstractReplyProducingMessageHandler implements DelayHandlerManagement,
@@ -132,7 +142,7 @@ public class DelayHandler extends AbstractReplyProducingMessageHandler implement
 
 	/**
 	 * Construct an instance with default options.
-	 * The {@link #messageGroupId}must then be provided via the setter.
+	 * The {@link #messageGroupId} must then be provided via the setter.
 	 * @since 6.2
 	 */
 	public DelayHandler() {
@@ -165,6 +175,7 @@ public class DelayHandler extends AbstractReplyProducingMessageHandler implement
 
 	/**
 	 * Set a group id to manage delayed messages by this handler.
+	 * Required.
 	 * @param messageGroupId the group id for delayed messages.
 	 * @since 6.2
 	 */

spring-integration-core/src/main/kotlin/org/springframework/integration/dsl/KotlinIntegrationFlowDefinition.kt

@@ -573,6 +573,7 @@ class KotlinIntegrationFlowDefinition(@PublishedApi internal val delegate: Integ
 
 	/**
 	 * Populate a [DelayHandler] to the current integration flow position.
+	 * The [DelayerEndpointSpec#messageGroupId(String)] is required option.
 	 * @since 6.2
 	 */
 	fun delay(endpointConfigurer: DelayerEndpointSpec.() -> Unit) {