chore: migrate quickstarts to use declarative shadow variables

One food-packaging ShadowVariable could not be migrated, since
it uses a non-declarative shadow on non-declarative shadow as a source.

Author: Christopher-Chianelli

java/food-packaging/src/main/java/org/acme/foodpackaging/domain/Job.java

@@ -8,9 +8,12 @@
 import ai.timefold.solver.core.api.domain.variable.NextElementShadowVariable;
 import ai.timefold.solver.core.api.domain.variable.PreviousElementShadowVariable;
 import ai.timefold.solver.core.api.domain.variable.ShadowVariable;
+import ai.timefold.solver.core.preview.api.domain.variable.declarative.ShadowSources;
+
 import com.fasterxml.jackson.annotation.JsonIgnore;
 
 import java.time.Duration;
+import java.time.LocalDate;
 import java.time.LocalDateTime;
 
 @PlanningEntity
@@ -34,6 +37,9 @@ public class Job {
 
     @InverseRelationShadowVariable(sourceVariableName = "jobs")
     private Line line;
+
+    // TODO: Replace me when declarative shadow variables support
+    //       non-declarative shadow on non-declarative shadow sources
     @ShadowVariable(
             variableListenerClass = LineOperatorUpdatingVariableListener.class,
             sourceEntityClass = Line.class,
@@ -52,11 +58,11 @@ public class Job {
     /**
      * Start is after cleanup.
      */
-    @CascadingUpdateShadowVariable(targetMethodName = "updateStartCleaningDateTime")
+    @ShadowVariable(supplierName = "startCleaningDateTimeSupplier")
     private LocalDateTime startCleaningDateTime;
-    @CascadingUpdateShadowVariable(targetMethodName = "updateStartCleaningDateTime")
+    @ShadowVariable(supplierName = "startProductionDateTimeSupplier")
     private LocalDateTime startProductionDateTime;
-    @CascadingUpdateShadowVariable(targetMethodName = "updateStartCleaningDateTime")
+    @ShadowVariable(supplierName = "endDateTimeSupplier")
     private LocalDateTime endDateTime;
 
     // No-arg constructor required for Timefold
@@ -190,28 +196,34 @@ public void setEndDateTime(LocalDateTime endDateTime) {
     // ************************************************************************
 
     @SuppressWarnings("unused")
-    private void updateStartCleaningDateTime() {
-        if (getLine() == null) {
-            if (getStartCleaningDateTime() != null) {
-                setStartCleaningDateTime(null);
-                setStartProductionDateTime(null);
-                setEndDateTime(null);
-            }
-            return;
+    @ShadowSources({"line", "previousJob.endDateTime"})
+    private LocalDateTime startCleaningDateTimeSupplier() {
+        if (line == null) {
+            return null;
         }
-        Job previous = getPreviousJob();
-        LocalDateTime startCleaning;
-        LocalDateTime startProduction;
-        if (previous == null) {
-            startCleaning = line.getStartDateTime();
-            startProduction = line.getStartDateTime();
+        if (previousJob == null) {
+            return line.getStartDateTime();
         } else {
-            startCleaning = previous.getEndDateTime();
-            startProduction = startCleaning == null ? null : startCleaning.plus(getProduct().getCleanupDuration(previous.getProduct()));
+            return previousJob.getEndDateTime();
+        }
+    }
+
+    @SuppressWarnings("unused")
+    @ShadowSources({"line", "startCleaningDateTime"})
+    private LocalDateTime startProductionDateTimeSupplier() {
+        if (line == null) {
+            return null;
         }
-        setStartCleaningDateTime(startCleaning);
-        setStartProductionDateTime(startProduction);
-        var endTime = startProduction == null ? null : startProduction.plus(getDuration());
-        setEndDateTime(endTime);
+        if (previousJob == null) {
+            return line.getStartDateTime();
+        } else {
+            return startCleaningDateTime == null ? null : startCleaningDateTime.plus(getProduct().getCleanupDuration(previousJob.getProduct()));
+        }
+    }
+
+    @SuppressWarnings("unused")
+    @ShadowSources({"startProductionDateTime"})
+    private LocalDateTime endDateTimeSupplier() {
+        return startProductionDateTime == null ? null : startProductionDateTime.plus(getDuration());
     }
 }

java/food-packaging/src/main/resources/application.properties

@@ -4,6 +4,7 @@
 
 # The solver runs for 30 seconds. To run for 5 minutes use "5m" and for 2 hours use "2h".
 quarkus.timefold.solver.termination.spent-limit=30s
+quarkus.timefold.solver.enabled-preview-features=DECLARATIVE_SHADOW_VARIABLES
 
 # To change how many solvers to run in parallel
 # timefold.solver-manager.parallel-solver-count=4

java/maintenance-scheduling/src/main/java/org/acme/maintenancescheduling/domain/Job.java

@@ -7,8 +7,7 @@
 import ai.timefold.solver.core.api.domain.lookup.PlanningId;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariable;
 import ai.timefold.solver.core.api.domain.variable.ShadowVariable;
-
-import org.acme.maintenancescheduling.solver.EndDateUpdatingVariableListener;
+import ai.timefold.solver.core.preview.api.domain.variable.declarative.ShadowSources;
 
 @PlanningEntity
 public class Job {
@@ -29,7 +28,7 @@ public class Job {
     // Follows the TimeGrain Design Pattern
     @PlanningVariable
     private LocalDate startDate; // Inclusive
-    @ShadowVariable(variableListenerClass = EndDateUpdatingVariableListener.class, sourceVariableName = "startDate")
+    @ShadowVariable(supplierName = "endDateSupplier")
     private LocalDate endDate; // Exclusive
 
     public Job() {
@@ -56,7 +55,7 @@ public Job(String id, String name, int durationInDays, LocalDate minStartDate, L
         this.tags = tags;
         this.crew = crew;
         this.startDate = startDate;
-        this.endDate = EndDateUpdatingVariableListener.calculateEndDate(startDate, durationInDays);
+        this.endDate = calculateEndDate(startDate, durationInDays);
     }
 
     @Override
@@ -119,4 +118,25 @@ public LocalDate getEndDate() {
     public void setEndDate(LocalDate endDate) {
         this.endDate = endDate;
     }
+
+    // ************************************************************************
+    // Complex methods
+    // ************************************************************************
+    @SuppressWarnings("unused")
+    @ShadowSources("startDate")
+    public LocalDate endDateSupplier() {
+        return calculateEndDate(startDate, durationInDays);
+    }
+
+    public static LocalDate calculateEndDate(LocalDate startDate, int durationInDays) {
+        if (startDate == null) {
+            return null;
+        } else {
+            // Skip weekends. Does not work for holidays.
+            // To skip holidays too, cache all working days in WorkCalendar.
+            // Keep in sync with MaintenanceSchedule.createStartDateList().
+            int weekendPadding = 2 * ((durationInDays + (startDate.getDayOfWeek().getValue() - 1)) / 5);
+            return startDate.plusDays(durationInDays + weekendPadding);
+        }
+    }
 }

java/maintenance-scheduling/src/main/java/org/acme/maintenancescheduling/rest/DemoDataGenerator.java

@@ -14,7 +14,6 @@
 import org.acme.maintenancescheduling.domain.Job;
 import org.acme.maintenancescheduling.domain.MaintenanceSchedule;
 import org.acme.maintenancescheduling.domain.WorkCalendar;
-import org.acme.maintenancescheduling.solver.EndDateUpdatingVariableListener;
 
 @ApplicationScoped
 public class DemoDataGenerator {
@@ -63,9 +62,9 @@ public MaintenanceSchedule generateDemoData(DemoData demoData) {
                     + random.nextInt(workdayTotal - (durationInDays + 5));
             int minWorkdayOffset = random.nextInt(workdayTotal - minMaxBetweenWorkdays + 1);
             int minIdealEndBetweenWorkdays = minMaxBetweenWorkdays - 1 - random.nextInt(4);
-            LocalDate minStartDate = EndDateUpdatingVariableListener.calculateEndDate(fromDate, minWorkdayOffset);
-            LocalDate maxEndDate = EndDateUpdatingVariableListener.calculateEndDate(minStartDate, minMaxBetweenWorkdays);
-            LocalDate idealEndDate = EndDateUpdatingVariableListener.calculateEndDate(minStartDate, minIdealEndBetweenWorkdays);
+            LocalDate minStartDate = Job.calculateEndDate(fromDate, minWorkdayOffset);
+            LocalDate maxEndDate = Job.calculateEndDate(minStartDate, minMaxBetweenWorkdays);
+            LocalDate idealEndDate = Job.calculateEndDate(minStartDate, minIdealEndBetweenWorkdays);
             Set<String> tags = random.nextDouble() < 0.1 ? Set.of(jobArea, "Subway") : Set.of(jobArea);
             jobs.add(new Job(Integer.toString(i), jobArea + " " + jobTarget, durationInDays, minStartDate, maxEndDate, idealEndDate,
                     tags));

java/maintenance-scheduling/src/main/java/org/acme/maintenancescheduling/solver/EndDateUpdatingVariableListener.java

@@ -4,6 +4,7 @@
 
 # The solver runs for 30 seconds. To run for 5 minutes use "5m" and for 2 hours use "2h".
 quarkus.timefold.solver.termination.spent-limit=30s
+quarkus.timefold.solver.enabled-preview-features=DECLARATIVE_SHADOW_VARIABLES
 
 # To change how many solvers to run in parallel
 # timefold.solver-manager.parallel-solver-count=4

java/maintenance-scheduling/src/main/resources/application.properties

@@ -13,9 +13,9 @@
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeProvider;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariable;
 import ai.timefold.solver.core.api.domain.variable.ShadowVariable;
+import ai.timefold.solver.core.preview.api.domain.variable.declarative.ShadowSources;
 
 import org.acme.projectjobschedule.domain.solver.DelayStrengthComparator;
-import org.acme.projectjobschedule.domain.solver.PredecessorsDoneDateUpdatingVariableListener;
 
 import com.fasterxml.jackson.annotation.JsonIdentityInfo;
 import com.fasterxml.jackson.annotation.JsonIdentityReference;
@@ -50,9 +50,7 @@ public class Allocation {
     private Integer delay; // In days
 
     // Shadow variables
-    @ShadowVariable(variableListenerClass = PredecessorsDoneDateUpdatingVariableListener.class,
-            sourceVariableName = "executionMode")
-    @ShadowVariable(variableListenerClass = PredecessorsDoneDateUpdatingVariableListener.class, sourceVariableName = "delay")
+    @ShadowVariable(supplierName = "predecessorsDoneDateSupplier")
     private Integer predecessorsDoneDate;
 
     // Filled from shadow variables
@@ -199,6 +197,17 @@ public void setPredecessorsDoneDate(Integer predecessorsDoneDate) {
     // ************************************************************************
     // Complex methods
     // ************************************************************************
+    @SuppressWarnings("unused")
+    @ShadowSources({"executionMode", "delay", "predecessorAllocations[].predecessorsDoneDate"})
+    public Integer predecessorsDoneDateSupplier() {
+        // For the source the doneDate must be 0.
+        Integer doneDate = 0;
+        for (Allocation predecessorAllocation : predecessorAllocations) {
+            int endDate = predecessorAllocation.getEndDate();
+            doneDate = Math.max(doneDate, endDate);
+        }
+        return doneDate;
+    }
 
     public void invalidateComputedVariables() {
         this.startDate = null;

java/project-job-scheduling/src/main/java/org/acme/projectjobschedule/domain/Allocation.java

@@ -4,6 +4,7 @@
 
 # The solver runs for 30 seconds. To run for 5 minutes use "5m" and for 2 hours use "2h".
 quarkus.timefold.solver.termination.spent-limit=30s
+quarkus.timefold.solver.enabled-preview-features=DECLARATIVE_SHADOW_VARIABLES
 
 # To change how many solvers to run in parallel
 # timefold.solver-manager.parallel-solver-count=4