feat: enable sorting for CH with list variable

benchmark/src/main/resources/benchmark.xsd

@@ -890,9 +890,15 @@
           <xs:element minOccurs="0" name="sorterComparatorClass" type="xs:string"/>
 
 
+          <xs:element minOccurs="0" name="comparatorClass" type="xs:string"/>
+
+
           <xs:element minOccurs="0" name="sorterWeightFactoryClass" type="xs:string"/>
 
 
+          <xs:element minOccurs="0" name="comparatorFactoryClass" type="xs:string"/>
+
+
           <xs:element minOccurs="0" name="sorterOrder" type="tns:selectionSorterOrder"/>
 
 
@@ -1082,9 +1088,15 @@
           <xs:element minOccurs="0" name="sorterComparatorClass" type="xs:string"/>
 
 
+          <xs:element minOccurs="0" name="comparatorClass" type="xs:string"/>
+
+
           <xs:element minOccurs="0" name="sorterWeightFactoryClass" type="xs:string"/>
 
 
+          <xs:element minOccurs="0" name="comparatorFactoryClass" type="xs:string"/>
+
+
           <xs:element minOccurs="0" name="sorterOrder" type="tns:selectionSorterOrder"/>
 
 
@@ -1229,9 +1241,15 @@
           <xs:element minOccurs="0" name="sorterComparatorClass" type="xs:string"/>
 
 
+          <xs:element minOccurs="0" name="comparatorClass" type="xs:string"/>
+
+
           <xs:element minOccurs="0" name="sorterWeightFactoryClass" type="xs:string"/>
 
 
+          <xs:element minOccurs="0" name="comparatorFactoryClass" type="xs:string"/>
+
+
           <xs:element minOccurs="0" name="sorterOrder" type="tns:selectionSorterOrder"/>
 
 
@@ -2874,6 +2892,12 @@
 
 
       <xs:enumeration value="DECREASING_DIFFICULTY_IF_AVAILABLE"/>
+
+
+      <xs:enumeration value="DESCENDING"/>
+
+
+      <xs:enumeration value="DESCENDING_IF_AVAILABLE"/>
 
 
     </xs:restriction>
@@ -2901,6 +2925,18 @@
 
 
       <xs:enumeration value="DECREASING_STRENGTH_IF_AVAILABLE"/>
+
+
+      <xs:enumeration value="ASCENDING"/>
+
+
+      <xs:enumeration value="ASCENDING_IF_AVAILABLE"/>
+
+
+      <xs:enumeration value="DESCENDING"/>
+
+
+      <xs:enumeration value="DESCENDING_IF_AVAILABLE"/>
 
 
     </xs:restriction>

core/src/build/revapi-differences.json

@@ -348,6 +348,108 @@
           "oldValue": "{\"constructionHeuristicType\", \"entitySorterManner\", \"valueSorterManner\", \"entityPlacerConfig\", \"moveSelectorConfigList\", \"foragerConfig\"}",
           "newValue": "{\"constructionHeuristicType\", \"entitySorterManner\", \"valueSorterManner\", \"entityPlacerConfigList\", \"moveSelectorConfigList\", \"foragerConfig\"}",
           "justification": "New CH configuration with multiple placers"
+        },
+        {
+          "ignore": true,
+          "code": "java.method.returnTypeTypeParametersChanged",
+          "old": "method java.lang.Class<? extends ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorterWeightFactory> ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig::getSorterWeightFactoryClass()",
+          "new": "method java.lang.Class<? extends ai.timefold.solver.core.api.domain.common.ComparatorFactory> ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig::getSorterWeightFactoryClass()",
+          "justification": "New comparator factory class"
+        },
+        {
+          "ignore": true,
+          "code": "java.method.parameterTypeParameterChanged",
+          "old": "parameter void ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig::setSorterWeightFactoryClass(===java.lang.Class<? extends ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorterWeightFactory>===)",
+          "new": "parameter void ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig::setSorterWeightFactoryClass(===java.lang.Class<? extends ai.timefold.solver.core.api.domain.common.ComparatorFactory>===)",
+          "parameterIndex": "0",
+          "justification": "New comparator factory class"
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.attributeValueChanged",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig",
+          "annotationType": "jakarta.xml.bind.annotation.XmlType",
+          "attribute": "propOrder",
+          "oldValue": "{\"id\", \"mimicSelectorRef\", \"entityClass\", \"cacheType\", \"selectionOrder\", \"nearbySelectionConfig\", \"filterClass\", \"sorterManner\", \"sorterComparatorClass\", \"sorterWeightFactoryClass\", \"sorterOrder\", \"sorterClass\", \"probabilityWeightFactoryClass\", \"selectedCountLimit\"}",
+          "newValue": "{\"id\", \"mimicSelectorRef\", \"entityClass\", \"cacheType\", \"selectionOrder\", \"nearbySelectionConfig\", \"filterClass\", \"sorterManner\", \"sorterComparatorClass\", \"comparatorClass\", \"sorterWeightFactoryClass\", \"comparatorFactoryClass\", \"sorterOrder\", \"sorterClass\", \"probabilityWeightFactoryClass\", \"selectedCountLimit\"}",
+          "justification": "New comparator properties"
+        },
+        {
+          "ignore": true,
+          "code": "java.method.returnTypeTypeParametersChanged",
+          "old": "method java.lang.Class<? extends ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorterWeightFactory> ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>::getSorterWeightFactoryClass()",
+          "new": "method java.lang.Class<? extends ai.timefold.solver.core.api.domain.common.ComparatorFactory> ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>::getSorterWeightFactoryClass()",
+          "justification": "New comparator factory class"
+        },
+        {
+          "ignore": true,
+          "code": "java.method.parameterTypeParameterChanged",
+          "old": "parameter void ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>::setSorterWeightFactoryClass(===java.lang.Class<? extends ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorterWeightFactory>===)",
+          "new": "parameter void ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>::setSorterWeightFactoryClass(===java.lang.Class<? extends ai.timefold.solver.core.api.domain.common.ComparatorFactory>===)",
+          "parameterIndex": "0",
+          "justification": "New comparator factory class"
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.attributeValueChanged",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "annotationType": "jakarta.xml.bind.annotation.XmlType",
+          "attribute": "propOrder",
+          "oldValue": "{\"cacheType\", \"selectionOrder\", \"filterClass\", \"sorterComparatorClass\", \"sorterWeightFactoryClass\", \"sorterOrder\", \"sorterClass\", \"probabilityWeightFactoryClass\", \"selectedCountLimit\", \"fixedProbabilityWeight\"}",
+          "newValue": "{\"cacheType\", \"selectionOrder\", \"filterClass\", \"sorterComparatorClass\", \"comparatorClass\", \"sorterWeightFactoryClass\", \"comparatorFactoryClass\", \"sorterOrder\", \"sorterClass\", \"probabilityWeightFactoryClass\", \"selectedCountLimit\", \"fixedProbabilityWeight\"}",
+          "justification": "New comparator properties"
+        },
+        {
+          "ignore": true,
+          "code": "java.method.returnTypeTypeParametersChanged",
+          "old": "method java.lang.Class<? extends ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorterWeightFactory> ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig::getSorterWeightFactoryClass()",
+          "new": "method java.lang.Class<? extends ai.timefold.solver.core.api.domain.common.ComparatorFactory> ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig::getSorterWeightFactoryClass()",
+          "justification": "New comparator factory class"
+        },
+        {
+          "ignore": true,
+          "code": "java.method.parameterTypeParameterChanged",
+          "old": "parameter void ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig::setSorterWeightFactoryClass(===java.lang.Class<? extends ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorterWeightFactory>===)",
+          "new": "parameter void ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig::setSorterWeightFactoryClass(===java.lang.Class<? extends ai.timefold.solver.core.api.domain.common.ComparatorFactory>===)",
+          "parameterIndex": "0",
+          "justification": "New comparator factory class"
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.attributeValueChanged",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig",
+          "annotationType": "jakarta.xml.bind.annotation.XmlType",
+          "attribute": "propOrder",
+          "oldValue": "{\"id\", \"mimicSelectorRef\", \"downcastEntityClass\", \"variableName\", \"cacheType\", \"selectionOrder\", \"nearbySelectionConfig\", \"filterClass\", \"sorterManner\", \"sorterComparatorClass\", \"sorterWeightFactoryClass\", \"sorterOrder\", \"sorterClass\", \"probabilityWeightFactoryClass\", \"selectedCountLimit\"}",
+          "newValue": "{\"id\", \"mimicSelectorRef\", \"downcastEntityClass\", \"variableName\", \"cacheType\", \"selectionOrder\", \"nearbySelectionConfig\", \"filterClass\", \"sorterManner\", \"sorterComparatorClass\", \"comparatorClass\", \"sorterWeightFactoryClass\", \"comparatorFactoryClass\", \"sorterOrder\", \"sorterClass\", \"probabilityWeightFactoryClass\", \"selectedCountLimit\"}",
+          "justification": "New comparator properties"
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.added",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig",
+          "annotation": "@org.jspecify.annotations.NullMarked",
+          "justification": "Update config"
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.added",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_ extends ai.timefold.solver.core.config.heuristic.selector.move.MoveSelectorConfig<Config_>>",
+          "annotation": "@org.jspecify.annotations.NullMarked",
+          "justification": "Update config"
+        },
+        {
+          "ignore": true,
+          "code": "java.annotation.added",
+          "old": "class ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig",
+          "new": "class ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig",
+          "annotation": "@org.jspecify.annotations.NullMarked",
+          "justification": "Update config"
         }
       ]
     }

core/src/main/java/ai/timefold/solver/core/api/domain/common/ComparatorFactory.java

@@ -0,0 +1,47 @@
+package ai.timefold.solver.core.api.domain.common;
+
+import java.util.Comparator;
+
+import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
+import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.config.constructionheuristic.ConstructionHeuristicPhaseConfig;
+import ai.timefold.solver.core.config.heuristic.selector.entity.EntitySelectorConfig;
+import ai.timefold.solver.core.config.heuristic.selector.value.ValueSelectorConfig;
+import ai.timefold.solver.core.impl.heuristic.move.Move;
+import ai.timefold.solver.core.impl.heuristic.selector.Selector;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Creates a {@link Comparable} to decide the order of a collection of selections
+ * (a selection is a {@link PlanningEntity}, a planningValue, a {@link Move} or a {@link Selector}).
+ * The selections are then sorted by some specific metric,
+ * normally ascending unless it's configured descending.
+ * The property {@code sortManner},
+ * present in the selector configurations such as {@link ValueSelectorConfig} and {@link EntitySelectorConfig},
+ * specifies how the data will be sorted.
+ * Additionally,
+ * the property {@code constructionHeuristicType} from {@link ConstructionHeuristicPhaseConfig} can also configure how entities
+ * and values are sorted.
+ * <p>
+ * Implementations are expected to be stateless.
+ * The solver may choose to reuse instances.
+ *
+ * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
+ * @param <T> the selection type
+ *
+ * @see ValueSelectorConfig
+ * @see EntitySelectorConfig
+ * @see ConstructionHeuristicPhaseConfig
+ */
+@NullMarked
+@FunctionalInterface
+public interface ComparatorFactory<Solution_, T> {
+
+    /**
+     * @param solution never null, the {@link PlanningSolution} to which the selection belongs or applies to
+     * @return never null
+     */
+    Comparator<T> createComparator(Solution_ solution);
+
+}

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

@@ -7,6 +7,7 @@
 import java.lang.annotation.Target;
 import java.util.Comparator;
 
+import ai.timefold.solver.core.api.domain.common.ComparatorFactory;
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariable;
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorterWeightFactory;
@@ -34,6 +35,40 @@
 @Retention(RUNTIME)
 public @interface PlanningEntity {
 
+    /**
+     * Allows sorting a collection of planning entities for this variable.
+     * Some algorithms perform better when the entities are sorted based on specific metrics.
+     * <p>
+     * The {@link Comparator} should sort the data in ascending order.
+     * For example, prioritize three vehicles by sorting them based on their capacity:
+     * Vehicle C (4 people), Vehicle A (6 people), Vehicle B (32 people)
+     * <p>
+     * Do not use together with {@link #comparatorFactoryClass()}.
+     *
+     * @return {@link PlanningVariable.NullComparator} when it is null (workaround for annotation limitation)
+     * @see #comparatorFactoryClass()
+     */
+    Class<? extends Comparator> comparatorClass() default NullComparator.class;
+
+    interface NullComparator<T> extends Comparator<T> {
+    }
+
+    /**
+     * The {@link ComparatorFactory} alternative for {@link #comparatorClass()}.
+     * <p>
+     * Differs from {@link #comparatorClass()}
+     * because it allows accessing the current solution when creating the comparator.
+     * <p>
+     * Do not use together with {@link #comparatorClass()}.
+     *
+     * @return {@link NullComparatorFactory} when it is null (workaround for annotation limitation)
+     * @see #comparatorClass()
+     */
+    Class<? extends ComparatorFactory> comparatorFactoryClass() default NullComparatorFactory.class;
+
+    interface NullComparatorFactory<Solution_, T> extends ComparatorFactory<Solution_, T> {
+    }
+
     /**
      * 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).
@@ -50,7 +85,7 @@
 
     /**
      * Workaround for annotation limitation in {@link #pinningFilter()}.
-     * 
+     *
      * @deprecated Prefer using {@link PlanningPin}.
      */
     @Deprecated(forRemoval = true, since = "1.23.0")
@@ -69,27 +104,45 @@ interface NullPinningFilter extends PinningFilter {
      * <p>
      * Do not use together with {@link #difficultyWeightFactoryClass()}.
      *
+     * @deprecated Deprecated in favor of {@link #comparatorClass()}.
+     *
      * @return {@link NullDifficultyComparator} when it is null (workaround for annotation limitation)
      * @see #difficultyWeightFactoryClass()
      */
+    @Deprecated(forRemoval = true, since = "1.28.0")
     Class<? extends Comparator> difficultyComparatorClass() default NullDifficultyComparator.class;
 
-    /** Workaround for annotation limitation in {@link #difficultyComparatorClass()}. */
-    interface NullDifficultyComparator extends Comparator {
+    /**
+     * Workaround for annotation limitation in {@link #difficultyComparatorClass()}.
+     *
+     * @deprecated Deprecated in favor of {@link NullComparator}.
+     */
+    @Deprecated(forRemoval = true, since = "1.28.0")
+    interface NullDifficultyComparator<T> extends NullComparator<T> {
     }
 
     /**
      * The {@link SelectionSorterWeightFactory} alternative for {@link #difficultyComparatorClass()}.
      * <p>
      * Do not use together with {@link #difficultyComparatorClass()}.
      *
+     * @deprecated Deprecated in favor of {@link #comparatorFactoryClass()}.
+     *
      * @return {@link NullDifficultyWeightFactory} when it is null (workaround for annotation limitation)
      * @see #difficultyComparatorClass()
      */
+    @Deprecated(forRemoval = true, since = "1.28.0")
     Class<? extends SelectionSorterWeightFactory> difficultyWeightFactoryClass() default NullDifficultyWeightFactory.class;
 
-    /** Workaround for annotation limitation in {@link #difficultyWeightFactoryClass()}. */
-    interface NullDifficultyWeightFactory extends SelectionSorterWeightFactory {
+    /**
+     * Workaround for annotation limitation in {@link #difficultyWeightFactoryClass()}.
+     *
+     * @deprecated Deprecated in favor of {@link NullComparatorFactory}.
+     */
+    @Deprecated(forRemoval = true, since = "1.28.0")
+    interface NullDifficultyWeightFactory<Solution_, T>
+            extends SelectionSorterWeightFactory<Solution_, T>,
+            NullComparatorFactory<Solution_, T> {
     }
 
 }