feat: add model post processors results to FinalBestSolutionEvent

Author: cristianonicolai

model/definition/src/main/java/ai/timefold/solver/model/definition/api/ModelPostProcessingResult.java

@@ -0,0 +1,8 @@
+package ai.timefold.solver.model.definition.api;
+
+/**
+ * Marker interface for an optional output produced by a {@link ModelPostProcessor} for a completed model run.
+ */
+public interface ModelPostProcessingResult {
+
+}

model/definition/src/main/java/ai/timefold/solver/model/definition/api/ModelPostProcessor.java

@@ -12,6 +12,18 @@ public interface ModelPostProcessor {
      */
     void process(ModelOutput modelOutput, SolverModel<?> solverModel, String id);
 
+    /**
+     * Process a successfully solved model run and optionally return a result to attach to the final best solution event.
+     *
+     * @param solverModel the model with all data taken from the solving
+     * @param id unique identifier of the model
+     * @return the result to attach to the final best solution event, or {@code null} if this post-processor contributes none
+     */
+    default ModelPostProcessingResult processWithResult(ModelOutput modelOutput, SolverModel<?> solverModel, String id) {
+        process(modelOutput, solverModel, id);
+        return null;
+    }
+
     /**
      * Process successfully computed model (not yet solved).
      * <p>

model/definition/src/main/java/ai/timefold/solver/model/definition/internal/events/FinalBestSolutionEvent.java

@@ -1,6 +1,9 @@
 package ai.timefold.solver.model.definition.internal.events;
 
+import java.util.List;
+
 import ai.timefold.solver.core.api.solver.SolverJob;
+import ai.timefold.solver.model.definition.api.ModelPostProcessingResult;
 import ai.timefold.solver.model.definition.api.SolverModel;
 import ai.timefold.solver.model.definition.api.domain.Metadata;
 
@@ -9,8 +12,23 @@
  */
 public final class FinalBestSolutionEvent extends SolverWorkerEvent {
 
+    private final List<ModelPostProcessingResult> postProcessingResults;
+
     public FinalBestSolutionEvent(Metadata metadata, SolverModel model, SolverJob job, String planName, String tenantName) {
+        this(metadata, model, job, planName, tenantName, null);
+    }
+
+    public FinalBestSolutionEvent(Metadata metadata, SolverModel model, SolverJob job, String planName, String tenantName,
+            List<ModelPostProcessingResult> postProcessingResults) {
         super(metadata, model, job, planName, tenantName, null);
+        this.postProcessingResults = postProcessingResults == null ? List.of() : List.copyOf(postProcessingResults);
+    }
+
+    /**
+     * The results contributed by the post-processors for this run, in the order the post-processors ran.
+     */
+    public List<ModelPostProcessingResult> getPostProcessingResults() {
+        return postProcessingResults;
     }
 
 }

model/worker/src/main/java/ai/timefold/solver/model/worker/impl/SolverWorker.java

@@ -5,6 +5,7 @@
 import static ai.timefold.solver.model.definition.internal.platform.EnvironmentVars.ENV_TIMEFOLD_TENANT_NAME;
 
 import java.time.Duration;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
@@ -33,6 +34,7 @@
 import ai.timefold.solver.model.definition.api.ModelConvertorBase;
 import ai.timefold.solver.model.definition.api.ModelInput;
 import ai.timefold.solver.model.definition.api.ModelOutput;
+import ai.timefold.solver.model.definition.api.ModelPostProcessingResult;
 import ai.timefold.solver.model.definition.api.ModelPostProcessor;
 import ai.timefold.solver.model.definition.api.SolverModel;
 import ai.timefold.solver.model.definition.api.SolvingStatus;
@@ -700,10 +702,12 @@ protected void notifyOnComplete(String id, SolverModel solverModel) {
                     extractOutputMetrics(solverModel));
 
             processor.onNext(metadata);
-            sendEvent(finalSolutionEmitter, new FinalBestSolutionEvent(metadata, solverModel,
-                    new SolverWorkerJobState(SolverStatus.NOT_SOLVING, solverJob), planName, tenantName));
 
-            postProcessCompleteOutput(id, modelOutput, solverModel);
+            List<ModelPostProcessingResult> postProcessingResults = postProcessCompleteOutput(id, modelOutput, solverModel);
+
+            sendEvent(finalSolutionEmitter, new FinalBestSolutionEvent(metadata, solverModel,
+                    new SolverWorkerJobState(SolverStatus.NOT_SOLVING, solverJob), planName, tenantName,
+                    postProcessingResults));
 
             sendEvent(scheduleCompletedEmitter, new ItemCompleted(id));
 
@@ -729,15 +733,21 @@ private void postProcessOutput(String id, ModelOutput modelOutput, SolverModel s
         }
     }
 
-    private void postProcessCompleteOutput(String id, ModelOutput modelOutput, SolverModel solverModel) {
+    private List<ModelPostProcessingResult> postProcessCompleteOutput(String id, ModelOutput modelOutput,
+            SolverModel solverModel) {
+        List<ModelPostProcessingResult> results = new ArrayList<>();
         for (ModelPostProcessor processor : modelPostProcessors) {
             try {
-                processor.process(modelOutput, solverModel, id);
+                ModelPostProcessingResult result = processor.processWithResult(modelOutput, solverModel, id);
+                if (result != null) {
+                    results.add(result);
+                }
             } catch (Throwable e) {
                 LOGGER.warn("Unexpected error while invoking post processor {} that returned {}",
                         processor.getClass().getSimpleName(), e.getMessage());
             }
         }
+        return results;
     }
 
     private void storeSolvedInput(String datasetId, ModelOutput modelOutput) {