refactor: unify move interfaces (#2127)

This PR takes both the old and new `Move` interfaces, and merges them
into one.

In order to not require large changes to the existing generic move
selectors,
it also introduces `AbstractSelectorBasedMove`, a non-public extension
of `Move` which allows to deal with move doability. I am adding the
`SelectoBased` prefix to all such move implementations, to distinguish
them in profiling and stack traces from the Neighborhoods-based
equivalents we either already have or will create.

It also makes large changes to the documentation around moves, and
finally exposes Neighborhoods as a documented preview feature.

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/domain/common/ComparatorFactory.java

@@ -7,8 +7,8 @@
 import ai.timefold.solver.core.config.constructionheuristic.ConstructionHeuristicPhaseConfig;
 import ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig;
-import ai.timefold.solver.core.impl.heuristic.move.Move;
 import ai.timefold.solver.core.impl.heuristic.selector.Selector;
+import ai.timefold.solver.core.preview.api.move.Move;
 
 import org.jspecify.annotations.NullMarked;
 

core/src/main/java/ai/timefold/solver/core/api/domain/common/PlanningId.java

@@ -12,7 +12,7 @@
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeProvider;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.api.solver.change.ProblemChange;
-import ai.timefold.solver.core.impl.heuristic.move.Move;
+import ai.timefold.solver.core.preview.api.move.Move;
 
 /**
  * Specifies that a bean property (or a field) is the id to match

core/src/main/java/ai/timefold/solver/core/api/score/analysis/ConstraintAnalysis.java

@@ -5,6 +5,7 @@
 
 import java.util.Comparator;
 import java.util.HashSet;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -14,7 +15,6 @@
 import ai.timefold.solver.core.api.score.constraint.ConstraintRef;
 import ai.timefold.solver.core.api.score.stream.ConstraintJustification;
 import ai.timefold.solver.core.api.solver.SolutionManager;
-import ai.timefold.solver.core.impl.util.CollectionUtils;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -154,8 +154,9 @@ private static int getMatchCount(ConstraintAnalysis<?> analysis, ConstraintAnaly
 
     private static <Score_ extends Score<Score_>> Map<ConstraintJustification, MatchAnalysis<Score_>>
             mapMatchesToJustifications(List<MatchAnalysis<Score_>> matchAnalyses) {
+
         Map<ConstraintJustification, MatchAnalysis<Score_>> matchAnalysisMap =
-                CollectionUtils.newLinkedHashMap(matchAnalyses.size());
+                LinkedHashMap.newLinkedHashMap(matchAnalyses.size());
         for (var matchAnalysis : matchAnalyses) {
             var previous = matchAnalysisMap.put(matchAnalysis.justification(), matchAnalysis);
             if (previous != null) {

core/src/main/java/ai/timefold/solver/core/api/solver/change/ProblemChange.java

@@ -6,7 +6,7 @@
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.api.solver.Solver;
 import ai.timefold.solver.core.api.solver.event.BestSolutionChangedEvent;
-import ai.timefold.solver.core.impl.heuristic.move.Move;
+import ai.timefold.solver.core.preview.api.move.Move;
 
 import org.jspecify.annotations.NullMarked;
 

core/src/main/java/ai/timefold/solver/core/config/solver/EnvironmentMode.java

@@ -9,8 +9,8 @@
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
 import ai.timefold.solver.core.api.domain.variable.ShadowVariable;
 import ai.timefold.solver.core.api.solver.Solver;
-import ai.timefold.solver.core.impl.heuristic.move.Move;
 import ai.timefold.solver.core.impl.score.director.InnerScoreDirector;
+import ai.timefold.solver.core.preview.api.move.Move;
 
 /**
  * The environment mode also allows you to detect common bugs in your implementation.

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/AbstractFlattenNode.java

@@ -12,7 +12,6 @@
 import ai.timefold.solver.core.impl.bavet.common.tuple.Tuple;
 import ai.timefold.solver.core.impl.bavet.common.tuple.TupleLifecycle;
 import ai.timefold.solver.core.impl.bavet.common.tuple.TupleState;
-import ai.timefold.solver.core.impl.util.CollectionUtils;
 
 public abstract class AbstractFlattenNode<InTuple_ extends Tuple, OutTuple_ extends Tuple, FlattenedItem_>
         extends AbstractNode
@@ -124,7 +123,8 @@ private record FlattenBagByItem<FlattenedItem_, OutTuple_>(
         }
 
         FlattenBagByItem(int size) {
-            this(CollectionUtils.newLinkedHashMap(size));
+
+            this(LinkedHashMap.newLinkedHashMap(size));
         }
 
         /**

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/RecordAndReplayPropagator.java

@@ -50,7 +50,7 @@ public RecordAndReplayPropagator(Supplier<BavetPrecomputeBuildHelper<Tuple_>> pr
             UnaryOperator<Tuple_> internalTupleToOutputTupleMapper, TupleLifecycle<Tuple_> nextNodesTupleLifecycle, int size) {
         this.precomputeBuildHelperSupplier = precomputeBuildHelperSupplier;
         this.internalTupleToOutputTupleMapper = internalTupleToOutputTupleMapper;
-        this.objectToOutputTuplesMap = CollectionUtils.newIdentityHashMap(size);
+        this.objectToOutputTuplesMap = new IdentityHashMap<>(size);
 
         // Guesstimate that updates are dominant.
         this.retractQueue = CollectionUtils.newIdentityHashSet(size / 20);

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/decider/ConstructionHeuristicDecider.java

@@ -9,7 +9,8 @@
 import ai.timefold.solver.core.impl.constructionheuristic.scope.ConstructionHeuristicPhaseScope;
 import ai.timefold.solver.core.impl.constructionheuristic.scope.ConstructionHeuristicStepScope;
 import ai.timefold.solver.core.impl.heuristic.move.MoveAdapters;
-import ai.timefold.solver.core.impl.heuristic.move.NoChangeMove;
+import ai.timefold.solver.core.impl.heuristic.move.SelectorBasedNoChangeMove;
+import ai.timefold.solver.core.impl.heuristic.selector.move.generic.SelectorBasedChangeMove;
 import ai.timefold.solver.core.impl.phase.scope.SolverLifecyclePoint;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
 import ai.timefold.solver.core.impl.solver.termination.PhaseTermination;
@@ -130,8 +131,8 @@ public void decideNextStep(ConstructionHeuristicStepScope<Solution_> stepScope,
     }
 
     private static <Solution_> boolean isAllowedNonDoableMove(Move<Solution_> move) {
-        return MoveAdapters.testWhenLegacyMove(move, legacyMove -> legacyMove instanceof NoChangeMove<Solution_>
-                || legacyMove instanceof ai.timefold.solver.core.impl.heuristic.selector.move.generic.ChangeMove<Solution_>);
+        return MoveAdapters.testWhenLegacyMove(move, legacyMove -> legacyMove instanceof SelectorBasedNoChangeMove<Solution_>
+                || legacyMove instanceof SelectorBasedChangeMove<Solution_>);
     }
 
     protected void pickMove(ConstructionHeuristicStepScope<Solution_> stepScope) {

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/Placement.java

@@ -10,12 +10,6 @@
  */
 public class Placement<Solution_> implements Iterable<Move<Solution_>> {
 
-    @SuppressWarnings({ "unchecked", "rawtypes" })
-    public static <Solution_> Iterator<ai.timefold.solver.core.preview.api.move.Move<Solution_>>
-            toNewMoveIterator(Iterator<ai.timefold.solver.core.impl.heuristic.move.Move<Solution_>> legacyIterator) {
-        return (Iterator) legacyIterator;
-    }
-
     private final Iterator<Move<Solution_>> moveIterator;
 
     public Placement(Iterator<Move<Solution_>> moveIterator) {

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/PooledEntityPlacer.java

@@ -3,11 +3,11 @@
 import java.util.Iterator;
 
 import ai.timefold.solver.core.impl.heuristic.HeuristicConfigPolicy;
-import ai.timefold.solver.core.impl.heuristic.move.Move;
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionFilter;
 import ai.timefold.solver.core.impl.heuristic.selector.common.iterator.UpcomingSelectionIterator;
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.move.decorator.FilteringMoveSelector;
+import ai.timefold.solver.core.preview.api.move.Move;
 
 public class PooledEntityPlacer<Solution_> extends AbstractEntityPlacer<Solution_> implements EntityPlacer<Solution_> {
 
@@ -41,7 +41,7 @@ protected Placement<Solution_> createUpcomingSelection() {
             if (!moveIterator.hasNext()) {
                 return noUpcomingSelection();
             }
-            return new Placement<>(Placement.toNewMoveIterator(moveIterator));
+            return new Placement<>(moveIterator);
         }
 
     }