refactor: introduce incremental constraint collectors for improved performance

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

@@ -1715,8 +1715,7 @@ public final class ConstraintCollectors {
                     @NonNull Function<A, PointType_> endExclusiveMap,
                     @NonNull BiFunction<PointType_, PointType_, DifferenceType_> differenceFunction) {
         return InnerUniConstraintCollectors.toConnectedRanges(ConstantLambdaUtils.identity(), startInclusiveMap,
-                endExclusiveMap,
-                differenceFunction);
+                endExclusiveMap, differenceFunction);
     }
 
     /**

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

@@ -8,7 +8,8 @@
 import ai.timefold.solver.core.api.score.stream.ConstraintStream;
 import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollector;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * As described by {@link UniConstraintCollector}, only for {@link BiConstraintStream}.
@@ -22,28 +23,24 @@
  *        especially if this value is ever used as a group key.
  * @see ConstraintCollectors
  */
+@NullMarked
 public interface BiConstraintCollector<A, B, ResultContainer_, Result_> {
 
     /**
-     * A lambda that creates the result container, one for each group key combination.
+     * As defined by {@link UniConstraintCollector#supplier()}, but for {@link BiConstraintStream}.
      */
-    @NonNull
     Supplier<ResultContainer_> supplier();
 
     /**
-     * A lambda that extracts data from the matched facts,
-     * accumulates it in the result container
-     * and returns an undo operation for that accumulation.
-     *
-     * @return the undo operation. This lambda is called when the facts no longer matches.
+     * As defined by {@link UniConstraintCollector#accumulator()}, but for {@link BiConstraintStream}.
+     * 
+     * @see BiConstraintCollectorAccumulator An incremental API to be returned instead of the deprecated plain tri-function.
      */
-    @NonNull
     TriFunction<ResultContainer_, A, B, Runnable> accumulator();
 
     /**
-     * A lambda that converts the result container into the result.
+     * As defined by {@link UniConstraintCollector#finisher()}, but for {@link BiConstraintStream}.
      */
-    @NonNull
-    Function<ResultContainer_, Result_> finisher();
+    Function<ResultContainer_, @Nullable Result_> finisher();
 
 }

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

@@ -0,0 +1,33 @@
+package ai.timefold.solver.core.api.score.stream.bi;
+
+import ai.timefold.solver.core.api.function.TriFunction;
+import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorAccumulator;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * As defined by {@link UniConstraintCollectorAccumulator},
+ * only for {@link BiConstraintCollector}.
+ */
+@NullMarked
+@FunctionalInterface
+public interface BiConstraintCollectorAccumulator<ResultContainer_, A, B>
+        extends TriFunction<ResultContainer_, A, B, Runnable> {
+
+    /**
+     * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
+     * only for {@link BiConstraintCollector}.
+     */
+    BiConstraintCollectorValueHandle<A, B> intoGroup(ResultContainer_ resultContainer);
+
+    /**
+     * @deprecated Use {@link #intoGroup(Object)} instead.
+     * @throws UnsupportedOperationException always
+     */
+    @Deprecated(since = "2.2.0", forRemoval = true)
+    @Override
+    default Runnable apply(ResultContainer_ resultContainer, A a, B b) {
+        throw new UnsupportedOperationException("Use intoGroup() instead.");
+    }
+
+}

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

@@ -0,0 +1,36 @@
+package ai.timefold.solver.core.api.score.stream.bi;
+
+import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorValueHandle;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * As defined by {@link UniConstraintCollectorValueHandle},
+ * only for {@link BiConstraintCollector}.
+ */
+@NullMarked
+public interface BiConstraintCollectorValueHandle<A, B> {
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#add(Object)},
+     * only for {@link BiConstraintCollector}
+     */
+    void add(@Nullable A a, @Nullable B b);
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#replaceWith(Object)},
+     * only for {@link BiConstraintCollector}
+     */
+    default void replaceWith(@Nullable A a, @Nullable B b) {
+        remove();
+        add(a, b);
+    }
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#remove()},
+     * only for {@link BiConstraintCollector}
+     */
+    void remove();
+
+}

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

@@ -8,7 +8,8 @@
 import ai.timefold.solver.core.api.score.stream.ConstraintStream;
 import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollector;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * As described by {@link UniConstraintCollector}, only for {@link QuadConstraintStream}.
@@ -24,28 +25,24 @@
  *        especially if this value is ever used as a group key.
  * @see ConstraintCollectors
  */
+@NullMarked
 public interface QuadConstraintCollector<A, B, C, D, ResultContainer_, Result_> {
 
     /**
-     * A lambda that creates the result container, one for each group key combination.
+     * As defined by {@link UniConstraintCollector#supplier()}, but for {@link QuadConstraintStream}.
      */
-    @NonNull
     Supplier<ResultContainer_> supplier();
 
     /**
-     * A lambda that extracts data from the matched facts,
-     * accumulates it in the result container
-     * and returns an undo operation for that accumulation.
-     *
-     * @return the undo operation. This lambda is called when the facts no longer matches.
+     * As defined by {@link UniConstraintCollector#accumulator()}, but for {@link QuadConstraintStream}.
+     * 
+     * @see QuadConstraintCollectorAccumulator An incremental API to be returned instead of the deprecated plain penta-function.
      */
-    @NonNull
     PentaFunction<ResultContainer_, A, B, C, D, Runnable> accumulator();
 
     /**
-     * A lambda that converts the result container into the result.
+     * As defined by {@link UniConstraintCollector#finisher()}, but for {@link QuadConstraintStream}.
      */
-    @NonNull
-    Function<ResultContainer_, Result_> finisher();
+    Function<ResultContainer_, @Nullable Result_> finisher();
 
 }

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

@@ -0,0 +1,33 @@
+package ai.timefold.solver.core.api.score.stream.quad;
+
+import ai.timefold.solver.core.api.function.PentaFunction;
+import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorAccumulator;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * As defined by {@link UniConstraintCollectorAccumulator},
+ * only for {@link QuadConstraintCollector}.
+ */
+@NullMarked
+@FunctionalInterface
+public interface QuadConstraintCollectorAccumulator<ResultContainer_, A, B, C, D>
+        extends PentaFunction<ResultContainer_, A, B, C, D, Runnable> {
+
+    /**
+     * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
+     * only for {@link QuadConstraintCollector}.
+     */
+    QuadConstraintCollectorValueHandle<A, B, C, D> intoGroup(ResultContainer_ resultContainer);
+
+    /**
+     * @deprecated Use {@link #intoGroup(Object)} instead.
+     * @throws UnsupportedOperationException always
+     */
+    @Deprecated(since = "2.2.0", forRemoval = true)
+    @Override
+    default Runnable apply(ResultContainer_ resultContainer, A a, B b, C c, D d) {
+        throw new UnsupportedOperationException("Use intoGroup() instead.");
+    }
+
+}

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

@@ -0,0 +1,36 @@
+package ai.timefold.solver.core.api.score.stream.quad;
+
+import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorValueHandle;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * As defined by {@link UniConstraintCollectorValueHandle},
+ * only for {@link QuadConstraintCollector}.
+ */
+@NullMarked
+public interface QuadConstraintCollectorValueHandle<A, B, C, D> {
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#add(Object)},
+     * only for {@link QuadConstraintCollector}
+     */
+    void add(@Nullable A a, @Nullable B b, @Nullable C c, @Nullable D d);
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#replaceWith(Object)},
+     * only for {@link QuadConstraintCollector}
+     */
+    default void replaceWith(@Nullable A a, @Nullable B b, @Nullable C c, @Nullable D d) {
+        remove();
+        add(a, b, c, d);
+    }
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#remove()},
+     * only for {@link QuadConstraintCollector}
+     */
+    void remove();
+
+}

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

@@ -8,7 +8,8 @@
 import ai.timefold.solver.core.api.score.stream.ConstraintStream;
 import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollector;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * As described by {@link UniConstraintCollector}, only for {@link TriConstraintStream}.
@@ -23,28 +24,24 @@
  *        especially if this value is ever used as a group key.
  * @see ConstraintCollectors
  */
+@NullMarked
 public interface TriConstraintCollector<A, B, C, ResultContainer_, Result_> {
 
     /**
-     * A lambda that creates the result container, one for each group key combination.
+     * As defined by {@link UniConstraintCollector#supplier()}, but for {@link TriConstraintStream}.
      */
-    @NonNull
     Supplier<ResultContainer_> supplier();
 
     /**
-     * A lambda that extracts data from the matched facts,
-     * accumulates it in the result container
-     * and returns an undo operation for that accumulation.
-     *
-     * @return the undo operation. This lambda is called when the facts no longer matches.
+     * As defined by {@link UniConstraintCollector#accumulator()}, but for {@link TriConstraintStream}.
+     * 
+     * @see TriConstraintCollectorAccumulator An incremental API to be returned instead of the deprecated plain quad-function.
      */
-    @NonNull
     QuadFunction<ResultContainer_, A, B, C, Runnable> accumulator();
 
     /**
-     * A lambda that converts the result container into the result.
+     * As defined by {@link UniConstraintCollector#finisher()}, but for {@link TriConstraintStream}.
      */
-    @NonNull
-    Function<ResultContainer_, Result_> finisher();
+    Function<ResultContainer_, @Nullable Result_> finisher();
 
 }

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

@@ -0,0 +1,33 @@
+package ai.timefold.solver.core.api.score.stream.tri;
+
+import ai.timefold.solver.core.api.function.QuadFunction;
+import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorAccumulator;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * As defined by {@link UniConstraintCollectorAccumulator},
+ * only for {@link TriConstraintCollector}.
+ */
+@NullMarked
+@FunctionalInterface
+public interface TriConstraintCollectorAccumulator<ResultContainer_, A, B, C>
+        extends QuadFunction<ResultContainer_, A, B, C, Runnable> {
+
+    /**
+     * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
+     * only for {@link TriConstraintCollector}.
+     */
+    TriConstraintCollectorValueHandle<A, B, C> intoGroup(ResultContainer_ resultContainer);
+
+    /**
+     * @deprecated Use {@link #intoGroup(Object)} instead.
+     * @throws UnsupportedOperationException always
+     */
+    @Deprecated(since = "2.2.0", forRemoval = true)
+    @Override
+    default Runnable apply(ResultContainer_ resultContainer, A a, B b, C c) {
+        throw new UnsupportedOperationException("Use intoGroup() instead.");
+    }
+
+}

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

@@ -0,0 +1,36 @@
+package ai.timefold.solver.core.api.score.stream.tri;
+
+import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorValueHandle;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * As defined by {@link UniConstraintCollectorValueHandle},
+ * only for {@link TriConstraintCollector}.
+ */
+@NullMarked
+public interface TriConstraintCollectorValueHandle<A, B, C> {
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#add(Object)},
+     * only for {@link TriConstraintCollector}
+     */
+    void add(@Nullable A a, @Nullable B b, @Nullable C c);
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#replaceWith(Object)},
+     * only for {@link TriConstraintCollector}
+     */
+    default void replaceWith(@Nullable A a, @Nullable B b, @Nullable C c) {
+        remove();
+        add(a, b, c);
+    }
+
+    /**
+     * As defined by {@link UniConstraintCollectorValueHandle#remove()},
+     * only for {@link TriConstraintCollector}
+     */
+    void remove();
+
+}