chore: final check of codebase post refactors (#2148)

Author: triceo

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

@@ -10,7 +10,7 @@
 import ai.timefold.solver.core.api.solver.change.ProblemChange;
 import ai.timefold.solver.core.impl.domain.solution.DefaultConstraintWeightOverrides;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -30,6 +30,7 @@
  *
  * @param <Score_>
  */
+@NullMarked
 public interface ConstraintWeightOverrides<Score_ extends Score<Score_>> {
 
     static <Score_ extends Score<Score_>> ConstraintWeightOverrides<Score_> none() {
@@ -46,14 +47,13 @@ static <Score_ extends Score<Score_>> ConstraintWeightOverrides<Score_> of(Map<S
      * @return null if the constraint name is not known
      */
     @Nullable
-    Score_ getConstraintWeight(@NonNull String constraintName);
+    Score_ getConstraintWeight(String constraintName);
 
     /**
      * Returns all known constraints.
      *
      * @return All constraint names for which {@link #getConstraintWeight(String)} returns a non-null value.
      */
-    @NonNull
     Set<String> getKnownConstraintNames();
 
 }

core/src/main/java/ai/timefold/solver/core/api/domain/valuerange/ValueRange.java

@@ -29,20 +29,10 @@ public interface ValueRange<T> {
 
     /**
      * @param value sometimes null
-     * @return true if the ValueRange contains that value
+     * @return true if the range contains that value
      */
     boolean contains(@Nullable T value);
 
-    /**
-     * Select in random order, but without shuffling the elements.
-     * Each element might be selected multiple times.
-     * Scales well because it does not require caching.
-     *
-     * @param workingRandom the {@link RandomGenerator} to use when any random number is needed,
-     *        so runs are reproducible.
-     */
-    Iterator<T> createRandomIterator(RandomGenerator workingRandom);
-
     /**
      * Used by uniform random selection.
      *
@@ -64,4 +54,14 @@ public interface ValueRange<T> {
      */
     Iterator<T> createOriginalIterator();
 
+    /**
+     * Select in random order, but without shuffling the elements.
+     * Each element might be selected multiple times.
+     * Scales well because it does not require caching.
+     *
+     * @param workingRandom the {@link RandomGenerator} to use when any random number is needed,
+     *        so runs are reproducible.
+     */
+    Iterator<T> createRandomIterator(RandomGenerator workingRandom);
+
 }

core/src/main/java/ai/timefold/solver/core/api/domain/variable/InverseRelationShadowVariable.java

@@ -11,8 +11,8 @@
 import ai.timefold.solver.core.api.solver.Solver;
 
 /**
- * Specifies that a bean property (or a field) is the inverse of a {@link PlanningVariable}, which implies it's a shadow
- * variable.
+ * Specifies that a bean property (or a field) is the inverse of a {@link PlanningVariable} or a {@link PlanningListVariable}
+ * which implies it's a shadow variable.
  * <p>
  * It is specified on a getter of a java bean property (or a field) of a {@link PlanningEntity} class.
  */
@@ -22,7 +22,7 @@
 
     /**
      * In a bidirectional relationship, the shadow side (= the follower side) uses this property
-     * (and nothing else) to declare for which {@link PlanningVariable} (= the leader side) it is a shadow.
+     * (and nothing else) to declare for which variable (= the leader side) it is a shadow.
      * <p>
      * Both sides of a bidirectional relationship should be consistent: if A points to B, then B must point to A.
      * <p>

core/src/main/java/ai/timefold/solver/core/api/domain/variable/NextElementShadowVariable.java

@@ -19,7 +19,6 @@
  * <p>
  * The source variable must be a {@link PlanningListVariable list variable}.
  */
-// TODO When a non-disjoint list variable is supported, specify that this annotation is only allowed on disjoint list variables.
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)
 public @interface NextElementShadowVariable {

core/src/main/java/ai/timefold/solver/core/api/domain/variable/PlanningListVariable.java

@@ -38,9 +38,9 @@
  * </ul>
  *
  * <p>
- * This makes sense for common use cases, for example the Vehicle Routing Problem or Task Assigning. In both cases
- * the <em>order</em> in which customers are visited and tasks are being worked on matters. Also, each customer
- * must be visited <em>once</em> and each task must be completed by <em>exactly one</em> employee.
+ * This makes sense for common use cases, for example the Vehicle Routing Problem or Task Assigning.
+ * In both cases the <em>order</em> in which customers are visited and tasks are being worked on matters.
+ * Also, each customer must be visited <em>once</em> and each task must be completed by <em>exactly one</em> employee.
  *
  * @see PlanningPin
  * @see PlanningPinToIndex

core/src/main/java/ai/timefold/solver/core/api/domain/variable/PlanningVariableReference.java

@@ -19,7 +19,6 @@
  * <p>
  * The source variable must be a {@link PlanningListVariable list variable}.
  */
-// TODO When a non-disjoint list variable is supported, specify that this annotation is only allowed on disjoint list variables.
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)
 public @interface PreviousElementShadowVariable {

core/src/main/java/ai/timefold/solver/core/api/domain/variable/PreviousElementShadowVariable.java

@@ -11,20 +11,19 @@
 
 /**
  * Specifies that a bean property (or a field) is a custom shadow variable of 1 or more source variables.
- * The source variable may be a genuine {@link PlanningVariable}, {@link PlanningListVariable}, or another shadow variable.
+ * The source variable may be a genuine {@link PlanningVariable}, {@link PlanningListVariable},
+ * or another shadow variable.
  * <p>
  * It is specified on a getter of a java bean property (or a field) of a {@link PlanningEntity} class.
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)
 public @interface ShadowVariable {
+
     /**
-     * {@link ai.timefold.solver.core.config.solver.PreviewFeature Preview feature}.
-     * <p>
-     * If set, this {@link ShadowVariable} is a supplier variable, and it
-     * is a name of a method annotated with
-     * {@link ShadowSources} that computes the value of this
-     * {@link ShadowVariable}.
+     * If set, this {@link ShadowVariable} is a supplier variable,
+     * and it is a name of a method annotated with {@link ShadowSources}
+     * that computes the value of this {@link ShadowVariable}.
      *
      * @return the method that computes the value of this {@link ShadowVariable}.
      */

core/src/main/java/ai/timefold/solver/core/api/domain/variable/ShadowVariable.java

@@ -126,10 +126,9 @@
  * The solver will fail-fast if it detects a source-induced or fact-induced loop.
  * <p>
  * Important:
- * Do not use a {@link ShadowVariablesInconsistent} property in a method annotated
- * with {@link ShadowSources}. {@link ShadowSources} marked methods do not need to check
- * {@link ShadowVariablesInconsistent} properties, since they are only called if all
- * their dependencies are consistent.
+ * Do not use a {@link ShadowVariablesInconsistent} property in a method annotated with {@link ShadowSources}.
+ * {@link ShadowSources} marked methods do not need to check {@link ShadowVariablesInconsistent} properties,
+ * since they are only called if all their dependencies are consistent.
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)

core/src/main/java/ai/timefold/solver/core/api/domain/variable/ShadowVariablesInconsistent.java

@@ -15,8 +15,8 @@
  * @param <Score_> the actual score type to allow addition, subtraction and other arithmetic
  */
 @NullMarked
-public interface IBendableScore<Score_ extends IBendableScore<Score_>>
-        extends Score<Score_> {
+public sealed interface IBendableScore<Score_ extends IBendableScore<Score_>>
+        extends Score<Score_> permits BendableBigDecimalScore, BendableScore {
 
     /**
      * The sum of this and {@link #softLevelsSize()} equals {@link #levelsSize()}.