docs: migrate to new event consumers (#1919)

Author: triceo

docs/src/modules/ROOT/pages/enterprise-edition/enterprise-edition.adoc

@@ -982,12 +982,12 @@ It is not available in the Community Edition.
 This feature helps you avoid overloading your system with best solution events,
 especially in the early phase of the solving process when the solver is typically improving the solution very rapidly.
 
-To enable event throttling, use `ThrottlingBestSolutionConsumer` when starting a new `SolverJob` using `SolverManager`:
+To enable event throttling, use `ThrottlingBestSolutionEventConsumer` when starting a new `SolverJob` using `SolverManager`:
 
 [source,java,options="nowrap"]
 ----
 ...
-import ai.timefold.solver.enterprise.core.api.ThrottlingBestSolutionConsumer;
+import ai.timefold.solver.enterprise.core.api.ThrottlingBestSolutionEventConsumer;
 import java.time.Duration;
 ...
 
@@ -996,8 +996,8 @@ public class TimetableService {
     private SolverManager<Timetable, Long> solverManager;
 
     public String solve(Timetable problem) {
-        Consumer<Timetable> bestSolutionConsumer = ThrottlingBestSolutionConsumer.of(
-            solution -> {
+        var bestSolutionEventConsumer = ThrottlingBestSolutionEventConsumer.of(
+            event -> {
                // Your custom event handling code goes here.
             },
             Duration.ofSeconds(1)); // Throttle to 1 event per second.
@@ -1006,7 +1006,7 @@ public class TimetableService {
         solverManager.solveBuilder()
                 .withProblemId(jobId)
                 .withProblem(problem)
-                .withBestSolutionConsumer(bestSolutionConsumer)
+                .withBestSolutionEventConsumer(bestSolutionEventConsumer)
                 .run(); // Start the solver job and listen to best solutions, with throttling.
         return jobId;
     }
@@ -1026,7 +1026,7 @@ event delivery will be delayed until a thread can be started.
 
 [NOTE]
 ====
-If you are using the `ThrottlingBestSolutionConsumer` for intermediate best solutions
+If you are using the `ThrottlingBestSolutionEventConsumer` for intermediate best solutions
 together with a final best solution consumer,
 both these consumers will receive the final best solution.
 ====

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-to-latest-version.adoc

@@ -64,8 +64,26 @@ We kindly ask Kotlin users to translate the changes accordingly.
 .icon:exclamation-triangle[role=red] `SolverJobBuilder` `with...SolutionConsumer` methods deprecated.
 [%collapsible%open]
 ====
-The `SolverJobBuilder` 's `withBestSolutionConsumer`, `withFinalBestSolutionConsumer`, `withFirstInitializedSolutionConsumer` and `withSolverJobStartedConsumer` methods have been deprecated in favor of the new methods `withBestSolutionEventConsumer`, `withFinalBestSolutionEventConsumer`, `withFirstInitializedSolutionEventConsumer`, and `withSolverJobStartedEventConsumer` respectively.
-The new `with...EventConsumer` methods accept their own `...Event` object, with methods to access the best solution and different additional properties depending on the event.
+Some `SolverJobBuilder` 's methods for consuming solution-related events have been deprecated in favor of new methods that provide more context through event objects:
+
+
+|===
+|1.27.0 and older |1.28.0 and newer
+
+|`withBestSolutionConsumer`
+|`withBestSolutionEventConsumer`
+
+|`withFinalBestSolutionConsumer`
+|`withFinalBestSolutionEventConsumer`
+
+|`withFirstInitializedSolutionConsumer`
+|`withFirstInitializedSolutionEventConsumer`
+
+|`withSolverJobStartedConsumer`
+|`withSolverJobStartedEventConsumer`
+|===
+
+
 To migrate, change your `Consumer` to accept the event instead of the solution:
 
 Before in `*.java`:
@@ -139,8 +157,13 @@ void onFinalBestSolution(FinalBestSolutionEvent<Timetable> event) {
     // ...
 }
 ----
+
+Users of xref:enterprise-edition/enterprise-edition.adoc#throttlingBestSolutionEvents[solution throttling] should also update their code
+to use `ThrottlingBestSolutionEventConsumer` instead of the now deprecated `ThrottlingBestSolutionConsumer`.
 ====
 
+'''
+
 .icon:info-circle[role=yellow] `SelectionSorterWeightFactory` deprecated for removal
 [%collapsible%open]
 ====
@@ -150,6 +173,8 @@ ensuring all related settings are consistent and simpler.
 The old class remains valid and can be easily converted to use the `ComparatorFactory` instead.
 ====
 
+'''
+
 .icon:info-circle[role=yellow] `flattenLast` behaviour on `equals` objects
 [%collapsible%open]
 ====

docs/src/modules/ROOT/pages/using-timefold-solver/running-the-solver.adoc

@@ -720,29 +720,30 @@ Java::
 solverManager.solveBuilder()
         .withProblemId(problemId)
         .withProblem(problem)
-        .withFirstInitializedSolutionConsumer(firstInitializedSolutionConsumer)
-        .withBestSolutionConsumer(bestSolutionConsumer)
-        .withFinalBestSolutionConsumer(finalBestSolutionConsumer)
+        .withFirstInitializedSolutionEventConsumer(firstInitializedSolutionEventConsumer)
+        .withBestSolutionEventConsumer(bestSolutionEventConsumer)
+        .withFinalBestSolutionEventConsumer(finalBestSolutionEventConsumer)
         .withExceptionHandler(exceptionHandler)
         .withConfigOverride(configOverride)
 ...
 ----
 ====
 
-A consumer for the first initialized solution can be configured with `withFirstInitializedSolutionConsumer(...)`.
+A consumer for the first initialized solution can be configured with `withFirstInitializedSolutionEventConsumer(...)`.
 The solution is returned by the last phase that immediately precedes the first local search phase.
 
 Whenever a new best solution is generated by the solver,
-it can be consumed by configuring it with `withBestSolutionConsumer(...)`.
+it can be consumed by configuring it with `withBestSolutionEventConsumer(...)`.
 The final best solution consumer,
 which is called at the end of the solving process,
-can be set using `withFinalBestSolutionConsumer(...)`.
+can be set using `withFinalBestSolutionEventConsumer(...)`.
 Additionally,
 an improved solution consumer capable of throttling events is available in the xref:enterprise-edition/enterprise-edition.adoc#throttlingBestSolutionEvents[Enterprise Edition].
 
 [WARNING]
 ====
-Do not modify the solutions returned by the events in `withFirstInitializedSolutionConsumer(...)` and `withBestSolutionConsumer(...)`. These instances are still utilized during the solving process, and any modifications may lead to solver corruption.
+Do not modify the solutions returned by the events in `withFirstInitializedSolutionEventConsumer(...)` and `withBestSolutionEventConsumer(...)`.
+These instances are still utilized during the solving process, and any modifications may lead to solver corruption.
 ====
 
 To handle errors that may arise during the solving process,