refactor: remove all leftover deprecations

Author: triceo

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

@@ -0,0 +1,32 @@
+package ai.timefold.solver.core.api.domain.common;
+
+import ai.timefold.solver.core.api.solver.change.ProblemChange;
+import ai.timefold.solver.core.preview.api.move.Move;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Allows to transfer an entity or fact instance (often from another {@link Thread})
+ * to another working solution.
+ */
+public interface Lookup {
+
+    /**
+     * Translates an entity or fact instance (often from another {@link Thread})
+     * to another working solution.
+     * Useful for {@link Move#rebase(Lookup) move rebasing}
+     * and in a {@link ProblemChange} and for multi-threaded solving.
+     * <p>
+     * Matching uses {@link PlanningId}.
+     *
+     * @param problemFactOrPlanningEntity The fact or entity to rebase.
+     * @return null if problemFactOrPlanningEntity is null
+     * @throws IllegalArgumentException if there is no working object for the fact or entity,
+     *         if it cannot be looked up,
+     *         or if its class is not supported.
+     * @throws IllegalStateException if it cannot be looked up
+     * @param <T> the object type
+     */
+    <T> @Nullable T lookUpWorkingObject(@Nullable T problemFactOrPlanningEntity);
+
+}

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

@@ -12,11 +12,10 @@
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeProvider;
 import ai.timefold.solver.core.api.solver.change.ProblemChange;
 import ai.timefold.solver.core.preview.api.move.Move;
-import ai.timefold.solver.core.preview.api.move.Rebaser;
 
 /**
  * Specifies that a bean property (or a field) is the id to match
- * when {@link Rebaser#rebase(Object) locating}
+ * when {@link Lookup#lookUpWorkingObject(Object) looking up}
  * an externalObject (often from another {@link Thread} or JVM).
  * Used during {@link Move} rebasing and in a {@link ProblemChange}.
  * <p>

core/src/main/java/ai/timefold/solver/core/api/domain/solution/PlanningEntityProperty.java

@@ -13,7 +13,7 @@
  * Specifies that a property (or a field) on a {@link PlanningSolution} class is a planning entity.
  * <p>
  * The planning entity should have the {@link PlanningEntity} annotation.
- * The planning entity will be added registered with the solver.
+ * The planning entity will be registered with the solver.
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)

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

@@ -1,16 +1,14 @@
 package ai.timefold.solver.core.api.solver.change;
 
-import java.util.Optional;
 import java.util.function.Consumer;
 
-import ai.timefold.solver.core.api.domain.common.PlanningId;
+import ai.timefold.solver.core.api.domain.common.Lookup;
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariable;
 import ai.timefold.solver.core.api.domain.variable.ShadowVariable;
 
 import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
 
 /**
  * Allows external changes to the {@link PlanningSolution working solution}. If the changes are not applied through
@@ -19,9 +17,12 @@
  * never notified about them, resulting to inconsistencies in the {@link PlanningSolution working solution}.
  * Should be used only from a {@link ProblemChange} implementation.
  * To see an example implementation, please refer to the {@link ProblemChange} Javadoc.
+ *
+ * @see Lookup You may need to perform lookups of working objects from external objects.
  */
 @NullMarked
-public interface ProblemChangeDirector {
+public interface ProblemChangeDirector
+        extends Lookup {
 
     /**
      * Add a new {@link PlanningEntity} instance into the {@link PlanningSolution working solution}.
@@ -35,7 +36,7 @@ public interface ProblemChangeDirector {
     /**
      * Remove an existing {@link PlanningEntity} instance from the {@link PlanningSolution working solution}.
      * Translates the entity to a working planning entity by performing a lookup as defined by
-     * {@link #lookUpWorkingObjectOrFail(Object)}.
+     * {@link #lookUpWorkingObject(Object)}.
      *
      * @param entity the {@link PlanningEntity} instance
      * @param entityConsumer removes the working entity from the {@link PlanningSolution working solution}
@@ -45,7 +46,7 @@ public interface ProblemChangeDirector {
 
     /**
      * Change a {@link PlanningVariable} value of a {@link PlanningEntity}. Translates the entity to a working
-     * planning entity by performing a lookup as defined by {@link #lookUpWorkingObjectOrFail(Object)}.
+     * planning entity by performing a lookup as defined by {@link #lookUpWorkingObject(Object)}.
      *
      * @param entity the {@link PlanningEntity} instance
      * @param variableName name of the {@link PlanningVariable}
@@ -66,7 +67,7 @@ public interface ProblemChangeDirector {
 
     /**
      * Remove an existing problem fact from the {@link PlanningSolution working solution}. Translates the problem fact
-     * to a working problem fact by performing a lookup as defined by {@link #lookUpWorkingObjectOrFail(Object)}.
+     * to a working problem fact by performing a lookup as defined by {@link #lookUpWorkingObject(Object)}.
      *
      * @param problemFact the problem fact instance
      * @param problemFactConsumer removes the working problem fact from the
@@ -78,7 +79,7 @@ public interface ProblemChangeDirector {
     /**
      * Change a property of either a {@link PlanningEntity} or a problem fact. Translates the entity or the problem fact
      * to its {@link PlanningSolution working solution} counterpart by performing a lookup as defined by
-     * {@link #lookUpWorkingObjectOrFail(Object)}.
+     * {@link #lookUpWorkingObject(Object)}.
      *
      * @param problemFactOrEntity the {@link PlanningEntity} or the problem fact instance
      * @param problemFactOrEntityConsumer updates the property of the {@link PlanningEntity}
@@ -88,32 +89,6 @@ public interface ProblemChangeDirector {
     <EntityOrProblemFact> void changeProblemProperty(EntityOrProblemFact problemFactOrEntity,
             Consumer<EntityOrProblemFact> problemFactOrEntityConsumer);
 
-    /**
-     * Translate an entity or fact instance (often from another {@link Thread} or JVM)
-     * to this {@link ProblemChangeDirector}'s internal working instance.
-     * <p>
-     * Matching uses {@link PlanningId}.
-     *
-     * @return null if externalObject is null
-     * @throws IllegalArgumentException if there is no workingObject for externalObject, if it cannot be looked up
-     *         or if the externalObject's class is not supported
-     * @throws IllegalStateException if it cannot be looked up
-     * @param <EntityOrProblemFact> the object type
-     */
-    <EntityOrProblemFact> @Nullable EntityOrProblemFact lookUpWorkingObjectOrFail(@Nullable EntityOrProblemFact externalObject);
-
-    /**
-     * As defined by {@link #lookUpWorkingObjectOrFail(Object)},
-     * but doesn't fail fast if no workingObject was ever added for the externalObject.
-     * It's recommended to use {@link #lookUpWorkingObjectOrFail(Object)} instead.
-     *
-     * @return {@link Optional#empty()} if there is no workingObject for externalObject, or if externalObject is null
-     * @throws IllegalArgumentException if it cannot be looked up or if the externalObject's class is not supported
-     * @throws IllegalStateException if it cannot be looked up
-     * @param <EntityOrProblemFact> the object type
-     */
-    <EntityOrProblemFact> Optional<EntityOrProblemFact> lookUpWorkingObject(@Nullable EntityOrProblemFact externalObject);
-
     /**
      * Calls variable listeners on the external changes submitted so far.
      *

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

@@ -20,7 +20,7 @@ public interface PhaseCommand<Solution_> {
     /**
      * Changes the current {@link PhaseCommandContext#getWorkingSolution() working solution}.
      * The solver is notified of the changes through {@link PhaseCommandContext},
-     * specifically through {@link PhaseCommandContext#execute(Move)}.
+     * specifically through {@link PhaseCommandContext#executeAndCalculateScore(Move)}.
      * Any other modifications to the working solution are strictly forbidden
      * and will likely cause the solver to be in an inconsistent state and throw an exception later on.
      * <p>

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

@@ -2,9 +2,10 @@
 
 import java.util.function.Function;
 
+import ai.timefold.solver.core.api.domain.common.Lookup;
+import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.preview.api.domain.metamodel.PlanningSolutionMetaModel;
 import ai.timefold.solver.core.preview.api.move.Move;
-import ai.timefold.solver.core.preview.api.move.Rebaser;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -17,7 +18,8 @@
  * @see PhaseCommand
  */
 @NullMarked
-public interface PhaseCommandContext<Solution_> {
+public interface PhaseCommandContext<Solution_>
+        extends Lookup {
 
     /**
      * Returns the meta-model of the {@link #getWorkingSolution() working solution}.
@@ -29,7 +31,7 @@ public interface PhaseCommandContext<Solution_> {
     /**
      * Returns the current working solution.
      * It must not be modified directly,
-     * but only through {@link #execute(Move)} or {@link #executeTemporarily(Move, Function)}.
+     * but only through {@link #executeAndCalculateScore(Move)} or {@link #executeTemporarily(Move, Function)}.
      * Direct modifications will cause the solver to be in an inconsistent state and likely throw an exception later on.
      *
      * @return the current working solution
@@ -47,23 +49,21 @@ public interface PhaseCommandContext<Solution_> {
     boolean isPhaseTerminated();
 
     /**
-     * As defined by {@link #execute(Move, boolean)},
-     * but with the guarantee of a fresh score.
+     * Executes the given move and updates the working solution
+     * without recalculating the score for performance reasons.
+     *
+     * @param move the move to execute
      */
-    default void execute(Move<Solution_> move) {
-        execute(move, true);
-    }
+    void execute(Move<Solution_> move);
 
     /**
      * Executes the given move and updates the working solution,
-     * optionally without recalculating the score for performance reasons.
+     * and returns the new score of the working solution.
      *
      * @param move the move to execute
-     * @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 new score of the working solution after executing the move
      */
-    void execute(Move<Solution_> move, boolean guaranteeFreshScore);
+    <Score_ extends Score<Score_>> Score_ executeAndCalculateScore(Move<Solution_> move);
 
     /**
      * As defined by {@link #executeTemporarily(Move, Function, boolean)},
@@ -90,9 +90,7 @@ default void execute(Move<Solution_> move) {
     <Result_> @Nullable Result_ executeTemporarily(Move<Solution_> move,
             Function<Solution_, @Nullable Result_> temporarySolutionConsumer, boolean guaranteeFreshScore);
 
-    /**
-     * As defined by {@link Rebaser#rebase(Object)}, but for the working solution of this context.
-     */
-    <T> @Nullable T lookupWorkingObject(@Nullable T original);
+    @Override
+    <T> @Nullable T lookUpWorkingObject(@Nullable T problemFactOrPlanningEntity);
 
 }

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

@@ -1,6 +1,6 @@
 package ai.timefold.solver.core.impl.bavet.common;
 
-import static ai.timefold.solver.core.impl.bavet.common.ConstraintNodeProfileId.*;
+import static ai.timefold.solver.core.impl.bavet.common.ConstraintNodeProfileId.Qualifier;
 
 import java.util.ArrayDeque;
 import java.util.ArrayList;
@@ -64,7 +64,7 @@ public void addNode(AbstractNode node, Stream_ creator) {
         addNode(node, creator, creator);
     }
 
-    public void addNode(AbstractNode node, Stream_ creator, Stream_ parent) {
+    public void addNode(AbstractNode node, Stream_ creator, @Nullable Stream_ parent) {
         reversedNodeList.add(node);
         node.addLocationSet(creator.getLocationSet());
         nodeCreatorMap.put(node, creator);

…main/lookup/ImmutableLookUpStrategy.java …main/common/ImmutableLookupStrategy.javacore/src/main/java/ai/timefold/solver/core/impl/domain/lookup/ImmutableLookUpStrategy.java renamed to core/src/main/java/ai/timefold/solver/core/impl/domain/common/ImmutableLookupStrategy.java core/src/main/java/ai/timefold/solver/core/impl/domain/lookup/ImmutableLookUpStrategy.java renamed to core/src/main/java/ai/timefold/solver/core/impl/domain/common/ImmutableLookupStrategy.java

@@ -1,11 +1,11 @@
-package ai.timefold.solver.core.impl.domain.lookup;
+package ai.timefold.solver.core.impl.domain.common;
 
 import java.util.Map;
 
 import org.jspecify.annotations.NullMarked;
 
 @NullMarked
-final class ImmutableLookUpStrategy implements LookUpStrategy {
+final class ImmutableLookupStrategy implements LookupStrategy {
 
     @Override
     public void addWorkingObject(Map<Object, Object> idToWorkingObjectMap, Object workingObject) {
@@ -23,10 +23,4 @@ public <E> E lookUpWorkingObject(Map<Object, Object> idToWorkingObjectMap, E ext
         return externalObject;
     }
 
-    @Override
-    public <E> E lookUpWorkingObjectIfExists(Map<Object, Object> idToWorkingObjectMap, E externalObject) {
-        // Because it is immutable, we can use the same one.
-        return externalObject;
-    }
-
 }

…pl/domain/lookup/LookUpStrategyType.java …pl/domain/common/LookUpStrategyType.javacore/src/main/java/ai/timefold/solver/core/impl/domain/lookup/LookUpStrategyType.java renamed to core/src/main/java/ai/timefold/solver/core/impl/domain/common/LookUpStrategyType.java core/src/main/java/ai/timefold/solver/core/impl/domain/lookup/LookUpStrategyType.java renamed to core/src/main/java/ai/timefold/solver/core/impl/domain/common/LookUpStrategyType.java

@@ -1,4 +1,4 @@
-package ai.timefold.solver.core.impl.domain.lookup;
+package ai.timefold.solver.core.impl.domain.common;
 
 import ai.timefold.solver.core.api.domain.common.PlanningId;
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;

core/src/main/java/ai/timefold/solver/core/impl/domain/common/LookupManager.java

@@ -0,0 +1,50 @@
+package ai.timefold.solver.core.impl.domain.common;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import ai.timefold.solver.core.api.domain.common.Lookup;
+import ai.timefold.solver.core.api.domain.common.PlanningId;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * @see PlanningId
+ * @see Lookup
+ */
+@NullMarked
+public final class LookupManager
+        implements Lookup {
+
+    private final LookupStrategyResolver lookupStrategyResolver;
+    private final Map<Object, Object> idToWorkingObjectMap = new HashMap<>();
+
+    public LookupManager(LookupStrategyResolver lookupStrategyResolver) {
+        this.lookupStrategyResolver = lookupStrategyResolver;
+    }
+
+    public void reset() {
+        idToWorkingObjectMap.clear();
+    }
+
+    public void addWorkingObject(Object workingObject) {
+        var lookupStrategy = lookupStrategyResolver.determineLookUpStrategy(workingObject);
+        lookupStrategy.addWorkingObject(idToWorkingObjectMap, workingObject);
+    }
+
+    public void removeWorkingObject(Object workingObject) {
+        var lookupStrategy = lookupStrategyResolver.determineLookUpStrategy(workingObject);
+        lookupStrategy.removeWorkingObject(idToWorkingObjectMap, workingObject);
+    }
+
+    @Override
+    public <E> @Nullable E lookUpWorkingObject(@Nullable E externalObject) {
+        if (externalObject == null) {
+            return null;
+        }
+        var lookupStrategy = lookupStrategyResolver.determineLookUpStrategy(externalObject);
+        return lookupStrategy.lookUpWorkingObject(idToWorkingObjectMap, externalObject);
+    }
+
+}