feat(templates): add TemplateValidationContext to TemplatePayload.validate() (#856)

dieppa · web-flow · commit 44aeeb4e2ad4 · 2026-03-03T22:00:24.000Z
- Introduce **TemplateValidationContext** class with `transactional` field
  (default `false`) and a backward-compatibility contract: new fields are
  added via getter/setter with sensible defaults, so older payloads work
  unchanged
- Change `TemplatePayload.validate()` signature to
  `validate(TemplateValidationContext)`, enabling context-aware payload
  validation
- Add `buildValidationContext()` helper in **AbstractTemplateLoadedChange**
  to construct the context from change metadata, used by both
  **SimpleTemplateLoadedChange** and **MultiStepTemplateLoadedChange**
- Update all implementations: **TemplateVoid**, **TemplateString**, and
  test payloads
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplatePayload.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplatePayload.java
@@ -26,9 +26,11 @@
 public interface TemplatePayload {
 
     /**
-     * Validates this payload and returns any errors found.
+     * Validates this payload using the supplied change-level context
+     * and returns any errors found.
      *
+     * @param context change-level metadata available during validation
      * @return list of validation errors, empty if payload is valid
      */
-    List<TemplatePayloadValidationError> validate();
+    List<TemplatePayloadValidationError> validate(TemplateValidationContext context);
 }
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplateValidationContext.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/TemplateValidationContext.java
@@ -0,0 +1,59 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.api.template;
+
+/**
+ * Context provided to {@link TemplatePayload#validate(TemplateValidationContext)}
+ * so payload validation can access change-level metadata.
+ *
+ * <p><b>Binary-compatibility contract:</b> new fields are added as
+ * getter/setter pairs with sensible defaults.  Older template payloads
+ * that ignore the new fields continue to work unchanged.
+ *
+ * <p>Current fields:
+ * <ul>
+ *   <li>{@code transactional} (default {@code false}) — whether the
+ *       enclosing change is declared transactional.</li>
+ * </ul>
+ */
+public class TemplateValidationContext {
+
+    private boolean transactional;
+
+    /**
+     * Creates a context with all fields set to their defaults.
+     */
+    public TemplateValidationContext() {
+    }
+
+    /**
+     * Returns whether the enclosing change is declared transactional.
+     *
+     * @return {@code true} if the change is transactional, {@code false} otherwise
+     */
+    public boolean isTransactional() {
+        return transactional;
+    }
+
+    /**
+     * Sets whether the enclosing change is declared transactional.
+     *
+     * @param transactional {@code true} if the change is transactional
+     */
+    public void setTransactional(boolean transactional) {
+        this.transactional = transactional;
+    }
+}
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateString.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateString.java
@@ -17,6 +17,7 @@
 
 import io.flamingock.api.template.TemplatePayload;
 import io.flamingock.api.template.TemplatePayloadValidationError;
+import io.flamingock.api.template.TemplateValidationContext;
 
 import java.util.Collections;
 import java.util.List;
@@ -58,7 +59,7 @@ public void setValue(String value) {
     }
 
     @Override
-    public List<TemplatePayloadValidationError> validate() {
+    public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
         if (value == null || value.trim().isEmpty()) {
             return Collections.singletonList(
                     new TemplatePayloadValidationError("value", "must not be null or blank"));
diff --git a/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateVoid.java b/core/flamingock-core-api/src/main/java/io/flamingock/api/template/wrappers/TemplateVoid.java
@@ -17,6 +17,7 @@
 
 import io.flamingock.api.template.TemplatePayload;
 import io.flamingock.api.template.TemplatePayloadValidationError;
+import io.flamingock.api.template.TemplateValidationContext;
 
 import java.util.Collections;
 import java.util.List;
@@ -32,7 +33,7 @@
 public class TemplateVoid implements TemplatePayload {
 
     @Override
-    public List<TemplatePayloadValidationError> validate() {
+    public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
         return Collections.emptyList();
     }
 }
diff --git a/core/flamingock-core-api/src/test/java/io/flamingock/api/template/AbstractChangeTemplateReflectiveClassesTest.java b/core/flamingock-core-api/src/test/java/io/flamingock/api/template/AbstractChangeTemplateReflectiveClassesTest.java
@@ -36,7 +36,7 @@ public static class TestConfig implements TemplatePayload {
         public String configValue;
 
         @Override
-        public List<TemplatePayloadValidationError> validate() {
+        public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
             return Collections.emptyList();
         }
     }
@@ -46,7 +46,7 @@ public static class TestApplyPayload implements TemplatePayload {
         public String applyData;
 
         @Override
-        public List<TemplatePayloadValidationError> validate() {
+        public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
             return Collections.emptyList();
         }
     }
@@ -56,7 +56,7 @@ public static class TestRollbackPayload implements TemplatePayload {
         public String rollbackData;
 
         @Override
-        public List<TemplatePayloadValidationError> validate() {
+        public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {
             return Collections.emptyList();
         }
     }
diff --git a/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/AbstractTemplateLoadedChange.java b/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/AbstractTemplateLoadedChange.java
@@ -19,6 +19,7 @@
 import io.flamingock.api.annotations.Rollback;
 import io.flamingock.api.template.ChangeTemplate;
 import io.flamingock.api.template.TemplatePayload;
+import io.flamingock.api.template.TemplateValidationContext;
 import io.flamingock.internal.common.core.error.validation.ValidationError;
 import io.flamingock.internal.common.core.task.RecoveryDescriptor;
 import io.flamingock.internal.common.core.task.TargetSystemDescriptor;
@@ -103,6 +104,12 @@ public List<ValidationError> getValidationErrors(StageValidationContext context)
         return errors;
     }
 
+    protected TemplateValidationContext buildValidationContext() {
+        TemplateValidationContext ctx = new TemplateValidationContext();
+        ctx.setTransactional(isTransactional());
+        return ctx;
+    }
+
     abstract protected List<ValidationError> validateConfigurationPayload();
 
     abstract protected List<ValidationError> validateApplyPayload();
diff --git a/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/MultiStepTemplateLoadedChange.java b/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/MultiStepTemplateLoadedChange.java
@@ -19,6 +19,7 @@
 import io.flamingock.api.template.TemplatePayload;
 import io.flamingock.api.template.TemplatePayloadValidationError;
 import io.flamingock.api.template.TemplateStep;
+import io.flamingock.api.template.TemplateValidationContext;
 import io.flamingock.internal.common.core.error.validation.ValidationError;
 import io.flamingock.internal.common.core.task.RecoveryDescriptor;
 import io.flamingock.internal.common.core.task.TargetSystemDescriptor;
@@ -71,7 +72,8 @@ public List<TemplateStep<APPLY, ROLLBACK>> getSteps() {
     protected List<ValidationError> validateConfigurationPayload() {
         CONFIG config = getConfigurationPayload();
         if (config != null) {
-            List<TemplatePayloadValidationError> payloadErrors = config.validate();
+            TemplateValidationContext context = buildValidationContext();
+            List<TemplatePayloadValidationError> payloadErrors = config.validate(context);
             if (!payloadErrors.isEmpty()) {
                 List<ValidationError> errors = new ArrayList<>();
                 for (TemplatePayloadValidationError e : payloadErrors) {
@@ -89,14 +91,15 @@ protected List<ValidationError> validateConfigurationPayload() {
     protected List<ValidationError> validateApplyPayload() {
         List<ValidationError> errors = new ArrayList<>();
         if (steps != null) {
+            TemplateValidationContext context = buildValidationContext();
             for (int i = 0; i < steps.size(); i++) {
                 APPLY applyPayload = steps.get(i).getApplyPayload();
                 if (applyPayload == null) {
                     errors.add(new ValidationError(
                             String.format("Template '%s', step %d: missing required 'apply' payload", getSource(), i + 1),
                             getId(), "change"));
                 } else {
-                    List<TemplatePayloadValidationError> payloadErrors = applyPayload.validate();
+                    List<TemplatePayloadValidationError> payloadErrors = applyPayload.validate(context);
                     for (TemplatePayloadValidationError e : payloadErrors) {
                         errors.add(new ValidationError(
                                 String.format("Template '%s', step %d apply payload: %s", getSource(), i + 1, e.getFormattedMessage()),
@@ -112,14 +115,15 @@ protected List<ValidationError> validateApplyPayload() {
     protected List<ValidationError> validateRollbackPayload() {
         List<ValidationError> errors = new ArrayList<>();
         if (steps != null) {
+            TemplateValidationContext context = buildValidationContext();
             for (int i = 0; i < steps.size(); i++) {
                 ROLLBACK rollbackPayload = steps.get(i).getRollbackPayload();
                 if (rollbackPayloadRequired && !steps.get(i).hasRollbackPayload()) {
                     errors.add(new ValidationError(
                             String.format("Template '%s', step %d: missing required 'rollback' payload (rollbackPayloadRequired=true)", getSource(), i + 1),
                             getId(), "change"));
                 } else if (rollbackPayload != null) {
-                    List<TemplatePayloadValidationError> payloadErrors = rollbackPayload.validate();
+                    List<TemplatePayloadValidationError> payloadErrors = rollbackPayload.validate(context);
                     for (TemplatePayloadValidationError e : payloadErrors) {
                         errors.add(new ValidationError(
                                 String.format("Template '%s', step %d rollback payload: %s", getSource(), i + 1, e.getFormattedMessage()),
diff --git a/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/SimpleTemplateLoadedChange.java b/core/flamingock-core/src/main/java/io/flamingock/internal/core/task/loaded/SimpleTemplateLoadedChange.java
@@ -18,6 +18,7 @@
 import io.flamingock.api.template.AbstractChangeTemplate;
 import io.flamingock.api.template.TemplatePayload;
 import io.flamingock.api.template.TemplatePayloadValidationError;
+import io.flamingock.api.template.TemplateValidationContext;
 import io.flamingock.internal.common.core.error.validation.ValidationError;
 import io.flamingock.internal.common.core.task.RecoveryDescriptor;
 import io.flamingock.internal.common.core.task.TargetSystemDescriptor;
@@ -82,7 +83,8 @@ public boolean hasRollbackPayload() {
     protected List<ValidationError> validateConfigurationPayload() {
         CONFIG config = getConfigurationPayload();
         if (config != null) {
-            List<TemplatePayloadValidationError> payloadErrors = config.validate();
+            TemplateValidationContext context = buildValidationContext();
+            List<TemplatePayloadValidationError> payloadErrors = config.validate(context);
             if (!payloadErrors.isEmpty()) {
                 List<ValidationError> errors = new ArrayList<>();
                 for (TemplatePayloadValidationError e : payloadErrors) {
@@ -103,7 +105,8 @@ protected List<ValidationError> validateApplyPayload() {
                     String.format("Template '%s' requires 'apply' payload", getSource()),
                     getId(), "change"));
         }
-        List<TemplatePayloadValidationError> payloadErrors = applyPayload.validate();
+        TemplateValidationContext context = buildValidationContext();
+        List<TemplatePayloadValidationError> payloadErrors = applyPayload.validate(context);
         if (!payloadErrors.isEmpty()) {
             List<ValidationError> errors = new ArrayList<>();
             for (TemplatePayloadValidationError e : payloadErrors) {
@@ -124,7 +127,8 @@ protected List<ValidationError> validateRollbackPayload() {
                     getId(), "change"));
         }
         if (rollbackPayload != null) {
-            List<TemplatePayloadValidationError> payloadErrors = rollbackPayload.validate();
+            TemplateValidationContext context = buildValidationContext();
+            List<TemplatePayloadValidationError> payloadErrors = rollbackPayload.validate(context);
             if (!payloadErrors.isEmpty()) {
                 List<ValidationError> errors = new ArrayList<>();
                 for (TemplatePayloadValidationError e : payloadErrors) {

Original file line number	Diff line number	Diff line change
`@@ -26,9 +26,11 @@`
`26`	`26`	`public interface TemplatePayload {`
`27`	`27`
`28`	`28`	`/**`
`29`		`- * Validates this payload and returns any errors found.`
	`29`	`+ * Validates this payload using the supplied change-level context`
	`30`	`+ * and returns any errors found.`
`30`	`31`	`*`
	`32`	`+ * @param context change-level metadata available during validation`
`31`	`33`	`* @return list of validation errors, empty if payload is valid`
`32`	`34`	`*/`
`33`		`- List<TemplatePayloadValidationError> validate();`
	`35`	`+ List<TemplatePayloadValidationError> validate(TemplateValidationContext context);`
`34`	`36`	`}`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@`
`17`	`17`
`18`	`18`	`import io.flamingock.api.template.TemplatePayload;`
`19`	`19`	`import io.flamingock.api.template.TemplatePayloadValidationError;`
	`20`	`+import io.flamingock.api.template.TemplateValidationContext;`
`20`	`21`
`21`	`22`	`import java.util.Collections;`
`22`	`23`	`import java.util.List;`
`@@ -32,7 +33,7 @@`
`32`	`33`	`public class TemplateVoid implements TemplatePayload {`
`33`	`34`
`34`	`35`	`@Override`
`35`		`- public List<TemplatePayloadValidationError> validate() {`
	`36`	`+ public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {`
`36`	`37`	`return Collections.emptyList();`
`37`	`38`	`}`
`38`	`39`	`}`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ public static class TestConfig implements TemplatePayload {`
`36`	`36`	`public String configValue;`
`37`	`37`
`38`	`38`	`@Override`
`39`		`- public List<TemplatePayloadValidationError> validate() {`
	`39`	`+ public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {`
`40`	`40`	`return Collections.emptyList();`
`41`	`41`	`}`
`42`	`42`	`}`
`@@ -46,7 +46,7 @@ public static class TestApplyPayload implements TemplatePayload {`
`46`	`46`	`public String applyData;`
`47`	`47`
`48`	`48`	`@Override`
`49`		`- public List<TemplatePayloadValidationError> validate() {`
	`49`	`+ public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {`
`50`	`50`	`return Collections.emptyList();`
`51`	`51`	`}`
`52`	`52`	`}`
`@@ -56,7 +56,7 @@ public static class TestRollbackPayload implements TemplatePayload {`
`56`	`56`	`public String rollbackData;`
`57`	`57`
`58`	`58`	`@Override`
`59`		`- public List<TemplatePayloadValidationError> validate() {`
	`59`	`+ public List<TemplatePayloadValidationError> validate(TemplateValidationContext context) {`
`60`	`60`	`return Collections.emptyList();`
`61`	`61`	`}`
`62`	`62`	`}`