Update documentation for Task Execution

Signed-off-by: Dmytro Nosan <[email protected]>

Author: nosan

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/task-execution-and-scheduling.adoc

@@ -5,7 +5,59 @@ In the absence of an javadoc:java.util.concurrent.Executor[] bean in the context
 When virtual threads are enabled (using Java 21+ and configprop:spring.threads.virtual.enabled[] set to `true`) this will be a javadoc:org.springframework.core.task.SimpleAsyncTaskExecutor[] that uses virtual threads.
 Otherwise, it will be a javadoc:org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor[] with sensible defaults.
 
-If a custom `Executor` bean is present, you can request Spring Boot to auto-configure an `AsyncTaskExecutor` anyway, as follows:
+[NOTE]
+====
+The auto-configured javadoc:org.springframework.core.task.AsyncTaskExecutor[] will be used for all
+integrations unless a custom javadoc:java.util.concurrent.Executor[] bean is provided.
+====
+
+Although this works in most cases, Spring Boot provides the option to override the auto-configured
+javadoc:org.springframework.core.task.AsyncTaskExecutor[]. By default, when a custom
+javadoc:java.util.concurrent.Executor[] bean is registered, the auto-configured javadoc:org.springframework.core.task.AsyncTaskExecutor[]
+backs off, and custom javadoc:java.util.concurrent.Executor[] will be used for regular task execution
+(via javadoc:org.springframework.scheduling.annotation.EnableAsync[format=annotation]).
+However, Spring MVC, Spring WebFlux, and Spring GraphQL all require a bean named `applicationTaskExecutor`.
+For Spring MVC and Spring WebFlux, this bean must be of type javadoc:org.springframework.core.task.AsyncTaskExecutor[],
+whereas Spring GraphQL does not  have this requirement.
+
+The following code snippet demonstrates how to register a custom javadoc:org.springframework.core.task.AsyncTaskExecutor[]
+to be used with Spring MVC, Spring WebFlux and Spring GraphQL.
+
+include-code::TaskExecutionConfigurationExamples[tag=application-task-executor]
+
+[NOTE]
+====
+The `applicationTaskExecutor` above will be used for regular task execution as well if there is no `@Primary` bean
+or a bean named `taskExecutor`  of type javadoc:java.util.concurrent.Executor[] is registered in the application context.
+====
+
+If your application needs multiple javadoc:java.util.concurrent.Executor[] beans for different purposes and configurations,
+such as one for regular task execution (`@EnableAsync`) and another for Spring MVC, this can be achieved with the following configuration:
+
+include-code::TaskExecutionConfigurationExamples[tag=multiple-task-executor]
+
+[TIP]
+====
+The auto-configured javadoc:org.springframework.boot.task.ThreadPoolTaskExecutorBuilder[] or javadoc:org.springframework.boot.task.SimpleAsyncTaskExecutorBuilder[] allow you to easily create instances
+of type javadoc:org.springframework.core.task.AsyncTaskExecutor[] that replicate the default behavior of auto-configuration.
+====
+
+[WARNING]
+====
+If neither the auto-configured `AsyncTaskExecutor` nor the bean named `applicationTaskExecutor` is defined,
+only regular task execution fallbacks to a bean named `taskExecutor` to match Spring Framework's behavior.
+====
+
+If a bean named `taskExecutor` cannot be used, you can register an
+javadoc:org.springframework.scheduling.annotation.AsyncConfigurer[] bean to specify which `Executor` should handle regular task execution with `@EnableAsync`.
+
+To register a custom javadoc:java.util.concurrent.Executor[] while keeping the auto-configured javadoc:org.springframework.core.task.AsyncTaskExecutor[],
+you can create a custom javadoc:java.util.concurrent.Executor[] bean and set the `defaultCandidate=false` attribute
+in its javadoc:org.springframework.context.annotation.Bean[format=annotation] annotation, as demonstrated in the following example.
+
+include-code::TaskExecutionConfigurationExamples[tag=default-candidate-task-executor]
+
+If for some reason, it is not possible, you can request Spring Boot to auto-configure an `AsyncTaskExecutor` anyway, as follows:
 
 [configprops,yaml]
 ----
@@ -15,7 +67,7 @@ spring:
       mode: force
 ----
 
-The auto-configured executor will be automatically used for:
+The auto-configured javadoc:org.springframework.core.task.AsyncTaskExecutor[] will be automatically used for:
 
 - Asynchronous task execution (`@EnableAsync`), unless an javadoc:org.springframework.scheduling.annotation.AsyncConfigurer[] bean is present.
 - Spring for GraphQL's asynchronous handling of javadoc:java.util.concurrent.Callable[] return values from controller methods.
@@ -24,22 +76,17 @@ The auto-configured executor will be automatically used for:
 
 [TIP]
 ====
-If you have defined a custom javadoc:java.util.concurrent.Executor[] in the context, both regular task execution (that is javadoc:org.springframework.scheduling.annotation.EnableAsync[format=annotation]) and Spring for GraphQL will use it.
-However, the Spring MVC and Spring WebFlux support will only use it if it is an javadoc:org.springframework.core.task.AsyncTaskExecutor[] implementation named `applicationTaskExecutor`.
-
 Depending on your target arrangement, you could set configprop:spring.task.execution.mode[] to `force` to auto-configure an `applicationTaskExecutor`, change your javadoc:java.util.concurrent.Executor[] into an javadoc:org.springframework.core.task.AsyncTaskExecutor[] or define both an javadoc:org.springframework.core.task.AsyncTaskExecutor[] and an javadoc:org.springframework.scheduling.annotation.AsyncConfigurer[] wrapping your custom javadoc:java.util.concurrent.Executor[].
-
-Another option is to define those beans explicitly.
-The auto-configured javadoc:org.springframework.boot.task.ThreadPoolTaskExecutorBuilder[] or javadoc:org.springframework.boot.task.SimpleAsyncTaskExecutorBuilder[] allow you to easily create instances that reproduce what the auto-configuration does by default.
 ====
 
-[NOTE]
+[WARNING]
 ====
-If multiple javadoc:java.util.concurrent.Executor[] beans are defined with configprop:spring.task.execution.mode[] to `force`, all the supported integrations look for a bean named `applicationTaskExecutor`.
-If the auto-configured `AsyncTaskExecutor` is not defined, only regular task execution fallbacks to a bean named `taskExecutor` to match Spring Framework's behavior.
+When `force` mode is enabled, `applicationTaskExecutor` will also be configured for regular
+task execution with `@EnableAsync`, even if a `@Primary` bean or a bean named `taskExecutor`
+of type javadoc:java.util.concurrent.Executor[] is present. The only way to override the `Executor`
+for regular tasks is by registering an javadoc:org.springframework.scheduling.annotation.AsyncConfigurer[] bean.
 ====
 
-
 When a javadoc:org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor[] is auto-configured, the thread pool uses 8 core threads that can grow and shrink according to the load.
 Those default settings can be fine-tuned using the `spring.task.execution` namespace, as shown in the following example:
 

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/taskexecutionandscheduling/TaskExecutionConfigurationExamples.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.features.taskexecutionandscheduling;
+
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.context.annotation.Bean;
+import org.springframework.core.task.SimpleAsyncTaskExecutor;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
+
+public class TaskExecutionConfigurationExamples {
+
+	static class TaskExecutorWithDefaultCandidate {
+
+		// tag::default-candidate-task-executor[]
+		@Bean(defaultCandidate = false)
+		@Qualifier("myScheduler")
+		ScheduledExecutorService myScheduler() {
+			return Executors.newSingleThreadScheduledExecutor();
+		}
+		// end::default-candidate-task-executor[]
+
+	}
+
+	static class ApplicationTaskExecutor {
+
+		// tag::application-task-executor[]
+		@Bean("applicationTaskExecutor")
+		SimpleAsyncTaskExecutor applicationTaskExecutor() {
+			return new SimpleAsyncTaskExecutor("my-app-");
+		}
+		// end::application-task-executor[]
+
+	}
+
+	static class MultipleTaskExecutor {
+
+		// tag::multiple-task-executor[]
+		@Bean("applicationTaskExecutor")
+		SimpleAsyncTaskExecutor applicationTaskExecutor() {
+			return new SimpleAsyncTaskExecutor("spring-mvc-");
+		}
+
+		@Bean("taskExecutor")
+		ThreadPoolTaskExecutor taskExecutor() {
+			ThreadPoolTaskExecutor threadPoolTaskExecutor = new ThreadPoolTaskExecutor();
+			threadPoolTaskExecutor.setThreadNamePrefix("enable-async-");
+			return threadPoolTaskExecutor;
+		}
+		// end::multiple-task-executor[]
+
+	}
+
+}