HV-1529 Add dynamic payload to HibernateConstraintValidator

documentation/src/main/asciidoc/ch06.asciidoc

@@ -189,7 +189,7 @@ The `initialize()` method of `HibernateConstraintValidator` takes two parameters
  * The `ConstraintDescriptor` of the constraint at hand.
    You can get access to the annotation using `ConstraintDescriptor#getAnnotation()`.
  * The `HibernateConstraintValidatorInitializationContext` which provides useful helpers and contextual
-   information, such as the clock provider or the temporal validation tolerance.
+   information, such as the clock provider, the temporal validation tolerance or the constraint validator payload.
 
 This extension is marked as incubating so it might be subject to change.
 The plan is to standardize it and to include it in Bean Validation in the future.
@@ -210,6 +210,67 @@ include::{sourcedir}/org/hibernate/validator/referenceguide/chapter06/MyFutureVa
 You should only implement one of the `initialize()` methods. Be aware that both are called when initializing the validator.
 ====
 
+[[constraint-validator-payload]]
+===== Passing a payload to the constraint validator
+
+From time to time, you might want to condition the constraint validator behavior on some external parameters.
+
+For instance, your zip code validator could vary depending on the locale of your application instance if you have one
+instance per country.
+Another requirement could be to have different behaviors on specific environments: the staging environment may not have
+access to some external production resources necessary for the correct functioning of a validator.
+
+The notion of constraint validator payload was introduced for all these use cases.
+It is an object passed from the `Validator` instance to each constraint validator via the `HibernateConstraintValidatorInitializationContext`.
+
+The example below shows how to set a constraint validator payload during the `ValidatorFactory` initialization.
+Unless you override this default value, all the ``Validator``s created by this `ValidatorFactory` will have this
+constraint validator payload value set.
+
+[[example-constraint-validator-payload-definition-validatorfactory]]
+.Defining a constraint validator payload during the `ValidatorFactory` initialization
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/org/hibernate/validator/referenceguide/chapter06/constraintvalidatorpayload/ConstraintValidatorPayloadTest.java[tags=setConstraintValidatorPayloadDuringValidatorFactoryInitialization]
+----
+====
+
+Another option is to set the constraint validator payload per `Validator` using a context:
+
+[[example-constraint-validator-payload-definition-validatorcontext]]
+.Defining a constraint validator payload using a `Validator` context
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/org/hibernate/validator/referenceguide/chapter06/constraintvalidatorpayload/ConstraintValidatorPayloadTest.java[tags=setConstraintValidatorPayloadInValidatorContext]
+----
+====
+
+Once you have set the constraint validator payload, it is time to use it in your constraint validators as shown in the example below:
+
+[[example-constraint-validator-payload-usage]]
+.Using the constraint validator payload in a constraint validator
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/org/hibernate/validator/referenceguide/chapter06/constraintvalidatorpayload/ZipCodeValidator.java[tags=include]
+----
+====
+
+`HibernateConstraintValidatorInitializationContext#getConstraintValidatorPayload()` has a type parameter
+and returns the payload only if the payload is of the given type.
+
+[NOTE]
+====
+It is important to note that the constraint validator payload is different from the dynamic payload you can include in
+the constraint violation raised.
+
+The whole purpose of this constraint validator payload is to be used to condition the behavior of your constraint validators.
+It is not included in the constraint violations, unless a specific `ConstraintValidator` implementation passes on the
+payload to emitted constraint violations by using the <<section-dynamic-payload,constraint violation dynamic payload mechanism>>.
+====
+
 [[validator-customconstraints-errormessage]]
 ==== The error message
 

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter06/constraintvalidatorpayload/ConstraintValidatorPayloadTest.java

@@ -0,0 +1,48 @@
+package org.hibernate.validator.referenceguide.chapter06.constraintvalidatorpayload;
+
+import javax.validation.Validation;
+import javax.validation.Validator;
+import javax.validation.ValidatorFactory;
+
+import org.hibernate.validator.HibernateValidator;
+import org.hibernate.validator.HibernateValidatorFactory;
+import org.junit.Test;
+
+@SuppressWarnings("unused")
+public class ConstraintValidatorPayloadTest {
+
+	@Test
+	public void setConstraintValidatorPayloadDuringValidatorFactoryInitialization() {
+		//tag::setConstraintValidatorPayloadDuringValidatorFactoryInitialization[]
+		ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )
+				.configure()
+				.constraintValidatorPayload( "US" )
+				.buildValidatorFactory();
+
+		Validator validator = validatorFactory.getValidator();
+		//end::setConstraintValidatorPayloadDuringValidatorFactoryInitialization[]
+	}
+
+	@Test
+	public void setConstraintValidatorPayloadInValidatorContext() {
+		//tag::setConstraintValidatorPayloadInValidatorContext[]
+		HibernateValidatorFactory hibernateValidatorFactory = Validation.byDefaultProvider()
+				.configure()
+				.buildValidatorFactory()
+				.unwrap( HibernateValidatorFactory.class );
+
+		Validator validator = hibernateValidatorFactory.usingContext()
+				.constraintValidatorPayload( "US" )
+				.getValidator();
+
+		// [...] US specific validation checks
+
+		validator = hibernateValidatorFactory.usingContext()
+				.constraintValidatorPayload( "FR" )
+				.getValidator();
+
+		// [...] France specific validation checks
+
+		//end::setConstraintValidatorPayloadInValidatorContext[]
+	}
+}

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter06/constraintvalidatorpayload/ZipCode.java

@@ -0,0 +1,27 @@
+package org.hibernate.validator.referenceguide.chapter06.constraintvalidatorpayload;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE_USE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import javax.validation.Constraint;
+import javax.validation.Payload;
+
+@Target({ METHOD, FIELD, ANNOTATION_TYPE, TYPE_USE })
+@Retention(RUNTIME)
+@Constraint(validatedBy = ZipCodeValidator.class)
+@Documented
+public @interface ZipCode {
+
+	String message() default "{org.hibernate.validator.referenceguide.chapter06.constraintvalidatorpayload.ZipCode.message}";
+
+	Class<?>[] groups() default { };
+
+	Class<? extends Payload>[] payload() default { };
+}

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter06/constraintvalidatorpayload/ZipCodeValidator.java

@@ -0,0 +1,45 @@
+//tag::include[]
+package org.hibernate.validator.referenceguide.chapter06.constraintvalidatorpayload;
+
+//end::include[]
+
+import javax.validation.ConstraintValidatorContext;
+import javax.validation.metadata.ConstraintDescriptor;
+
+import org.hibernate.validator.constraintvalidation.HibernateConstraintValidator;
+import org.hibernate.validator.constraintvalidation.HibernateConstraintValidatorInitializationContext;
+
+//tag::include[]
+public class ZipCodeValidator implements HibernateConstraintValidator<ZipCode, String> {
+
+	public String countryCode;
+
+	@Override
+	public void initialize(ConstraintDescriptor<ZipCode> constraintDescriptor,
+			HibernateConstraintValidatorInitializationContext initializationContext) {
+		this.countryCode = initializationContext
+				.getConstraintValidatorPayload( String.class );
+	}
+
+	@Override
+	public boolean isValid(String object, ConstraintValidatorContext constraintContext) {
+		if ( object == null ) {
+			return true;
+		}
+
+		boolean isValid = false;
+
+		if ( "US".equals( countryCode ) ) {
+			// checks specific to the United States
+		}
+		else if ( "FR".equals( countryCode ) ) {
+			// checks specific to France
+		}
+		else {
+			// ...
+		}
+
+		return isValid;
+	}
+}
+//end::include[]

engine/src/main/java/org/hibernate/validator/HibernateValidatorConfiguration.java

@@ -298,4 +298,16 @@ public interface HibernateValidatorConfiguration extends Configuration<Hibernate
 	 */
 	@Incubating
 	HibernateValidatorConfiguration temporalValidationTolerance(Duration temporalValidationTolerance);
+
+	/**
+	 * Allows to set a payload which will be passed to the constraint validators.
+	 *
+	 * @param constraintValidatorPayload the payload passed to constraint validators
+	 *
+	 * @return {@code this} following the chaining method pattern
+	 *
+	 * @since 6.0.8
+	 */
+	@Incubating
+	HibernateValidatorConfiguration constraintValidatorPayload(Object constraintValidatorPayload);
 }

engine/src/main/java/org/hibernate/validator/HibernateValidatorContext.java

@@ -153,4 +153,16 @@ public interface HibernateValidatorContext extends ValidatorContext {
 	 */
 	@Incubating
 	HibernateValidatorContext temporalValidationTolerance(Duration temporalValidationTolerance);
+
+	/**
+	 * Define a payload passed to the constraint validators.
+	 *
+	 * @param constraintValidatorPayload the payload passed to constraint validators
+	 *
+	 * @return {@code this} following the chaining method pattern
+	 *
+	 * @since 6.0.8
+	 */
+	@Incubating
+	HibernateValidatorContext constraintValidatorPayload(Object constraintValidatorPayload);
 }

engine/src/main/java/org/hibernate/validator/constraintvalidation/HibernateConstraintValidatorInitializationContext.java

@@ -55,4 +55,14 @@ public interface HibernateConstraintValidatorInitializationContext {
 	 * @return the tolerance
 	 */
 	Duration getTemporalValidationTolerance();
+
+	/**
+	 * Returns an instance of the specified type or {@code null} if no constraint validator payload of the given type
+	 * has been set.
+	 *
+	 * @param type the type of payload to retrieve
+	 * @return an instance of the specified type or null if no payload of this type has been set
+	 * @since 6.0.8
+	 */
+	<C> C getConstraintValidatorPayload(Class<C> type);
 }

engine/src/main/java/org/hibernate/validator/internal/engine/ConfigurationImpl.java

@@ -102,6 +102,7 @@ public class ConfigurationImpl implements HibernateValidatorConfiguration, Confi
 	private boolean traversableResolverResultCacheEnabled = true;
 	private ScriptEvaluatorFactory scriptEvaluatorFactory;
 	private Duration temporalValidationTolerance;
+	private Object constraintValidatorPayload;
 
 	public ConfigurationImpl(BootstrapState state) {
 		this();
@@ -285,6 +286,14 @@ public HibernateValidatorConfiguration temporalValidationTolerance(Duration temp
 		return this;
 	}
 
+	@Override
+	public HibernateValidatorConfiguration constraintValidatorPayload(Object constraintValidatorPayload) {
+		Contracts.assertNotNull( constraintValidatorPayload, MESSAGES.parameterMustNotBeNull( "constraintValidatorPayload" ) );
+
+		this.constraintValidatorPayload = constraintValidatorPayload;
+		return this;
+	}
+
 	public boolean isAllowParallelMethodsDefineParameterConstraints() {
 		return this.methodValidationConfigurationBuilder.isAllowParallelMethodsDefineParameterConstraints();
 	}
@@ -437,6 +446,10 @@ public Duration getTemporalValidationTolerance() {
 		return temporalValidationTolerance;
 	}
 
+	public Object getConstraintValidatorPayload() {
+		return constraintValidatorPayload;
+	}
+
 	@Override
 	public Set<ValueExtractor<?>> getValueExtractors() {
 		return validationBootstrapParameters.getValueExtractorDescriptors()

engine/src/main/java/org/hibernate/validator/internal/engine/ValidationContext.java

@@ -711,6 +711,11 @@ static class ValidatorScopedContext {
 		 */
 		private final boolean traversableResolverResultCacheEnabled;
 
+		/**
+		 * Hibernate Validator specific payload passed to the constraint validators.
+		 */
+		private final Object constraintValidatorPayload;
+
 		ValidatorScopedContext(ValidatorFactoryScopedContext validatorFactoryScopedContext) {
 			this.messageInterpolator = validatorFactoryScopedContext.getMessageInterpolator();
 			this.parameterNameProvider = validatorFactoryScopedContext.getParameterNameProvider();
@@ -719,6 +724,7 @@ static class ValidatorScopedContext {
 			this.scriptEvaluatorFactory = validatorFactoryScopedContext.getScriptEvaluatorFactory();
 			this.failFast = validatorFactoryScopedContext.isFailFast();
 			this.traversableResolverResultCacheEnabled = validatorFactoryScopedContext.isTraversableResolverResultCacheEnabled();
+			this.constraintValidatorPayload = validatorFactoryScopedContext.getConstraintValidatorPayload();
 		}
 
 		public MessageInterpolator getMessageInterpolator() {
@@ -748,6 +754,10 @@ public boolean isFailFast() {
 		public boolean isTraversableResolverResultCacheEnabled() {
 			return this.traversableResolverResultCacheEnabled;
 		}
+
+		public Object getConstraintValidatorPayload() {
+			return this.constraintValidatorPayload;
+		}
 	}
 
 	/**

engine/src/main/java/org/hibernate/validator/internal/engine/ValidatorContextImpl.java

@@ -137,6 +137,12 @@ public HibernateValidatorContext temporalValidationTolerance(Duration temporalVa
 		return this;
 	}
 
+	@Override
+	public HibernateValidatorContext constraintValidatorPayload(Object dynamicPayload) {
+		validatorFactoryContextBuilder.setConstraintValidatorPayload( dynamicPayload );
+		return this;
+	}
+
 	@Override
 	public Validator getValidator() {
 		return validatorFactory.createValidator(