refactor: hide domain lookups

Author: triceo

…r/core/api/domain/lookup/PlanningId.java …r/core/api/domain/entity/PlanningId.javacore/src/main/java/ai/timefold/solver/core/api/domain/lookup/PlanningId.java renamed to core/src/main/java/ai/timefold/solver/core/api/domain/entity/PlanningId.java core/src/main/java/ai/timefold/solver/core/api/domain/lookup/PlanningId.java renamed to core/src/main/java/ai/timefold/solver/core/api/domain/entity/PlanningId.java

@@ -1,4 +1,4 @@
-package ai.timefold.solver.core.api.domain.lookup;
+package ai.timefold.solver.core.api.domain.entity;
 
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
@@ -7,7 +7,6 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
 import ai.timefold.solver.core.api.domain.solution.ProblemFactCollectionProperty;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeProvider;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;

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

@@ -7,8 +7,6 @@
 import java.lang.annotation.Target;
 
 import ai.timefold.solver.core.api.domain.autodiscover.AutoDiscoverMemberType;
-import ai.timefold.solver.core.api.domain.lookup.LookUpStrategyType;
-import ai.timefold.solver.core.api.domain.lookup.PlanningId;
 import ai.timefold.solver.core.api.domain.solution.cloner.SolutionCloner;
 import ai.timefold.solver.core.api.score.stream.ConstraintProvider;
 
@@ -73,11 +71,4 @@
     interface NullSolutionCloner extends SolutionCloner {
     }
 
-    /**
-     * @deprecated When multi-threaded solving, ensure your domain classes use {@link PlanningId} instead.
-     */
-    @Deprecated(forRemoval = true, since = "1.10.0")
-    @NonNull
-    LookUpStrategyType lookUpStrategyType() default LookUpStrategyType.PLANNING_ID_OR_NONE;
-
 }

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

@@ -1,7 +1,6 @@
 package ai.timefold.solver.core.api.score.director;
 
-import ai.timefold.solver.core.api.domain.lookup.LookUpStrategyType;
-import ai.timefold.solver.core.api.domain.lookup.PlanningId;
+import ai.timefold.solver.core.api.domain.entity.PlanningId;
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.api.solver.change.ProblemChange;
@@ -139,8 +138,7 @@ default void afterProblemFactRemoved(Object problemFact) {
      * to this {@link ScoreDirector}'s internal working instance.
      * Useful for move rebasing and in a {@link ProblemChange}.
      * <p>
-     * Matching is determined by the {@link LookUpStrategyType} on {@link PlanningSolution}.
-     * Matching uses a {@link PlanningId} by default.
+     * 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
@@ -156,7 +154,7 @@ default void afterProblemFactRemoved(Object problemFact) {
      * It's recommended to use {@link #lookUpWorkingObject(Object)} instead,
      * especially in move rebasing code.
      *
-     * @return null if externalObject is null or if there is no workingObject for externalObject
+     * @return null if externalObject is null, or if there is no workingObject for externalObject
      * @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 <E> the object type

core/src/main/java/ai/timefold/solver/core/api/score/stream/ConstraintFactory.java

@@ -5,7 +5,7 @@
 import java.util.function.Predicate;
 
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
-import ai.timefold.solver.core.api.domain.lookup.PlanningId;
+import ai.timefold.solver.core.api.domain.entity.PlanningId;
 import ai.timefold.solver.core.api.domain.solution.ProblemFactCollectionProperty;
 import ai.timefold.solver.core.api.domain.variable.InverseRelationShadowVariable;
 import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;

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

@@ -4,13 +4,12 @@
 import java.util.function.Consumer;
 
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
-import ai.timefold.solver.core.api.domain.lookup.LookUpStrategyType;
-import ai.timefold.solver.core.api.domain.lookup.PlanningId;
+import ai.timefold.solver.core.api.domain.entity.PlanningId;
 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.NonNull;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -21,6 +20,7 @@
  * Should be used only from a {@link ProblemChange} implementation.
  * To see an example implementation, please refer to the {@link ProblemChange} Javadoc.
  */
+@NullMarked
 public interface ProblemChangeDirector {
 
     /**
@@ -30,7 +30,7 @@ public interface ProblemChangeDirector {
      * @param entityConsumer adds the entity to the {@link PlanningSolution working solution}
      * @param <Entity> the planning entity object type
      */
-    <Entity> void addEntity(@NonNull Entity entity, @NonNull Consumer<Entity> entityConsumer);
+    <Entity> void addEntity(Entity entity, Consumer<Entity> entityConsumer);
 
     /**
      * Remove an existing {@link PlanningEntity} instance from the {@link PlanningSolution working solution}.
@@ -41,7 +41,7 @@ public interface ProblemChangeDirector {
      * @param entityConsumer removes the working entity from the {@link PlanningSolution working solution}
      * @param <Entity> the planning entity object type
      */
-    <Entity> void removeEntity(@NonNull Entity entity, @NonNull Consumer<Entity> entityConsumer);
+    <Entity> void removeEntity(Entity entity, Consumer<Entity> entityConsumer);
 
     /**
      * Change a {@link PlanningVariable} value of a {@link PlanningEntity}. Translates the entity to a working
@@ -52,8 +52,7 @@ public interface ProblemChangeDirector {
      * @param entityConsumer updates the value of the {@link PlanningVariable} inside the {@link PlanningEntity}
      * @param <Entity> the planning entity object type
      */
-    <Entity> void changeVariable(@NonNull Entity entity, @NonNull String variableName,
-            @NonNull Consumer<Entity> entityConsumer);
+    <Entity> void changeVariable(Entity entity, String variableName, Consumer<Entity> entityConsumer);
 
     /**
      * Add a new problem fact into the {@link PlanningSolution working solution}.
@@ -63,7 +62,7 @@ <Entity> void changeVariable(@NonNull Entity entity, @NonNull String variableNam
      *        {@link PlanningSolution working solution}
      * @param <ProblemFact> the problem fact object type
      */
-    <ProblemFact> void addProblemFact(@NonNull ProblemFact problemFact, @NonNull Consumer<ProblemFact> problemFactConsumer);
+    <ProblemFact> void addProblemFact(ProblemFact problemFact, Consumer<ProblemFact> problemFactConsumer);
 
     /**
      * Remove an existing problem fact from the {@link PlanningSolution working solution}. Translates the problem fact
@@ -74,7 +73,7 @@ <Entity> void changeVariable(@NonNull Entity entity, @NonNull String variableNam
      *        {@link PlanningSolution working solution}
      * @param <ProblemFact> the problem fact object type
      */
-    <ProblemFact> void removeProblemFact(@NonNull ProblemFact problemFact, @NonNull Consumer<ProblemFact> problemFactConsumer);
+    <ProblemFact> void removeProblemFact(ProblemFact problemFact, Consumer<ProblemFact> problemFactConsumer);
 
     /**
      * Change a property of either a {@link PlanningEntity} or a problem fact. Translates the entity or the problem fact
@@ -86,15 +85,14 @@ <Entity> void changeVariable(@NonNull Entity entity, @NonNull String variableNam
      *        or the problem fact
      * @param <EntityOrProblemFact> the planning entity or problem fact object type
      */
-    <EntityOrProblemFact> void changeProblemProperty(@NonNull EntityOrProblemFact problemFactOrEntity,
-            @NonNull Consumer<EntityOrProblemFact> problemFactOrEntityConsumer);
+    <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 is determined by the {@link LookUpStrategyType} on {@link PlanningSolution}.
-     * Matching uses a {@link PlanningId} by default.
+     * 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
@@ -109,7 +107,7 @@ <EntityOrProblemFact> void changeProblemProperty(@NonNull EntityOrProblemFact pr
      * 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 externalObject is null or if there is no workingObject for externalObject
+     * @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

core/src/main/java/ai/timefold/solver/core/config/util/ConfigUtils.java

@@ -1,7 +1,6 @@
 package ai.timefold.solver.core.config.util;
 
 import static ai.timefold.solver.core.impl.domain.common.accessor.MemberAccessorFactory.MemberAccessorType.FIELD_OR_READ_METHOD;
-import static ai.timefold.solver.core.impl.domain.solution.cloner.DeepCloningUtils.IMMUTABLE_CLASSES;
 
 import java.lang.annotation.Annotation;
 import java.lang.reflect.AnnotatedElement;
@@ -32,7 +31,7 @@
 import java.util.stream.Stream;
 
 import ai.timefold.solver.core.api.domain.common.DomainAccessType;
-import ai.timefold.solver.core.api.domain.lookup.PlanningId;
+import ai.timefold.solver.core.api.domain.entity.PlanningId;
 import ai.timefold.solver.core.config.AbstractConfig;
 import ai.timefold.solver.core.impl.domain.common.AlphabeticMemberComparator;
 import ai.timefold.solver.core.impl.domain.common.ReflectionHelper;
@@ -451,17 +450,6 @@ Maybe the member (%s) should return a parameterized %s."""
                                 memberName, type, memberName, type.getSimpleName())));
     }
 
-    /**
-     * @param type the class type
-     * @return true if it is immutable; otherwise false
-     */
-    public static boolean isGenericTypeImmutable(Class<?> type) {
-        if (type == null) {
-            return false;
-        }
-        return type.isRecord() || IMMUTABLE_CLASSES.contains(type);
-    }
-
     public static Optional<Class<?>> extractGenericTypeParameter(@NonNull String parentClassConcept,
             @NonNull Class<?> parentClass, @NonNull Class<?> type, @NonNull Type genericType,
             @Nullable Class<? extends Annotation> annotationClass, @NonNull String memberName) {

core/src/main/java/ai/timefold/solver/core/impl/domain/lookup/EqualsLookUpStrategy.java

@@ -2,7 +2,10 @@
 
 import java.util.Map;
 
-public final class ImmutableLookUpStrategy implements LookUpStrategy {
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+final class ImmutableLookUpStrategy implements LookUpStrategy {
 
     @Override
     public void addWorkingObject(Map<Object, Object> idToWorkingObjectMap, Object workingObject) {

core/src/main/java/ai/timefold/solver/core/impl/domain/lookup/ImmutableLookUpStrategy.java

@@ -3,14 +3,18 @@
 import java.util.HashMap;
 import java.util.Map;
 
-import ai.timefold.solver.core.api.domain.lookup.PlanningId;
+import ai.timefold.solver.core.api.domain.entity.PlanningId;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
 /**
  * @see PlanningId
  * @see ScoreDirector#lookUpWorkingObject(Object)
  */
-public class LookUpManager {
+@NullMarked
+public final class LookUpManager {
 
     private final LookUpStrategyResolver lookUpStrategyResolver;
 
@@ -26,47 +30,45 @@ public void reset() {
     }
 
     public void addWorkingObject(Object workingObject) {
-        LookUpStrategy lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(workingObject);
+        var lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(workingObject);
         lookUpStrategy.addWorkingObject(idToWorkingObjectMap, workingObject);
     }
 
     public void removeWorkingObject(Object workingObject) {
-        LookUpStrategy lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(workingObject);
+        var lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(workingObject);
         lookUpStrategy.removeWorkingObject(idToWorkingObjectMap, workingObject);
     }
 
     /**
      * As defined by {@link ScoreDirector#lookUpWorkingObject(Object)}.
      *
-     * @param externalObject sometimes null
-     * @return null if externalObject is null
+     * @return null if there is no workingObject for externalObject
      * @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 <E> the object type
      */
-    public <E> E lookUpWorkingObject(E externalObject) {
+    public <E> @Nullable E lookUpWorkingObject(@Nullable E externalObject) {
         if (externalObject == null) {
             return null;
         }
-        LookUpStrategy lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(externalObject);
+        var lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(externalObject);
         return lookUpStrategy.lookUpWorkingObject(idToWorkingObjectMap, externalObject);
     }
 
     /**
      * As defined by {@link ScoreDirector#lookUpWorkingObjectOrReturnNull(Object)}.
      *
-     * @param externalObject sometimes null
-     * @return null if externalObject is null or if there is no workingObject for externalObject
+     * @return null if externalObject is null, or if there is no workingObject for externalObject
      * @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 <E> the object type
      */
-    public <E> E lookUpWorkingObjectOrReturnNull(E externalObject) {
+    public <E> @Nullable E lookUpWorkingObjectOrReturnNull(@Nullable E externalObject) {
         if (externalObject == null) {
             return null;
         }
-        LookUpStrategy lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(externalObject);
+        var lookUpStrategy = lookUpStrategyResolver.determineLookUpStrategy(externalObject);
         return lookUpStrategy.lookUpWorkingObjectIfExists(idToWorkingObjectMap, externalObject);
     }
 

core/src/main/java/ai/timefold/solver/core/impl/domain/lookup/LookUpManager.java

@@ -2,15 +2,19 @@
 
 import java.util.Map;
 
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+@NullMarked
 public sealed interface LookUpStrategy
-        permits EqualsLookUpStrategy, ImmutableLookUpStrategy, NoneLookUpStrategy, PlanningIdLookUpStrategy {
+        permits ImmutableLookUpStrategy, NoneLookUpStrategy, PlanningIdLookUpStrategy {
 
     void addWorkingObject(Map<Object, Object> idToWorkingObjectMap, Object workingObject);
 
     void removeWorkingObject(Map<Object, Object> idToWorkingObjectMap, Object workingObject);
 
     <E> E lookUpWorkingObject(Map<Object, Object> idToWorkingObjectMap, E externalObject);
 
-    <E> E lookUpWorkingObjectIfExists(Map<Object, Object> idToWorkingObjectMap, E externalObject);
+    <E> @Nullable E lookUpWorkingObjectIfExists(Map<Object, Object> idToWorkingObjectMap, E externalObject);
 
 }