chore: 2.0 migration docs and final API cleanup (#2178)

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/solver/phase/PhaseCommandContext.java

@@ -31,7 +31,7 @@ public interface PhaseCommandContext<Solution_>
     /**
      * Returns the current working solution.
      * It must not be modified directly,
-     * but only through {@link #executeAndCalculateScore(Move)} or {@link #executeTemporarily(Move, Function)}.
+     * but only through {@link #execute(Move)} and other similar methods on this interface.
      * Direct modifications will cause the solver to be in an inconsistent state and likely throw an exception later on.
      *
      * @return the current working solution
@@ -65,30 +65,41 @@ public interface PhaseCommandContext<Solution_>
      */
     <Score_ extends Score<Score_>> Score_ executeAndCalculateScore(Move<Solution_> move);
 
-    /**
-     * As defined by {@link #executeTemporarily(Move, Function, boolean)},
-     * with the guarantee of a fresh score.
-     */
-    default <Result_> @Nullable Result_ executeTemporarily(Move<Solution_> move,
-            Function<Solution_, @Nullable Result_> temporarySolutionConsumer) {
-        return executeTemporarily(move, temporarySolutionConsumer, true);
-    }
-
     /**
      * Executes the given move temporarily and returns the result of the given consumer.
      * The working solution is reverted to its original state after the consumer has been executed,
-     * optionally without recalculating the score for performance reasons.
+     * except for the score, which is not recalculated for performance reasons.
      *
      * @param move the move to execute temporarily
      * @param temporarySolutionConsumer the consumer to execute with the temporarily modified solution;
      *        this solution must not be modified any further.
-     * @param guaranteeFreshScore if true, the score of {@link #getWorkingSolution()} after this method returns
-     *        is guaranteed to be up-to-date;
-     *        otherwise it may be stale as the solver will skip recalculating it for performance reasons.
      * @return the result of the consumer
      */
     <Result_> @Nullable Result_ executeTemporarily(Move<Solution_> move,
-            Function<Solution_, @Nullable Result_> temporarySolutionConsumer, boolean guaranteeFreshScore);
+            Function<Solution_, @Nullable Result_> temporarySolutionConsumer);
+
+    /**
+     * Executes the given move temporarily and returns the score of the temporarily modified solution.
+     * The working solution is reverted to its original state after the consumer has been executed,
+     * except for the score, which is not recalculated for performance reasons.
+     *
+     * @param move the move to execute temporarily
+     * @return the score of the temporarily modified solution after executing the move
+     */
+    <Score_ extends Score<Score_>> Score_ executeTemporarily(Move<Solution_> move);
+
+    /**
+     * As defined by {@link #executeTemporarily(Move)},
+     * with the guarantee of a fresh score at the end of the method's invocation.
+     */
+    <Score_ extends Score<Score_>> Score_ executeTemporarilyAndCalculateScore(Move<Solution_> move);
+
+    /**
+     * As defined by {@link #executeTemporarily(Move, Function)},
+     * with the guarantee of a fresh score at the end of the method's invocation.
+     */
+    <Result_> @Nullable Result_ executeTemporarilyAndCalculateScore(Move<Solution_> move,
+            Function<Solution_, @Nullable Result_> temporarySolutionConsumer);
 
     @Override
     <T> @Nullable T lookUpWorkingObject(@Nullable T problemFactOrPlanningEntity);

core/src/main/java/ai/timefold/solver/core/impl/move/MoveDirector.java

@@ -332,17 +332,18 @@ public final InnerScore<Score_> executeTemporary(Move<Solution_> move) {
         return score;
     }
 
-    public <Result_> Result_ executeTemporary(Move<Solution_> move,
-            TemporaryMovePostprocessor<Solution_, Score_, Result_> postprocessor) {
+    public @Nullable <Result_> Result_ executeTemporary(Move<Solution_> move,
+            TemporaryMovePostprocessor<Solution_, Score_, @Nullable Result_> postprocessor) {
         try (var ephemeralMoveDirector = ephemeral()) {
             ephemeralMoveDirector.execute(move);
             var score = backingScoreDirector.calculateScore();
             return postprocessor.apply(score, ephemeralMoveDirector.createUndoMove());
         }
     }
 
-    public <Result_> @Nullable Result_ executeTemporary(Move<Solution_> move,
-            Function<Solution_, @Nullable Result_> postprocessor, boolean guaranteeFreshScore) {
+    public @Nullable <Result_> Result_ executeTemporary(Move<Solution_> move,
+            Function<Solution_, @Nullable Result_> postprocessor,
+            boolean guaranteeFreshScore) {
         var ephemeralMoveDirector = ephemeral();
         ephemeralMoveDirector.execute(move, true);
         var result = postprocessor.apply(backingScoreDirector.getWorkingSolution());
@@ -451,7 +452,7 @@ public final VariableDescriptorAwareScoreDirector<Solution_> getScoreDirector()
      */
     @FunctionalInterface
     public interface TemporaryMovePostprocessor<Solution_, Score_ extends Score<Score_>, Result_>
-            extends BiFunction<InnerScore<Score_>, Move<Solution_>, Result_> {
+            extends BiFunction<InnerScore<Score_>, Move<Solution_>, @Nullable Result_> {
 
     }
 

core/src/main/java/ai/timefold/solver/core/impl/phase/custom/DefaultPhaseCommandContext.java

@@ -57,8 +57,30 @@ public <Score_ extends Score<Score_>> Score_ executeAndCalculateScore(Move<Solut
 
     @Override
     public @Nullable <Result_> Result_ executeTemporarily(Move<Solution_> move,
-            Function<Solution_, @Nullable Result_> temporarySolutionConsumer, boolean guaranteeFreshScore) {
-        return moveDirector.executeTemporary(move, temporarySolutionConsumer, guaranteeFreshScore);
+            Function<Solution_, @Nullable Result_> temporarySolutionConsumer) {
+        return moveDirector.executeTemporary(move, temporarySolutionConsumer, false);
+    }
+
+    @Override
+    public <Score_ extends Score<Score_>> Score_ executeTemporarily(Move<Solution_> move) {
+        Score_ score = executeTemporarily(move, solution -> moveDirector.getScoreDirector()
+                .getSolutionDescriptor()
+                .getScore(solution));
+        return Objects.requireNonNull(score, () -> "The move (%s) failed to calculate a score.".formatted(move));
+    }
+
+    @Override
+    public @Nullable <Result_> Result_ executeTemporarilyAndCalculateScore(Move<Solution_> move,
+            Function<Solution_, @Nullable Result_> temporarySolutionConsumer) {
+        return moveDirector.executeTemporary(move, temporarySolutionConsumer, true);
+    }
+
+    @Override
+    public <Score_ extends Score<Score_>> Score_ executeTemporarilyAndCalculateScore(Move<Solution_> move) {
+        Score_ score = executeTemporarilyAndCalculateScore(move, solution -> moveDirector.getScoreDirector()
+                .getSolutionDescriptor()
+                .getScore(solution));
+        return Objects.requireNonNull(score, () -> "The move (%s) failed to calculate a score.".formatted(move));
     }
 
 }