chore: add new basic var sorting setting

Author: zepfred

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

@@ -8,6 +8,7 @@
 import java.lang.annotation.Target;
 import java.util.Comparator;
 
+import ai.timefold.solver.core.api.domain.common.SorterFactory;
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeProvider;
@@ -78,11 +79,29 @@
  * <p>
  * Do not use together with {@link #strengthWeightFactoryClass()}.
  *
+ * @deprecated Deprecated in favor of {@link #comparatorClass()}.
+ *
  * @return {@link NullStrengthComparator} when it is null (workaround for annotation limitation)
  * @see #strengthWeightFactoryClass()
  */
+ @Deprecated(forRemoval = true, since = "1.28.0")
  Class<? extends Comparator> strengthComparatorClass() default NullStrengthComparator.class;
 
+ /**
+ * Allows sorting a collection of planning values for this variable.
+ * Some algorithms perform better when the values are sorted based on specific metrics.
+ * <p>
+ * The {@link Comparator} should sort the data in ascending order.
+ * For example, prioritize three visits by sorting them based on their importance:
+ * Visit C (SMALL_PRIORITY), Visit A (MEDIUM_PRIORITY), Visit B (HIGH_PRIORITY)
+ * <p>
+ * Do not use together with {@link #comparatorFactoryClass()}.
+ *
+ * @return {@link NullComparator} when it is null (workaround for annotation limitation)
+ * @see #comparatorFactoryClass()
+ */
+ Class<? extends Comparator> comparatorClass() default NullComparator.class;
+
  /** Workaround for annotation limitation in {@link #strengthComparatorClass()}. */
  interface NullStrengthComparator extends NullComparator {
  }
@@ -95,11 +114,24 @@ interface NullComparator extends Comparator {
  * <p>
  * Do not use together with {@link #strengthComparatorClass()}.
  *
+ * @deprecated Deprecated in favor of {@link #comparatorFactoryClass()}.
+ *
  * @return {@link NullStrengthWeightFactory} when it is null (workaround for annotation limitation)
  * @see #strengthComparatorClass()
  */
+ @Deprecated(forRemoval = true, since = "1.28.0")
  Class<? extends SelectionSorterWeightFactory> strengthWeightFactoryClass() default NullStrengthWeightFactory.class;
 
+ /**
+ * The {@link SorterFactory} alternative for {@link #comparatorClass()}.
+ * <p>
+ * Do not use together with {@link #comparatorClass()}.
+
+ * @return {@link NullComparatorFactory} when it is null (workaround for annotation limitation)
+ * @see #comparatorClass()
+ */
+ Class<? extends SorterFactory> comparatorFactoryClass() default NullComparatorFactory.class;
+
  /** Workaround for annotation limitation in {@link #strengthWeightFactoryClass()}. */
  interface NullStrengthWeightFactory extends NullComparatorFactory {
  }

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/descriptor/BasicVariableDescriptor.java

@@ -1,5 +1,6 @@
 package ai.timefold.solver.core.impl.domain.variable.descriptor;
 
+import ai.timefold.solver.core.api.domain.common.SorterFactory;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariable;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariableGraphType;
 import ai.timefold.solver.core.impl.domain.common.accessor.MemberAccessor;
@@ -8,6 +9,8 @@
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionFilter;
 import ai.timefold.solver.core.impl.heuristic.selector.value.decorator.MovableChainedTrailingValueFilter;
 
+import java.util.Comparator;
+
 public final class BasicVariableDescriptor<Solution_> extends GenuineVariableDescriptor<Solution_> {
 
  private SelectionFilter<Solution_, Object> movableChainedTrailingValueFilter;
@@ -41,8 +44,60 @@ protected void processPropertyAnnotations(DescriptorPolicy descriptorPolicy) {
  processAllowsUnassigned(planningVariableAnnotation);
  processChained(planningVariableAnnotation);
  processValueRangeRefs(descriptorPolicy, planningVariableAnnotation.valueRangeProviderRefs());
- processSorting("strengthComparatorClass", planningVariableAnnotation.strengthComparatorClass(),
- "strengthWeightFactoryClass", planningVariableAnnotation.strengthWeightFactoryClass());
+ var sortingProperties = assertSortingProperties(planningVariableAnnotation);
+ processSorting(sortingProperties.comparatorPropertyName(), sortingProperties.comparatorClass(),
+ sortingProperties.comparatorFactoryPropertyName(), sortingProperties.comparatorFactoryClass());
+ }
+
+ private SortingProperties assertSortingProperties(PlanningVariable planningVariableAnnotation) {
+ // Comparator property
+ var strengthComparatorClass = planningVariableAnnotation.strengthComparatorClass();
+ var comparatorClass = planningVariableAnnotation.comparatorClass();
+ if (strengthComparatorClass != null
+ && PlanningVariable.NullComparator.class.isAssignableFrom(strengthComparatorClass)) {
+ strengthComparatorClass = null;
+ }
+ if (comparatorClass != null && PlanningVariable.NullComparator.class.isAssignableFrom(comparatorClass)) {
+ comparatorClass = null;
+ }
+ if (strengthComparatorClass != null && comparatorClass != null) {
+ throw new IllegalStateException(
+ "The entityClass (%s) property (%s) cannot have a %s (%s) and a %s (%s) at the same time.".formatted(
+ entityDescriptor.getEntityClass(), variableMemberAccessor.getName(), "strengthComparatorClass",
+ strengthComparatorClass.getName(), "comparatorClass", comparatorClass.getName()));
+ }
+ // Comparator factory property
+ var strengthWeightFactoryClass = planningVariableAnnotation.strengthWeightFactoryClass();
+ var comparatorFactoryClass = planningVariableAnnotation.comparatorFactoryClass();
+ if (strengthWeightFactoryClass != null
+ && PlanningVariable.NullComparatorFactory.class.isAssignableFrom(strengthWeightFactoryClass)) {
+ strengthWeightFactoryClass = null;
+ }
+ if (comparatorFactoryClass != null
+ && PlanningVariable.NullComparatorFactory.class.isAssignableFrom(comparatorFactoryClass)) {
+ comparatorFactoryClass = null;
+ }
+ if (strengthWeightFactoryClass != null && comparatorFactoryClass != null) {
+ throw new IllegalStateException(
+ "The entityClass (%s) property (%s) cannot have a %s (%s) and a %s (%s) at the same time.".formatted(
+ entityDescriptor.getEntityClass(), variableMemberAccessor.getName(), "strengthWeightFactoryClass",
+ strengthWeightFactoryClass.getName(), "comparatorFactoryClass", comparatorFactoryClass.getName()));
+ }
+ // Final properties
+ var comparatorPropertyName = "comparatorClass";
+ var comparatorPropertyClass = comparatorClass;
+ var factoryPropertyName = "comparatorFactoryClass";
+ var factoryPropertyClass = comparatorFactoryClass;
+ if (strengthComparatorClass != null) {
+ comparatorPropertyName = "strengthComparatorClass";
+ comparatorPropertyClass = strengthComparatorClass;
+ }
+ if (strengthWeightFactoryClass != null) {
+ factoryPropertyName = "strengthWeightFactoryClass";
+ factoryPropertyClass = strengthWeightFactoryClass;
+ }
+ return new SortingProperties(comparatorPropertyName, comparatorPropertyClass, factoryPropertyName,
+ factoryPropertyClass);
  }
 
  private void processAllowsUnassigned(PlanningVariable planningVariableAnnotation) {
@@ -130,4 +185,9 @@ public SelectionFilter<Solution_, Object> getMovableChainedTrailingValueFilter()
  return movableChainedTrailingValueFilter;
  }
 
+ private record SortingProperties(String comparatorPropertyName, Class<? extends Comparator> comparatorClass,
+ String comparatorFactoryPropertyName, Class<? extends SorterFactory> comparatorFactoryClass) {
+
+ }
+
 }

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/SelectionSorterWeightFactory.java

@@ -21,7 +21,7 @@
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
  * @param <T> the selection type
  */
-@Deprecated(forRemoval = true, since = "1.27.0")
+@Deprecated(forRemoval = true, since = "1.28.0")
 public interface SelectionSorterWeightFactory<Solution_, T> extends SorterFactory<Solution_, T> {
 
  Comparable createSorterWeight(Solution_ solution, T selection);