chore: deprecate PiggybackShadowVariable

Author: Christopher-Chianelli

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

@@ -14,9 +14,12 @@
  * variable listener.
  * <p>
  * It is specified on a getter of a java bean property (or a field) of a {@link PlanningEntity} class.
+ *
+ * @deprecated Use a {@link ShadowVariable#supplierName() supplier} with {@link ShadowSources sources} instead.
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)
+@Deprecated(since = "1.28.0", forRemoval = true)
 public @interface PiggybackShadowVariable {
 
     /**

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/custom/PiggybackShadowVariableDescriptor.java

@@ -7,6 +7,7 @@
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.api.domain.variable.PiggybackShadowVariable;
 import ai.timefold.solver.core.api.domain.variable.ShadowVariable;
+import ai.timefold.solver.core.api.domain.variable.VariableListener;
 import ai.timefold.solver.core.impl.domain.common.accessor.MemberAccessor;
 import ai.timefold.solver.core.impl.domain.entity.descriptor.EntityDescriptor;
 import ai.timefold.solver.core.impl.domain.policy.DescriptorPolicy;
@@ -70,11 +71,13 @@ private void linkShadowSources(DescriptorPolicy descriptorPolicy) {
                     + shadowEntityDescriptor.buildInvalidVariableNameExceptionMessage(shadowVariableName));
         }
         if (!(uncastShadowVariableDescriptor instanceof CustomShadowVariableDescriptor)) {
-            throw new IllegalArgumentException("The entityClass (" + entityDescriptor.getEntityClass()
-                    + ") has a @" + PiggybackShadowVariable.class.getSimpleName()
-                    + " annotated property (" + variableMemberAccessor.getName()
-                    + ") with refVariable (" + uncastShadowVariableDescriptor.getSimpleEntityAndVariableName()
-                    + ") that lacks a @" + ShadowVariable.class.getSimpleName() + " annotation.");
+            throw new IllegalArgumentException("""
+                    The entityClass (%s) has a @%s annotated property (%s) with refVariable (%s) that
+                    lacks a %s @%s annotation.
+                    """.formatted(entityDescriptor.getEntityClass(), PiggybackShadowVariable.class.getSimpleName(),
+                    variableMemberAccessor.getName(), uncastShadowVariableDescriptor.getSimpleEntityAndVariableName(),
+                    VariableListener.class.getSimpleName(),
+                    ShadowVariable.class.getSimpleName()));
         }
         shadowVariableDescriptor = (CustomShadowVariableDescriptor<Solution_>) uncastShadowVariableDescriptor;
         shadowVariableDescriptor.registerSinkVariableDescriptor(this);

core/src/test/java/ai/timefold/solver/core/impl/domain/variable/cascade/SingleCascadingUpdateShadowVariableListenerTest.java

@@ -37,11 +37,11 @@ void requiredShadowVariableDependencies() {
                         "Shadow variables such as @CascadingUpdateShadowVariable are not allowed to be used as source")
                 .withMessageContaining("Maybe check if cascadeValue is annotated with @CascadingUpdateShadowVariable");
         assertThatIllegalArgumentException().isThrownBy(TestdataCascadingInvalidPiggyback::buildEntityDescriptor)
-                .withMessageContaining(
-                        "The entityClass (class ai.timefold.solver.core.testdomain.shadow.wrongcascade.TestdataCascadingInvalidPiggyback)")
-                .withMessageContaining("has a @PiggybackShadowVariable annotated property (cascadeValue2)")
-                .withMessageContaining(
-                        "with refVariable (TestdataCascadingInvalidPiggyback.cascadeValue) that lacks a @ShadowVariable annotation");
+                .withMessageContainingAll(
+                        "The entityClass (class ai.timefold.solver.core.testdomain.shadow.wrongcascade.TestdataCascadingInvalidPiggyback)",
+                        "has a @PiggybackShadowVariable annotated property (cascadeValue2)",
+                        "with refVariable (TestdataCascadingInvalidPiggyback.cascadeValue) that",
+                        "lacks a VariableListener @ShadowVariable annotation.");
     }
 
     @Test