chore: expose Move Streams as a experimental feature (#1493)

This feature is under heavy development.
Any use is discouraged.

Author: triceo

benchmark/src/main/java/ai/timefold/solver/benchmark/config/blueprint/SolverBenchmarkBluePrintType.java

@@ -11,7 +11,6 @@
 import ai.timefold.solver.core.config.localsearch.LocalSearchPhaseConfig;
 import ai.timefold.solver.core.config.localsearch.LocalSearchType;
 import ai.timefold.solver.core.config.phase.PhaseConfig;
-import ai.timefold.solver.core.config.solver.PreviewFeature;
 import ai.timefold.solver.core.config.solver.SolverConfig;
 
 import org.jspecify.annotations.NonNull;
@@ -72,7 +71,7 @@ private List<SolverBenchmarkConfig> buildEveryLocalSearchType(ConstructionHeuris
         LocalSearchType[] lsTypes = LocalSearchType.getBluePrintTypes();
         List<SolverBenchmarkConfig> solverBenchmarkConfigList = new ArrayList<>(lsTypes.length);
         for (LocalSearchType lsType : lsTypes) {
-            if (PreviewFeature.DIVERSIFIED_LATE_ACCEPTANCE != null && lsType == LocalSearchType.DIVERSIFIED_LATE_ACCEPTANCE) {
+            if (lsType == LocalSearchType.DIVERSIFIED_LATE_ACCEPTANCE) {
                 // When the preview feature is removed, this will fail at compile time
                 // and the code will have to be adjusted.
                 // Most likely, the preview feature will be promoted to a regular feature,

benchmark/src/main/resources/benchmark.xsd

@@ -2381,6 +2381,9 @@
           </xs:choice>
 
 
+          <xs:element minOccurs="0" name="moveProvidersClass" type="xs:string"/>
+                              
+          
           <xs:element minOccurs="0" name="acceptor" type="tns:localSearchAcceptorConfig"/>
 
 
@@ -2604,6 +2607,9 @@
 
 
       <xs:enumeration value="PLANNING_SOLUTION_DIFF"/>
+                  
+      
+      <xs:enumeration value="MOVE_STREAMS"/>
 
 
     </xs:restriction>

core/src/build/revapi-differences.json

@@ -140,6 +140,17 @@
           "new": "class ai.timefold.solver.core.config.phase.custom.CustomPhaseConfig",
           "annotation": "@org.jspecify.annotations.NullMarked",
           "justification": "Less verbose nullability, no practical impact."
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.attributeValueChanged",
+          "old": "class ai.timefold.solver.core.config.localsearch.LocalSearchPhaseConfig",
+          "new": "class ai.timefold.solver.core.config.localsearch.LocalSearchPhaseConfig",
+          "annotationType": "jakarta.xml.bind.annotation.XmlType",
+          "attribute": "propOrder",
+          "oldValue": "{\"localSearchType\", \"moveSelectorConfig\", \"acceptorConfig\", \"foragerConfig\"}",
+          "newValue": "{\"localSearchType\", \"moveSelectorConfig\", \"moveProvidersClass\", \"acceptorConfig\", \"foragerConfig\"}",
+          "justification": "Move Streams arrives as a preview feature."
         }
       ]
     }

core/src/main/java/ai/timefold/solver/core/config/localsearch/LocalSearchPhaseConfig.java

@@ -27,14 +27,17 @@
 import ai.timefold.solver.core.config.localsearch.decider.acceptor.LocalSearchAcceptorConfig;
 import ai.timefold.solver.core.config.localsearch.decider.forager.LocalSearchForagerConfig;
 import ai.timefold.solver.core.config.phase.PhaseConfig;
+import ai.timefold.solver.core.config.solver.PreviewFeature;
 import ai.timefold.solver.core.config.util.ConfigUtils;
+import ai.timefold.solver.core.impl.move.streams.maybeapi.stream.MoveProviders;
 
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
 @XmlType(propOrder = {
         "localSearchType",
         "moveSelectorConfig",
+        "moveProvidersClass",
         "acceptorConfig",
         "foragerConfig"
 })
@@ -74,6 +77,7 @@ public class LocalSearchPhaseConfig extends PhaseConfig<LocalSearchPhaseConfig>
             @XmlElement(name = UnionMoveSelectorConfig.XML_ELEMENT_NAME, type = UnionMoveSelectorConfig.class)
     })
     private MoveSelectorConfig moveSelectorConfig = null;
+    private Class<? extends MoveProviders> moveProvidersClass = null;
     @XmlElement(name = "acceptor")
     private LocalSearchAcceptorConfig acceptorConfig = null;
     @XmlElement(name = "forager")
@@ -99,6 +103,22 @@ public void setMoveSelectorConfig(@Nullable MoveSelectorConfig moveSelectorConfi
         this.moveSelectorConfig = moveSelectorConfig;
     }
 
+    /**
+     * Part of {@link PreviewFeature#MOVE_STREAMS}.
+     */
+    @SuppressWarnings("unchecked")
+    public @Nullable <Solution_> Class<? extends MoveProviders<Solution_>> getMoveProvidersClass() {
+        return (Class<? extends MoveProviders<Solution_>>) moveProvidersClass;
+    }
+
+    /**
+     * Part of {@link PreviewFeature#MOVE_STREAMS}.
+     */
+    @SuppressWarnings("rawtypes")
+    public void setMoveProvidersClass(@Nullable Class<? extends MoveProviders> moveProvidersClass) {
+        this.moveProvidersClass = moveProvidersClass;
+    }
+
     public @Nullable LocalSearchAcceptorConfig getAcceptorConfig() {
         return acceptorConfig;
     }
@@ -129,6 +149,15 @@ public void setForagerConfig(@Nullable LocalSearchForagerConfig foragerConfig) {
         return this;
     }
 
+    /**
+     * Part of {@link PreviewFeature#MOVE_STREAMS}.
+     */
+    public @NonNull LocalSearchPhaseConfig
+            withMoveProvidersClass(@NonNull Class<? extends MoveProviders<?>> moveProviderClass) {
+        this.moveProvidersClass = moveProviderClass;
+        return this;
+    }
+
     public @NonNull LocalSearchPhaseConfig withAcceptorConfig(@NonNull LocalSearchAcceptorConfig acceptorConfig) {
         this.acceptorConfig = acceptorConfig;
         return this;
@@ -146,6 +175,8 @@ public void setForagerConfig(@Nullable LocalSearchForagerConfig foragerConfig) {
                 inheritedConfig.getLocalSearchType());
         setMoveSelectorConfig(ConfigUtils.inheritOverwritableProperty(
                 getMoveSelectorConfig(), inheritedConfig.getMoveSelectorConfig()));
+        setMoveProvidersClass(ConfigUtils.inheritOverwritableProperty(getMoveProvidersClass(),
+                inheritedConfig.getMoveProvidersClass()));
         acceptorConfig = ConfigUtils.inheritConfig(acceptorConfig, inheritedConfig.getAcceptorConfig());
         foragerConfig = ConfigUtils.inheritConfig(foragerConfig, inheritedConfig.getForagerConfig());
         return this;
@@ -164,6 +195,9 @@ public void visitReferencedClasses(@NonNull Consumer<Class<?>> classVisitor) {
         if (moveSelectorConfig != null) {
             moveSelectorConfig.visitReferencedClasses(classVisitor);
         }
+        if (moveProvidersClass != null) {
+            classVisitor.accept(moveProvidersClass);
+        }
         if (acceptorConfig != null) {
             acceptorConfig.visitReferencedClasses(classVisitor);
         }

core/src/main/java/ai/timefold/solver/core/config/localsearch/LocalSearchType.java

@@ -4,6 +4,8 @@
 
 import jakarta.xml.bind.annotation.XmlEnum;
 
+import ai.timefold.solver.core.config.solver.PreviewFeature;
+
 import org.jspecify.annotations.NonNull;
 
 @XmlEnum
@@ -12,6 +14,9 @@ public enum LocalSearchType {
     TABU_SEARCH,
     SIMULATED_ANNEALING,
     LATE_ACCEPTANCE,
+    /**
+     * See {@link PreviewFeature#DIVERSIFIED_LATE_ACCEPTANCE}.
+     */
     DIVERSIFIED_LATE_ACCEPTANCE,
     GREAT_DELUGE,
     VARIABLE_NEIGHBORHOOD_DESCENT;

core/src/main/java/ai/timefold/solver/core/config/localsearch/decider/acceptor/AcceptorType.java

@@ -4,14 +4,30 @@
 
 @XmlEnum
 public enum AcceptorType {
+
     HILL_CLIMBING,
-    ENTITY_TABU,
-    VALUE_TABU,
-    MOVE_TABU,
-    UNDO_MOVE_TABU,
+    ENTITY_TABU(true),
+    VALUE_TABU(true),
+    MOVE_TABU(true),
+    UNDO_MOVE_TABU(true),
     SIMULATED_ANNEALING,
     LATE_ACCEPTANCE,
     DIVERSIFIED_LATE_ACCEPTANCE,
     GREAT_DELUGE,
-    STEP_COUNTING_HILL_CLIMBING
+    STEP_COUNTING_HILL_CLIMBING;
+
+    private final boolean isTabu;
+
+    AcceptorType() {
+        this(false);
+    }
+
+    AcceptorType(boolean isTabu) {
+        this.isTabu = isTabu;
+    }
+
+    public boolean isTabu() {
+        return isTabu;
+    }
+
 }

core/src/main/java/ai/timefold/solver/core/config/solver/PreviewFeature.java

@@ -1,8 +1,37 @@
 package ai.timefold.solver.core.config.solver;
 
+/**
+ * Lists features available in Timefold Solver on a preview basis.
+ * These preview features are developed to the same standard as the rest of Timefold Solver.
+ * However, their APIs are not yet considered stable, pending user feedback.
+ * Any class, method, or field related to these features may change or be removed without prior notice,
+ * although we will strive to avoid this as much as possible.
+ * We encourage you to try these preview features and give us feedback on your experience with them.
+ * Please direct your feedback to our Github Discussions.
+ * 
+ * <p>
+ * This list is not constant and is evolving over time,
+ * with items being added and removed without warning.
+ * It should not be treated as part of our public API,
+ * just like the preview features themselves.
+ *
+ * @see <a href="https://github.com/TimefoldAI/timefold-solver/discussions">Timefold Solver Github Discussions</a>
+ */
 public enum PreviewFeature {
 
     DIVERSIFIED_LATE_ACCEPTANCE,
-    PLANNING_SOLUTION_DIFF
+    PLANNING_SOLUTION_DIFF,
+    /**
+     * Unlike other preview features, Move Streams are an active research project.
+     * It is intended to simplify the creation of custom moves, eventually replacing move selectors.
+     * The component is under heavy development, entirely undocumented, and many key features are yet to be delivered.
+     * Neither the API nor the feature set are complete, and any part can change or be removed at any time.
+     * 
+     * Move Streams will eventually stabilize and be promoted from a research project to a true preview feature.
+     * We only expose it now to be able to use it for experimentation and testing.
+     * As such, it is an exception to the rule;
+     * this preview feature is not finished, and it is not yet ready for feedback.
+     */
+    MOVE_STREAMS
 
 }