chore: support pinning in Move Streams (#1560)

By default, enumerations produce results without pinned entities.
If pinned entities are required, they have to be specifically requested.

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/domain/entity/PinningFilter.java

@@ -2,22 +2,25 @@
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Decides on accepting or discarding a {@link PlanningEntity}.
  * A pinned {@link PlanningEntity}'s planning variables are never changed.
  *
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
  * @param <Entity_> the entity type, the class with the {@link PlanningEntity} annotation
+ * @deprecated Use {@link PlanningPin} instead.
  */
+@Deprecated(forRemoval = true, since = "1.23.0")
+@NullMarked
 public interface PinningFilter<Solution_, Entity_> {
 
     /**
      * @param solution working solution to which the entity belongs
      * @param entity a {@link PlanningEntity}
      * @return true if the entity it is pinned, false if the entity is movable.
      */
-    boolean accept(@NonNull Solution_ solution, @NonNull Entity_ entity);
+    boolean accept(Solution_ solution, Entity_ entity);
 
 }

core/src/main/java/ai/timefold/solver/core/api/domain/entity/PlanningEntity.java

@@ -37,18 +37,23 @@
     /**
      * A pinned planning entity is never changed during planning,
      * this is useful in repeated planning use cases (such as continuous planning and real-time planning).
-     * <p>
      * This applies to all the planning variables of this planning entity.
-     * To pin individual variables, see https://issues.redhat.com/browse/PLANNER-124
      * <p>
      * The method {@link PinningFilter#accept(Object, Object)} returns false if the selection entity is pinned
      * and it returns true if the selection entity is movable
      *
      * @return {@link NullPinningFilter} when it is null (workaround for annotation limitation)
+     * @deprecated Prefer using {@link PlanningPin}.
      */
+    @Deprecated(forRemoval = true, since = "1.23.0")
     Class<? extends PinningFilter> pinningFilter() default NullPinningFilter.class;
 
-    /** Workaround for annotation limitation in {@link #pinningFilter()} ()}. */
+    /**
+     * Workaround for annotation limitation in {@link #pinningFilter()}.
+     * 
+     * @deprecated Prefer using {@link PlanningPin}.
+     */
+    @Deprecated(forRemoval = true, since = "1.23.0")
     interface NullPinningFilter extends PinningFilter {
     }
 

core/src/main/java/ai/timefold/solver/core/api/domain/entity/PlanningPin.java

@@ -8,10 +8,12 @@
 import java.lang.annotation.Target;
 
 import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
+import ai.timefold.solver.core.api.solver.change.ProblemChange;
 
 /**
  * Specifies that a boolean property (or field) of a {@link PlanningEntity} determines if the planning entity is pinned.
- * A pinned planning entity is never changed during planning.
+ * A pinned planning entity is never changed during planning;
+ * to change a pinned planning entity, even to make it not pinned anymore, trigger a {@link ProblemChange}.
  * For example, it allows the user to pin a shift to a specific employee before solving
  * and the solver will not undo that, regardless of the constraints.
  * <p>
@@ -20,9 +22,9 @@
  * It applies to all the planning variables of that planning entity.
  * If set on an entity with {@link PlanningListVariable},
  * this will pin the entire list of planning values as well.
- * <p>
- * This is syntactic sugar for {@link PlanningEntity#pinningFilter()},
- * which is a more flexible and verbose way to pin a planning entity.
+ * 
+ * @see PlanningPinToIndex Read more about how to only pin part of the planning list variable.
+ * @see ProblemChange Use ProblemChange to trigger pinning changes.
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)

core/src/main/java/ai/timefold/solver/core/api/domain/entity/PlanningPinToIndex.java

@@ -8,6 +8,7 @@
 import java.lang.annotation.Target;
 
 import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
+import ai.timefold.solver.core.api.solver.change.ProblemChange;
 
 /**
  * Specifies that an {@code int} property (or field) of a {@link PlanningEntity} determines
@@ -32,6 +33,7 @@
  * </ul>
  *
  * To pin the entire list and disallow any changes, use {@link PlanningPin} instead.
+ * The index must never change during planning; to change it, trigger a {@link ProblemChange}.
  *
  * <p>
  * Example: Assuming a list of values {@code [A, B, C]}:
@@ -47,6 +49,9 @@
  * If the same entity also specifies a {@link PlanningPin} and the pin is enabled,
  * any value of {@link PlanningPinToIndex} is ignored.
  * In other words, enabling {@link PlanningPin} pins the entire list without exception.
+ *
+ * @see PlanningPin Pin the entire entity.
+ * @see ProblemChange Use ProblemChange to trigger pinning changes.
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)

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

@@ -81,8 +81,9 @@
 public interface ProblemChange<Solution_> {
 
     /**
-     * Do the change on the {@link PlanningSolution}. Every modification to the {@link PlanningSolution} must
-     * be done via the {@link ProblemChangeDirector}, otherwise the {@link Score} calculation will be corrupted.
+     * Do the change on the {@link PlanningSolution}.
+     * Every modification to the {@link PlanningSolution} must be done via the {@link ProblemChangeDirector},
+     * otherwise the {@link Score} calculation will be corrupted.
      *
      * @param workingSolution the {@link PlanningSolution working solution} which contains the problem facts
      *        (and {@link PlanningEntity planning entities}) to change

core/src/main/java/ai/timefold/solver/core/impl/bavet/AbstractSession.java

@@ -2,18 +2,20 @@
 
 import java.util.IdentityHashMap;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.impl.bavet.uni.AbstractForEachUniNode;
 import ai.timefold.solver.core.impl.bavet.uni.AbstractForEachUniNode.LifecycleOperation;
+import ai.timefold.solver.core.impl.domain.variable.supply.SupplyManager;
 
-public abstract class AbstractSession {
+public abstract class AbstractSession implements AutoCloseable {
 
     private final NodeNetwork nodeNetwork;
-    private final Map<Class<?>, AbstractForEachUniNode<Object, Object>[]> initializeEffectiveClassToNodeArrayMap;
-    private final Map<Class<?>, AbstractForEachUniNode<Object, Object>[]> insertEffectiveClassToNodeArrayMap;
-    private final Map<Class<?>, AbstractForEachUniNode<Object, Object>[]> updateEffectiveClassToNodeArrayMap;
-    private final Map<Class<?>, AbstractForEachUniNode<Object, Object>[]> retractEffectiveClassToNodeArrayMap;
+    private final Map<Class<?>, AbstractForEachUniNode.InitializableForEachNode<Object>[]> initializeEffectiveClassToNodeArrayMap;
+    private final Map<Class<?>, AbstractForEachUniNode<Object>[]> insertEffectiveClassToNodeArrayMap;
+    private final Map<Class<?>, AbstractForEachUniNode<Object>[]> updateEffectiveClassToNodeArrayMap;
+    private final Map<Class<?>, AbstractForEachUniNode<Object>[]> retractEffectiveClassToNodeArrayMap;
 
     protected AbstractSession(NodeNetwork nodeNetwork) {
         this.nodeNetwork = nodeNetwork;
@@ -23,9 +25,9 @@ protected AbstractSession(NodeNetwork nodeNetwork) {
         this.retractEffectiveClassToNodeArrayMap = new IdentityHashMap<>(nodeNetwork.forEachNodeCount());
     }
 
-    public final void initialize(Object workingSolution) {
-        for (var node : findNodes(PlanningSolution.class, LifecycleOperation.INITIALIZE)) {
-            node.initialize(workingSolution);
+    public final void initialize(Object workingSolution, SupplyManager supplyManager) {
+        for (var node : findInitializableNodes()) {
+            node.initialize(workingSolution, supplyManager);
         }
     }
 
@@ -37,9 +39,8 @@ public final void insert(Object fact) {
     }
 
     @SuppressWarnings("unchecked")
-    private AbstractForEachUniNode<Object, Object>[] findNodes(Class<?> factClass, LifecycleOperation lifecycleOperation) {
+    private AbstractForEachUniNode<Object>[] findNodes(Class<?> factClass, LifecycleOperation lifecycleOperation) {
         var effectiveClassToNodeArrayMap = switch (lifecycleOperation) {
-            case INITIALIZE -> initializeEffectiveClassToNodeArrayMap;
             case INSERT -> insertEffectiveClassToNodeArrayMap;
             case UPDATE -> updateEffectiveClassToNodeArrayMap;
             case RETRACT -> retractEffectiveClassToNodeArrayMap;
@@ -55,6 +56,29 @@ private AbstractForEachUniNode<Object, Object>[] findNodes(Class<?> factClass, L
         return nodeArray;
     }
 
+    @SuppressWarnings("unchecked")
+    private AbstractForEachUniNode.InitializableForEachNode<Object>[] findInitializableNodes() {
+        // There will only be one solution class in the problem.
+        // Therefore we do not need to know what it is, and using the annotation class will serve as a unique key.
+        var factClass = PlanningSolution.class;
+        var effectiveClassToNodeArrayMap = initializeEffectiveClassToNodeArrayMap;
+        // Map.computeIfAbsent() would have created lambdas on the hot path, this will not.
+        var nodeArray = effectiveClassToNodeArrayMap.get(factClass);
+        if (nodeArray == null) {
+            nodeArray = nodeNetwork.getForEachNodes(factClass)
+                    .flatMap(node -> {
+                        if (node instanceof AbstractForEachUniNode.InitializableForEachNode<?> initializableForEachNode) {
+                            return Stream.of(initializableForEachNode);
+                        } else {
+                            return Stream.empty();
+                        }
+                    })
+                    .toArray(AbstractForEachUniNode.InitializableForEachNode[]::new);
+            effectiveClassToNodeArrayMap.put(factClass, nodeArray);
+        }
+        return nodeArray;
+    }
+
     public final void update(Object fact) {
         var factClass = fact.getClass();
         for (var node : findNodes(factClass, LifecycleOperation.UPDATE)) {
@@ -73,4 +97,13 @@ public void settle() {
         nodeNetwork.settle();
     }
 
+    @Override
+    public final void close() {
+        for (var node : findInitializableNodes()) {
+            // Initializable nodes get a supply manager, fair to assume they will be demanding supplies.
+            // Give them the opportunity to cancel those demands.
+            node.close();
+        }
+    }
+
 }

core/src/main/java/ai/timefold/solver/core/impl/bavet/NodeNetwork.java

@@ -19,7 +19,7 @@
  * @param layeredNodes nodes grouped first by their layer, then by their index within the layer;
  *        propagation needs to happen in this order.
  */
-public record NodeNetwork(Map<Class<?>, List<AbstractForEachUniNode<?, ?>>> declaredClassToNodeMap,
+public record NodeNetwork(Map<Class<?>, List<AbstractForEachUniNode<?>>> declaredClassToNodeMap,
         Propagator[][] layeredNodes) {
 
     public static final NodeNetwork EMPTY = new NodeNetwork(Map.of(), new Propagator[0][0]);
@@ -32,7 +32,7 @@ public int layerCount() {
         return layeredNodes.length;
     }
 
-    public Stream<AbstractForEachUniNode<?, ?>> getForEachNodes(Class<?> factClass) {
+    public Stream<AbstractForEachUniNode<?>> getForEachNodes(Class<?> factClass) {
         // The node needs to match the fact, or the node needs to be applicable to the entire solution.
         // The latter is for FromSolution nodes.
         return declaredClassToNodeMap.entrySet()

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

@@ -47,7 +47,7 @@ public void addNode(AbstractNode node, Stream_ creator) {
     public void addNode(AbstractNode node, Stream_ creator, Stream_ parent) {
         reversedNodeList.add(node);
         nodeCreatorMap.put(node, creator);
-        if (!(node instanceof AbstractForEachUniNode<?, ?>)) {
+        if (!(node instanceof AbstractForEachUniNode<?>)) {
             if (parent == null) {
                 throw new IllegalStateException("Impossible state: The node (%s) has no parent (%s)."
                         .formatted(node, parent));
@@ -148,7 +148,7 @@ public AbstractNode findParentNode(Stream_ childNodeCreator) {
     }
 
     public static NodeNetwork buildNodeNetwork(List<AbstractNode> nodeList,
-            Map<Class<?>, List<AbstractForEachUniNode<?, ?>>> declaredClassToNodeMap) {
+            Map<Class<?>, List<AbstractForEachUniNode<?>>> declaredClassToNodeMap) {
         var layerMap = new TreeMap<Long, List<Propagator>>();
         for (var node : nodeList) {
             layerMap.computeIfAbsent(node.getLayerIndex(), k -> new ArrayList<>())
@@ -206,7 +206,7 @@ public <BuildHelper_ extends AbstractNodeBuildHelper<Stream_>> List<AbstractNode
     @SuppressWarnings("unchecked")
     private static <Stream_ extends BavetStream> long determineLayerIndex(AbstractNode node,
             AbstractNodeBuildHelper<Stream_> buildHelper) {
-        if (node instanceof AbstractForEachUniNode<?, ?>) { // ForEach nodes, and only they, are in layer 0.
+        if (node instanceof AbstractForEachUniNode<?>) { // ForEach nodes, and only they, are in layer 0.
             return 0;
         } else if (node instanceof AbstractTwoInputNode<?, ?> joinNode) {
             var nodeCreator = (BavetStreamBinaryOperation<?>) buildHelper.getNodeCreatingStream(joinNode);

core/src/main/java/ai/timefold/solver/core/impl/bavet/uni/AbstractForEachUniNode.java

@@ -9,6 +9,7 @@
 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.bavet.common.tuple.UniTuple;
+import ai.timefold.solver.core.impl.domain.variable.supply.SupplyManager;
 
 import org.jspecify.annotations.NullMarked;
 
@@ -21,9 +22,9 @@
  * @param <A>
  */
 @NullMarked
-public abstract sealed class AbstractForEachUniNode<Solution_, A>
+public abstract sealed class AbstractForEachUniNode<A>
         extends AbstractNode
-        permits ForEachExcludingUnassignedUniNode, ForEachIncludingUnassignedUniNode {
+        permits ForEachExcludingUnassignedUniNode, ForEachExcludingPinnedUniNode, ForEachIncludingUnassignedUniNode {
 
     private final Class<A> forEachClass;
     private final int outputStoreSize;
@@ -37,8 +38,6 @@ protected AbstractForEachUniNode(Class<A> forEachClass, TupleLifecycle<UniTuple<
         this.propagationQueue = new StaticPropagationQueue<>(nextNodesTupleLifecycle);
     }
 
-    public abstract void initialize(Solution_ workingSolution);
-
     public void insert(A a) {
         var tuple = new UniTuple<>(a, outputStoreSize);
         var old = tupleMap.put(a, tuple);
@@ -115,10 +114,6 @@ public final String toString() {
      * on tuples within a node in Bavet.
      */
     public enum LifecycleOperation {
-        /**
-         * Called when initializing a new working solution.
-         */
-        INITIALIZE,
         /**
          * Represents the operation of inserting a new tuple into the node.
          * This operation is typically performed when a new fact is added to the working solution
@@ -140,4 +135,13 @@ public enum LifecycleOperation {
         RETRACT
     }
 
+    public interface InitializableForEachNode<Solution_> extends AutoCloseable {
+
+        void initialize(Solution_ workingSolution, SupplyManager supplyManager);
+
+        @Override
+        void close(); // Drop the checked exception.
+
+    }
+
 }