From 4610bdac9415068db5c92417731de3045f1a19a4 Mon Sep 17 00:00:00 2001
From: Mahmoud Ben Hassine <mbenhassine@vmware.com>
Date: Wed, 15 Nov 2023 11:44:01 +0100
Subject: [PATCH] Clarify documentation about throttling deprecation

Resolves #4389

(cherry picked from commit 6ba7c639a42a1b1ac1d8142f459c7fcf70965636)
---
 .../builder/AbstractTaskletStepBuilder.java   |  6 ++---
 .../src/main/asciidoc/scalability.adoc        | 23 +++++++++++++++++++
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/spring-batch-core/src/main/java/org/springframework/batch/core/step/builder/AbstractTaskletStepBuilder.java b/spring-batch-core/src/main/java/org/springframework/batch/core/step/builder/AbstractTaskletStepBuilder.java
index 8ab4fb2a1..495f65425 100644
--- a/spring-batch-core/src/main/java/org/springframework/batch/core/step/builder/AbstractTaskletStepBuilder.java
+++ b/spring-batch-core/src/main/java/org/springframework/batch/core/step/builder/AbstractTaskletStepBuilder.java
@@ -199,9 +199,9 @@ public abstract class AbstractTaskletStepBuilder<B extends AbstractTaskletStepBu
 	 * in the job repository for this step.
 	 * @param throttleLimit maximum number of concurrent tasklet executions allowed
 	 * @return this for fluent chaining
-	 * @deprecated since 5.0, scheduled for removal in 6.0. Use a pooled
-	 * {@link TaskExecutor} implementation with a limited capacity of its task queue
-	 * instead.
+	 * @deprecated with no replacement since 5.0, scheduled for removal in 6.0. Use a custom
+	 * {@link RepeatOperations} implementation (based on a {@link TaskExecutor} with a bounded
+	 * task queue) and set it on the step with {@link #stepOperations(RepeatOperations)}.
 	 */
 	@Deprecated(since = "5.0", forRemoval = true)
 	public B throttleLimit(int throttleLimit) {
diff --git a/spring-batch-docs/src/main/asciidoc/scalability.adoc b/spring-batch-docs/src/main/asciidoc/scalability.adoc
index 4a387f8e5..fc7dfa588 100644
--- a/spring-batch-docs/src/main/asciidoc/scalability.adoc
+++ b/spring-batch-docs/src/main/asciidoc/scalability.adoc
@@ -121,6 +121,29 @@ Note also that there may be limits placed on concurrency by any pooled resources
 your step, such as a `DataSource`. Be sure to make the pool in those resources at least
 as large as the desired number of concurrent threads in the step.
 
+[WARNING]
+.Throttle limit deprecation
+====
+As of v5.0, the throttle limit is deprecated with no replacement. If you want to replace the
+current throttling mechanism in the default `TaskExecutorRepeatTemplate`, you need to provide
+a custom `RepeatOperations` implementation (based on a `TaskExecutor` with a bounded task queue)
+and set it on the step with `StepBuilder#stepOperations`:
+
+.Java Configuration
+[source, java]
+----
+@Bean
+public Step sampleStep(RepeatOperations customRepeatOperations, JobRepository jobRepository, PlatformTransactionManager transactionManager) {
+	return new StepBuilder("sampleStep", jobRepository)
+				.<String, String>chunk(10, transactionManager)
+				.reader(itemReader())
+				.writer(itemWriter())
+				.stepOperations(customRepeatOperations)
+				.build();
+}
+----
+====
+
 There are some practical limitations of using multi-threaded `Step` implementations for
 some common batch use cases. Many participants in a `Step` (such as readers and writers)
 are stateful. If the state is not segregated by thread, those components are not