refactor: remove deprecated methods from ScoreDirector

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/score/director/ScoreDirector.java

@@ -5,7 +5,7 @@
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.api.solver.change.ProblemChange;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -14,6 +14,7 @@
  *
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
  */
+@NullMarked
 public interface ScoreDirector<Solution_> {
 
     /**
@@ -22,7 +23,6 @@ public interface ScoreDirector<Solution_> {
      * Because a {@link Score} is best calculated incrementally (by deltas),
      * the {@link ScoreDirector} needs to be notified when its {@link PlanningSolution working solution} changes.
      */
-    @NonNull
     Solution_ getWorkingSolution();
 
     void beforeVariableChanged(Object entity, String variableName);
@@ -43,96 +43,6 @@ public interface ScoreDirector<Solution_> {
 
     void triggerVariableListeners();
 
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void beforeEntityAdded(Object entity) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void afterEntityAdded(Object entity) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void beforeEntityRemoved(Object entity) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void afterEntityRemoved(Object entity) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void beforeProblemFactAdded(Object problemFact) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void afterProblemFactAdded(Object problemFact) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void beforeProblemPropertyChanged(Object problemFactOrEntity) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void afterProblemPropertyChanged(Object problemFactOrEntity) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void beforeProblemFactRemoved(Object problemFact) {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * @deprecated Calling this method by user code is not recommended and will lead to unforeseen consequences.
-     *             Use {@link ProblemChange} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.8.0")
-    default void afterProblemFactRemoved(Object problemFact) {
-        throw new UnsupportedOperationException();
-    }
-
     /**
      * Translates an entity or fact instance (often from another {@link Thread} or JVM)
      * to this {@link ScoreDirector}'s internal working instance.

core/src/main/java/ai/timefold/solver/core/impl/domain/solution/cloner/gizmo/GizmoCloningUtils.java

@@ -46,7 +46,7 @@ public static Set<Class<?>> getDeepClonedClasses(SolutionDescriptor<?> solutionD
                     }
                 }
 
-                // Ignore Collections, Maps, and PlanningCloneables, as there is collection/map/clonable logic to clone them.
+                // Ignore Collections and Maps, as there is collection/map/clonable logic to clone them.
                 if (DeepCloningUtils.isFieldDeepCloned(solutionDescriptor, field, clazz)
                         && !Collection.class.isAssignableFrom(field.getType())
                         && !Map.class.isAssignableFrom(field.getType())

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/ShadowVariableUpdateHelper.java

@@ -317,6 +317,7 @@ public InternalScoreDirectorFactory(SolutionDescriptor<Solution_> solutionDescri
         }
     }
 
+    @NullMarked
     private static class InternalScoreDirector<Solution_, Score_ extends Score<Score_>>
             extends AbstractScoreDirector<Solution_, Score_, InternalScoreDirectorFactory<Solution_, Score_>> {
 

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

@@ -11,6 +11,7 @@
 
 import org.jspecify.annotations.NullMarked;
 
+@NullMarked
 final class MoveTesterScoreDirector<Solution_, Score_ extends Score<Score_>>
         extends AbstractScoreDirector<Solution_, Score_, MoveTesterScoreDirectorFactory<Solution_, Score_>> {
 

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

@@ -17,12 +17,14 @@
 import ai.timefold.solver.core.impl.score.director.ValueRangeManager;
 import ai.timefold.solver.core.impl.score.director.VariableDescriptorCache;
 
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
+@NullMarked
 public final class VariableChangeRecordingScoreDirector<Solution_, Score_ extends Score<Score_>>
         implements RevertableScoreDirector<Solution_> {
 
-    private final InnerScoreDirector<Solution_, Score_> backingScoreDirector;
+    private final @Nullable InnerScoreDirector<Solution_, Score_> backingScoreDirector;
     private final List<ChangeAction<Solution_>> variableChanges;
 
     /*
@@ -42,7 +44,7 @@ public final class VariableChangeRecordingScoreDirector<Solution_, Score_ extend
      *
      * This map exists to ensure that this is the case.
      */
-    private final Map<Object, Integer> cache;
+    private final @Nullable Map<Object, Integer> cache;
 
     public VariableChangeRecordingScoreDirector(ScoreDirector<Solution_> backingScoreDirector) {
         this(backingScoreDirector, true);
@@ -56,8 +58,8 @@ public VariableChangeRecordingScoreDirector(ScoreDirector<Solution_> backingScor
         this.variableChanges = new LinkedList<>();
     }
 
-    private VariableChangeRecordingScoreDirector(InnerScoreDirector<Solution_, Score_> backingScoreDirector,
-            List<ChangeAction<Solution_>> variableChanges, Map<Object, Integer> cache) {
+    private VariableChangeRecordingScoreDirector(@Nullable InnerScoreDirector<Solution_, Score_> backingScoreDirector,
+            List<ChangeAction<Solution_>> variableChanges, @Nullable Map<Object, Integer> cache) {
         this.backingScoreDirector = backingScoreDirector;
         this.variableChanges = variableChanges;
         this.cache = cache;
@@ -178,13 +180,13 @@ public SolutionDescriptor<Solution_> getSolutionDescriptor() {
 
     @Override
     public ValueRangeManager<Solution_> getValueRangeManager() {
-        return getBacking().getValueRangeManager();
+        return Objects.requireNonNull(getBacking()).getValueRangeManager();
     }
 
     /**
      * Returns the score director to which events are delegated.
      */
-    public InnerScoreDirector<Solution_, Score_> getBacking() {
+    public @Nullable InnerScoreDirector<Solution_, Score_> getBacking() {
         return backingScoreDirector;
     }
 
@@ -217,12 +219,12 @@ public void triggerVariableListeners() {
     }
 
     @Override
-    public <E> E lookUpWorkingObject(E externalObject) {
+    public <E> @Nullable E lookUpWorkingObject(@Nullable E externalObject) {
         return Objects.requireNonNull(backingScoreDirector).lookUpWorkingObject(externalObject);
     }
 
     @Override
-    public <E> @Nullable E lookUpWorkingObjectOrReturnNull(E externalObject) {
+    public <E> @Nullable E lookUpWorkingObjectOrReturnNull(@Nullable E externalObject) {
         return Objects.requireNonNull(backingScoreDirector).lookUpWorkingObjectOrReturnNull(externalObject);
     }
 

core/src/main/java/ai/timefold/solver/core/impl/score/director/AbstractScoreDirector.java

@@ -48,7 +48,6 @@
 import ai.timefold.solver.core.preview.api.move.Move;
 import ai.timefold.solver.core.preview.api.move.SolutionView;
 
-import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
@@ -65,8 +64,9 @@
  * <li>after* method: first statement should be a call to the super method</li>
  * </ul>
  */
+@NullMarked
 public abstract class AbstractScoreDirector<Solution_, Score_ extends Score<Score_>, Factory_ extends AbstractScoreDirectorFactory<Solution_, Score_, Factory_>>
-        implements InnerScoreDirector<Solution_, Score_>, Cloneable {
+        implements InnerScoreDirector<Solution_, Score_> {
 
     private static final int CONSTRAINT_MATCH_DISPLAY_LIMIT = 8;
     protected final Logger logger = LoggerFactory.getLogger(getClass());
@@ -79,7 +79,7 @@ public abstract class AbstractScoreDirector<Solution_, Score_ extends Score<Scor
      */
     private final NeighborhoodNotifier<Solution_> neighborhoodsElementUpdateNotifier;
     private final boolean lookUpEnabled;
-    private final LookUpManager lookUpManager;
+    private final @Nullable LookUpManager lookUpManager;
     protected final ConstraintMatchPolicy constraintMatchPolicy;
     private boolean expectShadowVariablesInCorrectState;
     private final VariableDescriptorCache<Solution_> variableDescriptorCache;
@@ -93,14 +93,14 @@ public abstract class AbstractScoreDirector<Solution_, Score_ extends Score<Scor
      * and operations which do not perform moves do not require them.
      */
     private final ValueRangeManager<Solution_> valueRangeManager;
-    private final ListVariableStateSupply<Solution_, Object, Object> listVariableStateSupply; // Null when no list variable.
+    private final @Nullable ListVariableStateSupply<Solution_, Object, Object> listVariableStateSupply; // Null when no list variable.
     private final MoveDirector<Solution_, Score_> moveDirector = new MoveDirector<>(this);
 
     private long workingEntityListRevision = 0L;
     private int workingGenuineEntityCount = 0;
     private boolean allChangesWillBeUndoneBeforeStepEnds = false;
     private long calculationCount = 0L;
-    protected Solution_ workingSolution;
+    protected @Nullable Solution_ workingSolution;
     private int workingInitScore = 0;
 
     private final boolean isStepAssertOrMore;
@@ -178,7 +178,7 @@ public boolean expectShadowVariablesInCorrectState() {
     }
 
     @Override
-    public @NonNull Solution_ getWorkingSolution() {
+    public Solution_ getWorkingSolution() {
         return workingSolution;
     }
 
@@ -251,7 +251,8 @@ public NeighborhoodNotifier<Solution_> getNeighborhoodNotifier() {
      * @param workingSolution the working solution to set
      * @param entityAndFactVisitor maybe null; a function to apply to all problem facts and problem entities
      */
-    protected void setWorkingSolutionWithoutUpdatingShadows(Solution_ workingSolution, Consumer<Object> entityAndFactVisitor) {
+    protected void setWorkingSolutionWithoutUpdatingShadows(Solution_ workingSolution,
+            @Nullable Consumer<Object> entityAndFactVisitor) {
         this.workingSolution = requireNonNull(workingSolution);
         var solutionDescriptor = getSolutionDescriptor();
 
@@ -443,15 +444,6 @@ protected void setCalculatedScore(Score_ score) {
         calculationCount++;
     }
 
-    /**
-     * @deprecated Unused, but kept for backward compatibility.
-     */
-    @Deprecated(forRemoval = true, since = "1.14.0")
-    @Override
-    public AbstractScoreDirector<Solution_, Score_, Factory_> clone() {
-        throw new UnsupportedOperationException("Cloning score directors is not supported.");
-    }
-
     @Override
     public InnerScoreDirector<Solution_, Score_> createChildThreadScoreDirector(ChildThreadType childThreadType) {
         // Most score directors don't need derived status; CS will override this.
@@ -885,7 +877,7 @@ private void assertValueRangeForListVariable(Object entity, List<Object> valueLi
     }
 
     private static <Solution_> void assertValueRangeForBasicVariables(InnerScoreDirector<Solution_, ?> scoreDirector,
-            List<BasicVariableDescriptor<Solution_>> basicVariableDescriptorList, Object entity) {
+            @Nullable List<BasicVariableDescriptor<Solution_>> basicVariableDescriptorList, Object entity) {
         if (basicVariableDescriptorList == null || basicVariableDescriptorList.isEmpty()) {
             return;
         }
@@ -905,7 +897,7 @@ private static <Solution_> void assertValueRangeForBasicVariables(InnerScoreDire
     }
 
     private static <Solution_> void assertValueRangeForListVariable(InnerScoreDirector<Solution_, ?> scoreDirector,
-            ListVariableDescriptor<Solution_> variableDescriptor, Object entity, List<Object> valueList) {
+            ListVariableDescriptor<Solution_> variableDescriptor, Object entity, List<@Nullable Object> valueList) {
         if (valueList.isEmpty()) {
             return;
         }
@@ -923,36 +915,6 @@ private static <Solution_> void assertValueRangeForListVariable(InnerScoreDirect
         }
     }
 
-    public SolutionTracker.SolutionCorruptionResult getSolutionCorruptionAfterUndo(Move<Solution_> move,
-            InnerScore<Score_> undoInnerScore) {
-        var trackingWorkingSolution = solutionTracker != null;
-        if (trackingWorkingSolution) {
-            solutionTracker.setAfterUndoSolution(workingSolution);
-        }
-        // Precondition: assert that there are probably no corrupted constraints
-        var undoMoveToString = "Undo(%s)".formatted(move);
-        assertWorkingScoreFromScratch(undoInnerScore, undoMoveToString);
-        // Precondition: assert that shadow variables aren't stale after doing the undoMove
-        assertShadowVariablesAreNotStale(undoInnerScore, undoMoveToString);
-        if (trackingWorkingSolution) {
-            // Recalculate all shadow variables from scratch.
-            // We cannot set all shadow variables to null, since some variable listeners
-            // may expect them to be non-null.
-            // Instead, we just simulate a change to all genuine variables.
-            variableListenerSupport.forceTriggerAllVariableListeners(workingSolution);
-            solutionTracker.setUndoFromScratchSolution(workingSolution);
-
-            // Also calculate from scratch for the before solution, since it might
-            // have been corrupted but was only detected now
-            solutionTracker.restoreBeforeSolution();
-            variableListenerSupport.forceTriggerAllVariableListeners(workingSolution);
-            solutionTracker.setBeforeFromScratchSolution(workingSolution);
-
-            return solutionTracker.buildSolutionCorruptionResult();
-        }
-        return SolutionTracker.SolutionCorruptionResult.untracked();
-    }
-
     /**
      * @param uncorruptedScoreDirector never null
      * @param predicted true if the score was predicted and might have been calculated on another thread
@@ -1028,11 +990,15 @@ Maybe there is a bug in the score constraints of those ConstraintMatch(s).
     }
 
     private static <Score_ extends Score<Score_>> List<MatchAnalysis<Score_>>
-            emptyMatchAnalysisIfNull(ConstraintAnalysis<Score_> constraintAnalysis) {
+            emptyMatchAnalysisIfNull(@Nullable ConstraintAnalysis<Score_> constraintAnalysis) {
         if (constraintAnalysis == null) {
             return Collections.emptyList();
         }
-        return Objects.requireNonNullElse(constraintAnalysis.matches(), Collections.emptyList());
+        var matches = constraintAnalysis.matches();
+        if (matches == null) {
+            return Collections.emptyList();
+        }
+        return matches;
     }
 
     private void appendAnalysis(StringBuilder analysis, String workingLabel, String suffix,

core/src/main/java/ai/timefold/solver/core/impl/score/director/InnerScoreDirector.java

@@ -41,12 +41,14 @@
 import ai.timefold.solver.core.preview.api.move.Move;
 import ai.timefold.solver.core.preview.api.move.SolutionView;
 
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
  * @param <Score_> the score type to go with the solution
  */
+@NullMarked
 public interface InnerScoreDirector<Solution_, Score_ extends Score<Score_>>
         extends VariableDescriptorAwareScoreDirector<Solution_>, AutoCloseable {
 

core/src/main/java/ai/timefold/solver/core/impl/score/director/RevertableScoreDirector.java

@@ -2,6 +2,9 @@
 
 import java.util.List;
 
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
 public interface RevertableScoreDirector<Solution_> extends VariableDescriptorAwareScoreDirector<Solution_> {
 
     /**