feat: Improve @CascadingUpdateShadowVariable logic (#1020)

Enhances the logic of the shadow variable @CascadingUpdateShadowVariable. 
The new approach eliminates the need to define sources and automatically runs the listener at the end of the events lifecycle.

Author: zepfred

.github/workflows/downstream_python_quickstarts.yml

@@ -43,7 +43,7 @@ jobs:
 
       # Need to check for stale repo, since Github is not aware of the build chain and therefore doesn't automate it.
       - name: Checkout timefold-quickstarts (PR) # Checkout the PR branch first, if it exists
-        id: checkout-quickstarts
+        id: checkout-quickstarts-pr
         uses: actions/checkout@v4
         continue-on-error: true
         with:
@@ -52,7 +52,7 @@ jobs:
           path: ./timefold-quickstarts
           fetch-depth: 0 # Otherwise merge will fail on account of not having history.
       - name: Checkout timefold-quickstarts (development) # Checkout the development branch if the PR branch does not exist
-        if: steps.checkout-solver-quickstarts.outcome != 'success'
+        if: steps.checkout-quickstarts-pr.outcome != 'success'
         uses: actions/checkout@v4
         with:
           repository: TimefoldAI/timefold-quickstarts

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

@@ -3,54 +3,37 @@
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
-import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
-
 /**
- * Specifies that field may be updated by the target method when one or more source variables change.
+ * Specifies that a field may be updated by the target method when any of its variables change, genuine or shadow.
+ * <p>
+ * Automatically cascades change events to the subsequent elements of a {@link PlanningListVariable}.
+ * <p>
+ * A single listener is created
+ * to execute user-defined logic from the {@code targetMethod} after all variable changes have been applied.
+ * This means it will be the last step executed during the event lifecycle.
+ * <p>
+ * It can be applied in multiple fields to update various shadow variables.
+ * The user's logic is responsible for defining the order in which each variable is updated.
+ * <p>
+ * Distinct {@code targetMethod} can be defined, but there is no guarantee about the order in which they are executed.
+ * Therefore, caution is required when using multiple {@code targetMethod} per model.
  * <p>
- * Automatically cascades change events to {@link NextElementShadowVariable} of a {@link PlanningListVariable}.
+ * Except for {@link PiggybackShadowVariable},
+ * the use of {@link CascadingUpdateShadowVariable} as a source for other variables,
+ * such as {@link ShadowVariable}, is not allowed.
  * <p>
  * Important: it must only change the shadow variable(s) for which it's configured.
- * It is only possible to define either {@code sourceVariableName} or {@code sourceVariableNames}.
- * It can be applied to multiple fields to modify different shadow variables.
  * It should never change a genuine variable or a problem fact.
  * It can change its shadow variable(s) on multiple entity instances
  * (for example: an arrivalTime change affects all trailing entities too).
  */
 @Target({ FIELD })
 @Retention(RUNTIME)
-@Repeatable(CascadingUpdateShadowVariable.List.class)
 public @interface CascadingUpdateShadowVariable {
 
-    /**
-     * The source variable name.
-     *
-     * @return never null, a genuine or shadow variable name
-     */
-    String sourceVariableName() default "";
-
-    /**
-     * The source variable name.
-     *
-     * @return never null, a genuine or shadow variable name
-     */
-    String[] sourceVariableNames() default {};
-
-    /**
-     * The {@link PlanningEntity} class of the source variable.
-     * <p>
-     * Specified if the source variable is on a different {@link Class} than the class that uses this referencing annotation.
-     *
-     * @return {@link CascadingUpdateShadowVariable.NullEntityClass} when the attribute is omitted
-     *         (workaround for annotation limitation).
-     *         Defaults to the same {@link Class} as the one that uses this annotation.
-     */
-    Class<?> sourceEntityClass() default CascadingUpdateShadowVariable.NullEntityClass.class;
-
     /**
      * The target method element.
      * <p>
@@ -62,18 +45,4 @@
      * @return method name of the source host element which will update the shadow variable
      */
     String targetMethodName();
-
-    /**
-     * Defines several {@link ShadowVariable} annotations on the same element.
-     */
-    @Target({ FIELD })
-    @Retention(RUNTIME)
-    @interface List {
-
-        CascadingUpdateShadowVariable[] value();
-    }
-
-    /** Workaround for annotation limitation in {@link #sourceEntityClass()}. */
-    interface NullEntityClass {
-    }
 }

core/src/main/java/ai/timefold/solver/core/impl/domain/entity/descriptor/EntityDescriptor.java

@@ -89,8 +89,7 @@ public class EntityDescriptor<Solution_> {
             ShadowVariable.List.class,
             PiggybackShadowVariable.class,
             CustomShadowVariable.class,
-            CascadingUpdateShadowVariable.class,
-            CascadingUpdateShadowVariable.List.class };
+            CascadingUpdateShadowVariable.class };
 
     private static final Logger LOGGER = LoggerFactory.getLogger(EntityDescriptor.class);
 
@@ -217,7 +216,6 @@ public void processAnnotations(DescriptorPolicy descriptorPolicy) {
                     + ") should have at least 1 getter method or 1 field with a "
                     + PlanningVariable.class.getSimpleName() + " annotation or a shadow variable annotation.");
         }
-        processPiggyBackForCascadingUpdateShadowVariables();
         processVariableAnnotations(descriptorPolicy);
     }
 
@@ -292,8 +290,7 @@ private void processPlanningVariableAnnotation(MutableInt variableDescriptorCoun
                     || variableAnnotationClass.equals(ShadowVariable.class)
                     || variableAnnotationClass.equals(ShadowVariable.List.class)
                     || variableAnnotationClass.equals(PiggybackShadowVariable.class)
-                    || variableAnnotationClass.equals(CascadingUpdateShadowVariable.class)
-                    || variableAnnotationClass.equals(CascadingUpdateShadowVariable.List.class)) {
+                    || variableAnnotationClass.equals(CascadingUpdateShadowVariable.class)) {
                 memberAccessorType = FIELD_OR_GETTER_METHOD;
             } else {
                 memberAccessorType = FIELD_OR_GETTER_METHOD_WITH_SETTER;
@@ -305,38 +302,6 @@ private void processPlanningVariableAnnotation(MutableInt variableDescriptorCoun
         }
     }
 
-    private void processPiggyBackForCascadingUpdateShadowVariables() {
-        if (!declaredCascadingUpdateShadowVariableDecriptorMap.isEmpty()) {
-            var piggybackShadowVariableDescriptorList = declaredShadowVariableDescriptorMap
-                    .values()
-                    .stream()
-                    .filter(v -> PiggybackShadowVariableDescriptor.class.isAssignableFrom(v.getClass()))
-                    .map(v -> (PiggybackShadowVariableDescriptor<Solution_>) v)
-                    .toList();
-            for (var descriptor : piggybackShadowVariableDescriptorList) {
-                var cascadingUpdateShadowVariableDescriptor =
-                        findNotifiableCascadingUpdateDescriptor(descriptor.getShadowVariableName());
-                if (cascadingUpdateShadowVariableDescriptor != null) {
-                    cascadingUpdateShadowVariableDescriptor.addTargetVariable(descriptor.getEntityDescriptor(),
-                            descriptor.getMemberAccessor());
-                }
-            }
-        }
-    }
-
-    private CascadingUpdateShadowVariableDescriptor<Solution_>
-            findNotifiableCascadingUpdateDescriptor(String variableName) {
-        var descriptor = declaredShadowVariableDescriptorMap.get(variableName);
-        var isCascadingUpdateDescriptor =
-                descriptor != null && CascadingUpdateShadowVariableDescriptor.class.isAssignableFrom(descriptor.getClass());
-        if (isCascadingUpdateDescriptor && !descriptor.hasVariableListener()) {
-            descriptor =
-                    declaredCascadingUpdateShadowVariableDecriptorMap
-                            .get(((CascadingUpdateShadowVariableDescriptor<Solution_>) descriptor).getTargetMethodName());
-        }
-        return isCascadingUpdateDescriptor ? (CascadingUpdateShadowVariableDescriptor<Solution_>) descriptor : null;
-    }
-
     private void registerVariableAccessor(int nextVariableDescriptorOrdinal,
             Class<? extends Annotation> variableAnnotationClass, MemberAccessor memberAccessor) {
         var memberName = memberAccessor.getName();
@@ -392,24 +357,17 @@ The entityClass (%s) has a @%s annotated member (%s) that has an unsupported typ
                 || variableAnnotationClass.equals(ShadowVariable.List.class)) {
             var variableDescriptor = new CustomShadowVariableDescriptor<>(nextVariableDescriptorOrdinal, this, memberAccessor);
             declaredShadowVariableDescriptorMap.put(memberName, variableDescriptor);
-        } else if (variableAnnotationClass.equals(CascadingUpdateShadowVariable.class)
-                || variableAnnotationClass.equals(CascadingUpdateShadowVariable.List.class)) {
+        } else if (variableAnnotationClass.equals(CascadingUpdateShadowVariable.class)) {
             var variableDescriptor =
                     new CascadingUpdateShadowVariableDescriptor<>(nextVariableDescriptorOrdinal, this, memberAccessor);
             declaredShadowVariableDescriptorMap.put(memberName, variableDescriptor);
             if (declaredCascadingUpdateShadowVariableDecriptorMap.containsKey(variableDescriptor.getTargetMethodName())) {
                 // If the target method is already set,
                 // it means that multiple fields define the cascading shadow variable
                 // and point to the same target method.
-                // As a result, only one listener will be created for the related target method,
-                // which will include all sources from all fields.
-                // This specific shadow variable will not be notifiable,
-                // and no listener will be created from CascadingUpdateVariableListenerDescriptor#buildVariableListeners.
-                variableDescriptor.setNotifiable(false);
                 declaredCascadingUpdateShadowVariableDecriptorMap.get(variableDescriptor.getTargetMethodName())
                         .addTargetVariable(this, memberAccessor);
             } else {
-                // The first shadow variable read is notifiable and will generate a listener.
                 declaredCascadingUpdateShadowVariableDecriptorMap.put(variableDescriptor.getTargetMethodName(),
                         variableDescriptor);
             }
@@ -608,6 +566,10 @@ public boolean hasEffectiveMovableEntitySelectionFilter() {
         return effectiveMovableEntitySelectionFilter != null;
     }
 
+    public boolean hasCascadingShadowVariables() {
+        return !declaredShadowVariableDescriptorMap.isEmpty();
+    }
+
     public boolean supportsPinning() {
         return hasEffectiveMovableEntitySelectionFilter() || effectivePlanningPinToIndexReader != null;
     }
@@ -691,6 +653,11 @@ public Collection<ShadowVariableDescriptor<Solution_>> getDeclaredShadowVariable
         return declaredShadowVariableDescriptorMap.values();
     }
 
+    public Collection<CascadingUpdateShadowVariableDescriptor<Solution_>>
+            getDeclaredCascadingUpdateShadowVariableDescriptors() {
+        return declaredCascadingUpdateShadowVariableDecriptorMap.values();
+    }
+
     public Collection<VariableDescriptor<Solution_>> getDeclaredVariableDescriptors() {
         Collection<VariableDescriptor<Solution_>> variableDescriptors = new ArrayList<>(
                 declaredGenuineVariableDescriptorMap.size() + declaredShadowVariableDescriptorMap.size());