From cbc01c51b0daf0b1f88de9df8ea52a54a0a4003c Mon Sep 17 00:00:00 2001
From: marko-bekhta <marko.prykladna@gmail.com>
Date: Tue, 21 Oct 2025 15:21:16 +0200
Subject: [PATCH] [#271] Add an initialization context to the init method of
 the constraint validator

---
 .../validation/ConstraintValidator.java       | 21 +++++++++
 ...straintValidatorInitializationContext.java | 43 +++++++++++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 src/main/java/jakarta/validation/ConstraintValidatorInitializationContext.java

diff --git a/src/main/java/jakarta/validation/ConstraintValidator.java b/src/main/java/jakarta/validation/ConstraintValidator.java
index 468e54ff..7a8f7278 100644
--- a/src/main/java/jakarta/validation/ConstraintValidator.java
+++ b/src/main/java/jakarta/validation/ConstraintValidator.java
@@ -9,6 +9,7 @@
 import java.lang.annotation.Annotation;
 
 import jakarta.validation.constraintvalidation.SupportedValidationTarget;
+import jakarta.validation.metadata.ConstraintDescriptor;
 
 /**
  * Defines the logic to validate a given constraint {@code A}
@@ -34,6 +35,26 @@
  */
 public interface ConstraintValidator<A extends Annotation, T> {
 
+	/**
+	 * Initializes the validator in preparation for
+	 * {@link #isValid(Object, ConstraintValidatorContext)} calls.
+	 * The constraint annotation descriptor for a given constraint declaration is passed.
+	 * <p>
+	 * This method is guaranteed to be called before any use of this instance for validation.
+	 * <p>
+	 * The default implementation is a no-op.
+	 * <p>
+	 * Validation providers are expected to call this method only. {@code ConstraintValidator}s should implement only one of the initialize methods.
+	 * Either this one, which will be directly called by the validation provider, or the {@link #initialize(Annotation)},
+	 * which will be called through the default implementation of the current method.
+	 *
+	 * @param constraintDescriptor annotation instance for a given constraint declaration
+	 * @param context context in which the constraint is initialized
+	 */
+	default void initialize(ConstraintDescriptor<A> constraintDescriptor, ConstraintValidatorInitializationContext context) {
+		initialize( constraintDescriptor.getAnnotation() );
+	}
+
 	/**
 	 * Initializes the validator in preparation for
 	 * {@link #isValid(Object, ConstraintValidatorContext)} calls.
diff --git a/src/main/java/jakarta/validation/ConstraintValidatorInitializationContext.java b/src/main/java/jakarta/validation/ConstraintValidatorInitializationContext.java
new file mode 100644
index 00000000..9908fbe5
--- /dev/null
+++ b/src/main/java/jakarta/validation/ConstraintValidatorInitializationContext.java
@@ -0,0 +1,43 @@
+/*
+ * Jakarta Validation API
+ *
+ * License: Apache License, Version 2.0
+ * See the license.txt file in the root directory or <http://www.apache.org/licenses/LICENSE-2.0>.
+ */
+package jakarta.validation;
+
+import java.time.Clock;
+
+/**
+ * Provides contextual data and operations when initializing a constraint validator.
+ *
+ * @author Marko Bekhta
+ * @since 4.0
+ */
+public interface ConstraintValidatorInitializationContext {
+
+	/**
+	 * Returns the provider for obtaining the current time in the form of a {@link Clock},
+	 * e.g. when validating the {@code Future} and {@code Past} constraints.
+	 *
+	 * @return the provider for obtaining the current time, never {@code null}. If no
+	 * specific provider has been configured during bootstrap, a default implementation using
+	 * the current system time and the current default time zone as returned by
+	 * {@link Clock#systemDefaultZone()} will be returned.
+	 */
+	ClockProvider getClockProvider();
+
+	/**
+	 * Returns an instance of the specified type allowing access to
+	 * provider-specific APIs. If the Jakarta Validation provider
+	 * implementation does not support the specified class,
+	 * {@link ValidationException} is thrown.
+	 *
+	 * @param type the class of the object to be returned
+	 * @param <T> the type of the object to be returned
+	 * @return an instance of the specified class
+	 * @throws ValidationException if the provider does not support the call
+	 * @since 4.0
+	 */
+	<T> T unwrap(Class<T> type);
+}