chore: deprecate the chained variable

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

@@ -15,7 +15,10 @@
  * variable.
  * <p>
  * It is specified on a getter of a java bean property (or a field) of a {@link PlanningEntity} class.
+ * 
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)
 public @interface AnchorShadowVariable {

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

@@ -56,7 +56,9 @@
      * as specified by {@link PlanningVariableGraphType}.
      *
      * @return never null, defaults to {@link PlanningVariableGraphType#NONE}
+     * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
      */
+    @Deprecated(forRemoval = true, since = "1.31.0")
     PlanningVariableGraphType graphType() default PlanningVariableGraphType.NONE;
 
     /**

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

@@ -1,5 +1,9 @@
 package ai.timefold.solver.core.api.domain.variable;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public enum PlanningVariableGraphType {
     /**
      * This is the default.

core/src/main/java/ai/timefold/solver/core/config/heuristic/selector/move/generic/chained/KOptMoveSelectorConfig.java

@@ -5,6 +5,7 @@
 import jakarta.xml.bind.annotation.XmlElement;
 import jakarta.xml.bind.annotation.XmlType;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig;
@@ -17,11 +18,12 @@
  * THIS CLASS IS EXPERIMENTAL AND UNSUPPORTED.
  * Backward compatibility is not guaranteed.
  * It's NOT DOCUMENTED because we'll only document it when it actually works in more than 1 use case.
- *
  * Do not use.
  *
  * @see TailChainSwapMoveSelectorConfig
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 @XmlType(propOrder = {
         "entitySelectorConfig",
         "valueSelectorConfig"

core/src/main/java/ai/timefold/solver/core/config/heuristic/selector/move/generic/chained/SubChainChangeMoveSelectorConfig.java

@@ -5,6 +5,7 @@
 import jakarta.xml.bind.annotation.XmlElement;
 import jakarta.xml.bind.annotation.XmlType;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.value.chained.SubChainSelectorConfig;
@@ -13,6 +14,10 @@
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 @XmlType(propOrder = {
         "entityClass",
         "subChainSelectorConfig",

core/src/main/java/ai/timefold/solver/core/config/heuristic/selector/move/generic/chained/SubChainSwapMoveSelectorConfig.java

@@ -5,13 +5,18 @@
 import jakarta.xml.bind.annotation.XmlElement;
 import jakarta.xml.bind.annotation.XmlType;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.value.chained.SubChainSelectorConfig;
 import ai.timefold.solver.core.config.util.ConfigUtils;
 
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 @XmlType(propOrder = {
         "entityClass",
         "subChainSelectorConfig",

core/src/main/java/ai/timefold/solver/core/config/heuristic/selector/move/generic/chained/TailChainSwapMoveSelectorConfig.java

@@ -6,6 +6,7 @@
 import jakarta.xml.bind.annotation.XmlElement;
 import jakarta.xml.bind.annotation.XmlType;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig;
 import ai.timefold.solver.core.config.heuristic.selector.move.NearbyAutoConfigurationEnabled;
@@ -19,7 +20,10 @@
 
 /**
  * Also known as a 2-opt move selector config.
+ * 
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 @XmlType(propOrder = {
         "entitySelectorConfig",
         "valueSelectorConfig"

core/src/main/java/ai/timefold/solver/core/config/heuristic/selector/move/generic/chained/package-info.java

@@ -1,3 +1,8 @@
+/**
+ * @deprecated Chained variable is deprecated. Use {@link ai.timefold.solver.core.api.domain.variable.PlanningListVariable list
+ *             variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 @XmlSchema(
         namespace = SolverConfig.XML_NAMESPACE,
         elementFormDefault = XmlNsForm.QUALIFIED)

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/ChainedChangeMove.java

@@ -3,6 +3,7 @@
 import java.util.Objects;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableSupply;
@@ -11,7 +12,9 @@
 
 /**
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class ChainedChangeMove<Solution_> extends ChangeMove<Solution_> {
 
     protected final Object oldTrailingEntity;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/ChainedSwapMove.java

@@ -5,6 +5,7 @@
 import java.util.Objects;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.BasicVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
@@ -14,7 +15,9 @@
 
 /**
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class ChainedSwapMove<Solution_> extends SwapMove<Solution_> {
 
     protected final List<Object> oldLeftTrailingEntityList;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/KOptMove.java

@@ -8,6 +8,7 @@
 import java.util.Objects;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.anchor.AnchorVariableSupply;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
@@ -17,7 +18,9 @@
 
 /**
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class KOptMove<Solution_> extends AbstractMove<Solution_> {
 
     protected final GenuineVariableDescriptor<Solution_> variableDescriptor;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/KOptMoveSelector.java

@@ -3,6 +3,7 @@
 import java.util.Arrays;
 import java.util.Iterator;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.impl.domain.variable.anchor.AnchorVariableDemand;
 import ai.timefold.solver.core.impl.domain.variable.anchor.AnchorVariableSupply;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.BasicVariableDescriptor;
@@ -17,6 +18,10 @@
 import ai.timefold.solver.core.impl.heuristic.selector.value.ValueSelector;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class KOptMoveSelector<Solution_> extends GenericMoveSelector<Solution_> {
 
     protected final EntitySelector<Solution_> entitySelector;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/KOptMoveSelectorFactory.java

@@ -2,6 +2,7 @@
 
 import java.util.Objects;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.config.heuristic.selector.common.SelectionCacheType;
 import ai.timefold.solver.core.config.heuristic.selector.common.SelectionOrder;
 import ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig;
@@ -15,6 +16,10 @@
 import ai.timefold.solver.core.impl.heuristic.selector.value.ValueSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.ValueSelectorFactory;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class KOptMoveSelectorFactory<Solution_>
         extends AbstractMoveSelectorFactory<Solution_, KOptMoveSelectorConfig> {
 

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainChangeMove.java

@@ -4,7 +4,7 @@
 import java.util.Collections;
 import java.util.Objects;
 
-import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableSupply;
@@ -13,8 +13,9 @@
 import ai.timefold.solver.core.impl.score.director.VariableDescriptorAwareScoreDirector;
 
 /**
- * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainChangeMove<Solution_> extends AbstractMove<Solution_> {
 
     protected final SubChain subChain;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainChangeMoveSelector.java

@@ -3,6 +3,7 @@
 import java.util.Collections;
 import java.util.Iterator;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableDemand;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableSupply;
 import ai.timefold.solver.core.impl.domain.variable.supply.SupplyManager;
@@ -14,6 +15,10 @@
 import ai.timefold.solver.core.impl.heuristic.selector.value.chained.SubChainSelector;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainChangeMoveSelector<Solution_> extends GenericMoveSelector<Solution_> {
 
     protected final SubChainSelector<Solution_> subChainSelector;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainChangeMoveSelectorFactory.java

@@ -2,6 +2,7 @@
 
 import java.util.Objects;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.config.heuristic.selector.common.SelectionCacheType;
 import ai.timefold.solver.core.config.heuristic.selector.common.SelectionOrder;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainChangeMoveSelectorConfig;
@@ -17,6 +18,10 @@
 import ai.timefold.solver.core.impl.heuristic.selector.value.chained.SubChainSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.chained.SubChainSelectorFactory;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainChangeMoveSelectorFactory<Solution_>
         extends AbstractMoveSelectorFactory<Solution_, SubChainChangeMoveSelectorConfig> {
 

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainReversingChangeMove.java

@@ -4,7 +4,7 @@
 import java.util.Collections;
 import java.util.Objects;
 
-import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.VariableDescriptor;
@@ -14,8 +14,9 @@
 import ai.timefold.solver.core.impl.score.director.VariableDescriptorAwareScoreDirector;
 
 /**
- * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainReversingChangeMove<Solution_> extends AbstractMove<Solution_> {
 
     protected final SubChain subChain;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainReversingSwapMove.java

@@ -8,6 +8,7 @@
 import java.util.Objects;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableSupply;
@@ -21,7 +22,9 @@
  * This {@link Move} is not cacheable.
  *
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainReversingSwapMove<Solution_> extends AbstractMove<Solution_> {
 
     private final GenuineVariableDescriptor<Solution_> variableDescriptor;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainSwapMove.java

@@ -7,6 +7,7 @@
 import java.util.Set;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableSupply;
@@ -20,7 +21,9 @@
  * This {@link Move} is not cacheable.
  *
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainSwapMove<Solution_> extends AbstractMove<Solution_> {
 
     protected final GenuineVariableDescriptor<Solution_> variableDescriptor;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainSwapMoveSelector.java

@@ -2,6 +2,7 @@
 
 import java.util.Iterator;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableDemand;
 import ai.timefold.solver.core.impl.domain.variable.inverserelation.SingletonInverseVariableSupply;
@@ -14,6 +15,10 @@
 import ai.timefold.solver.core.impl.heuristic.selector.value.chained.SubChainSelector;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainSwapMoveSelector<Solution_> extends GenericMoveSelector<Solution_> {
 
     protected final SubChainSelector<Solution_> leftSubChainSelector;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/SubChainSwapMoveSelectorFactory.java

@@ -2,6 +2,7 @@
 
 import java.util.Objects;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.config.heuristic.selector.common.SelectionCacheType;
 import ai.timefold.solver.core.config.heuristic.selector.common.SelectionOrder;
 import ai.timefold.solver.core.config.heuristic.selector.move.generic.chained.SubChainSwapMoveSelectorConfig;
@@ -13,6 +14,10 @@
 import ai.timefold.solver.core.impl.heuristic.selector.value.chained.SubChainSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.chained.SubChainSelectorFactory;
 
+/**
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
+ */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class SubChainSwapMoveSelectorFactory<Solution_>
         extends AbstractMoveSelectorFactory<Solution_, SubChainSwapMoveSelectorConfig> {
 

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/TailChainSwapMove.java

@@ -6,6 +6,7 @@
 import java.util.Objects;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.variable.anchor.AnchorVariableSupply;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.GenuineVariableDescriptor;
@@ -17,7 +18,9 @@
  * Also known as a 2-opt move.
  *
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class TailChainSwapMove<Solution_> extends AbstractMove<Solution_> {
 
     protected final GenuineVariableDescriptor<Solution_> variableDescriptor;

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/generic/chained/TailChainSwapMoveSelector.java

@@ -2,6 +2,7 @@
 
 import java.util.Iterator;
 
+import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.impl.domain.variable.anchor.AnchorVariableDemand;
 import ai.timefold.solver.core.impl.domain.variable.anchor.AnchorVariableSupply;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.BasicVariableDescriptor;
@@ -20,7 +21,10 @@
 
 /**
  * Also known as a 2-opt move selector.
+ * 
+ * @deprecated Chained variable is deprecated. Use {@link PlanningListVariable list variable} instead.
  */
+@Deprecated(forRemoval = true, since = "1.31.0")
 public class TailChainSwapMoveSelector<Solution_> extends GenericMoveSelector<Solution_> {
 
     protected final EntitySelector<Solution_> entitySelector;