HV-2073 Add new OneOfValidator for CharSequence validation

Description:
Contributed a new OneOfValidator for the Hibernate Validator project.

This validator checks if a given CharSequence matches one of the allowed values specified in the OneOf annotation.

Features:
- Validates if a CharSequence is one of the allowed values.
- Supports case-sensitive and case-insensitive validation based on the ignoreCase flag.
- Supports both Enum constants and manually provided allowed values.

The validator is implemented with the following:
- OneOfValidator class implementing ConstraintValidator<OneOf, CharSequence>.
- Adds values from allowedValues() and enumClass() in the OneOf annotation for validation.
- Provides methods to handle case-sensitive and case-insensitive validation.

Tests have been added, and all tests pass.

Author: Yusuf Alamu Musa

engine/src/main/java/org/hibernate/validator/constraints/OneOf.java

@@ -0,0 +1,39 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.validator.constraints;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import jakarta.validation.Constraint;
+import jakarta.validation.Payload;
+
+import org.hibernate.validator.internal.constraintvalidators.bv.OneOfValidator;
+
+@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
+@Retention(RUNTIME)
+@Documented
+@Constraint(validatedBy = OneOfValidator.class)
+public @interface OneOf {
+
+	String[] allowedValues() default { };
+
+	Class<? extends Enum<?>> enumClass() default DefaultEnum.class;
+
+	boolean ignoreCase() default false;
+
+	String message() default "must be one of {allowedValues} or is an invalid enum";
+
+	Class<?>[] groups() default { };
+
+	Class<? extends Payload>[] payload() default { };
+
+	enum DefaultEnum {
+	}
+}

engine/src/main/java/org/hibernate/validator/internal/constraintvalidators/bv/OneOfValidator.java

@@ -0,0 +1,121 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.validator.internal.constraintvalidators.bv;
+
+
+import static java.util.Objects.nonNull;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.stream.Stream;
+
+import jakarta.validation.ConstraintValidator;
+import jakarta.validation.ConstraintValidatorContext;
+
+import org.hibernate.validator.constraints.OneOf;
+
+/**
+ * Validator that checks if a given {@link CharSequence} matches one of the allowed values specified
+ * in the {@link OneOf} annotation.
+ *
+ * <p>This class implements the {@link ConstraintValidator} interface to perform the validation logic
+ * based on the configuration in the {@link OneOf} annotation.</p>
+ *
+ * @author Yusuf Àlàmù Musa
+ * @version 1.0
+ */
+public class OneOfValidator implements ConstraintValidator<OneOf, CharSequence> {
+
+	private final List<String> acceptedValues = new ArrayList<>();
+	private boolean ignoreCase;
+
+	/**
+	* Initializes the validator with the values specified in the {@link OneOf} annotation.
+	*
+	* <p>This method sets the case sensitivity flag and adds the allowed values (either enum constants or specified values)
+	* to the list of accepted values for validation.</p>
+	*
+	* @param constraintAnnotation the {@link OneOf} annotation containing the configuration for validation.
+	*/
+	@Override
+	public void initialize(final OneOf constraintAnnotation) {
+		ignoreCase = constraintAnnotation.ignoreCase();
+
+		// If an enum class is specified, initialize accepted values from the enum constants
+		if ( constraintAnnotation.enumClass() != null ) {
+			final Enum<?>[] enumConstants = constraintAnnotation.enumClass().getEnumConstants();
+			initializeAcceptedValues( enumConstants );
+		}
+
+		// If specific allowed values are provided, initialize accepted values from them
+		if ( constraintAnnotation.allowedValues() != null ) {
+			initializeAcceptedValues( constraintAnnotation.allowedValues() );
+		}
+	}
+
+	/**
+	* Validates the given value based on the accepted values.
+	*
+	* <p>If the value is not null, it checks whether the value matches any of the accepted values.
+	* If the value is null, it is considered valid.</p>
+	*
+	* @param value the value to validate.
+	* @param context the validation context.
+	* @return {@code true} if the value is valid, {@code false} otherwise.
+	*/
+	@Override
+	public boolean isValid(final CharSequence value, final ConstraintValidatorContext context) {
+		if ( nonNull( value ) ) {
+			return checkIfValueTheSame( value.toString() );
+		}
+		return true;
+	}
+
+	/**
+	* Checks if the provided value matches any of the accepted values.
+	*
+	* <p>If {@code ignoreCase} is false, the comparison is case-sensitive.
+	* If {@code ignoreCase} is true, the value is compared in lowercase.</p>
+	*
+	* @param value the value to check.
+	* @return {@code true} if the value matches an accepted value, {@code false} otherwise.
+	*/
+	protected boolean checkIfValueTheSame(final String value) {
+		if ( !ignoreCase ) {
+			return acceptedValues.contains( value );
+		}
+
+		for ( final String acceptedValue : acceptedValues ) {
+			if ( acceptedValue.toLowerCase( Locale.ROOT ).equals( value.toLowerCase( Locale.ROOT ) ) ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	* Initializes and adds the names of the provided enum constants to the accepted values list.
+	*
+	* @param enumConstants the enum constants to be added, ignored if null.
+	*/
+	protected void initializeAcceptedValues(final Enum<?>... enumConstants) {
+		if ( nonNull( enumConstants ) ) {
+			acceptedValues.addAll( Stream.of( enumConstants ).map( Enum::name ).toList() );
+		}
+	}
+
+	/**
+	* Initializes and adds the provided values to the accepted values list after trimming them.
+	*
+	* @param values the values to be added, ignored if null.
+	*/
+	protected void initializeAcceptedValues(final String... values) {
+		if ( nonNull( values ) ) {
+			acceptedValues.addAll( Stream.of( values ).map( String::trim ).toList() );
+		}
+	}
+}

engine/src/test/java/org/hibernate/validator/internal/constraintvalidators/bv/OneOfValidatorTest.java

@@ -0,0 +1,128 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.validator.internal.constraintvalidators.bv;
+
+import static org.easymock.EasyMock.mock;
+import static org.testng.Assert.assertFalse;
+import static org.testng.Assert.assertTrue;
+
+import jakarta.validation.ConstraintValidatorContext;
+import jakarta.validation.Payload;
+
+import org.hibernate.validator.constraints.OneOf;
+import org.hibernate.validator.testutil.TestForIssue;
+
+import org.testng.annotations.BeforeMethod;
+import org.testng.annotations.Test;
+
+public class OneOfValidatorTest {
+
+	private ConstraintValidatorContext context;
+	private OneOfValidator validator;
+
+	@BeforeMethod
+	public void setUp() {
+		validator = new OneOfValidator();
+		context = mock( ConstraintValidatorContext.class );
+	}
+
+	@Test
+	@TestForIssue(jiraKey = "HV-2073")
+	public void testIsValidNullValueShouldReturnTrue() {
+		assertTrue( validator.isValid( null, context ), "Null value should be considered valid." );
+	}
+
+	@Test
+	@TestForIssue(jiraKey = "HV-2073")
+	public void testIsValidCaseSensitiveMatchShouldReturnTrue() {
+		OneOf annotation = createOneOf( false, new String[] { "Value1", "Value2" }, null );
+
+		validator.initialize( annotation );
+
+		assertTrue( validator.isValid( "Value1", context ), "Exact case-sensitive match should return true." );
+	}
+
+	@Test
+	@TestForIssue(jiraKey = "HV-2073")
+	public void testIsValidCaseSensitiveMismatchShouldReturnFalse() {
+		OneOf annotation = createOneOf( false, new String[] { "Value1", "Value2" }, null );
+
+		validator.initialize( annotation );
+
+		assertFalse( validator.isValid( "value1", context ), "Case-sensitive mismatch should return false." );
+	}
+
+	@Test
+	public void testIsValidIgnoreCaseMatchShouldReturnTrue() {
+		OneOf annotation = createOneOf( true, new String[] { "Value1", "Value2" }, null );
+
+		validator.initialize( annotation );
+
+		assertTrue( validator.isValid( "value1", context ), "Ignore-case match should return true." );
+	}
+
+	@Test
+	public void testIsValidIgnoreCaseMismatchShouldReturnFalse() {
+		OneOf annotation = createOneOf( true, new String[] { "Value1", "Value2" }, null );
+
+		validator.initialize( annotation );
+
+		assertFalse( validator.isValid( "invalid", context ), "Ignore-case mismatch should return false." );
+	}
+
+	@Test
+	public void testInitializeEnumClassShouldAcceptEnumValues() {
+		OneOf annotation = createOneOf( false, new String[] { }, TestEnum.class );
+
+		validator.initialize( annotation );
+
+		assertTrue( validator.isValid( "ONE", context ), "Enum constant 'ONE' should be valid." );
+		assertFalse( validator.isValid( "TWO", context ), "'TWO' should not be valid as it's not in the enum." );
+	}
+
+	private OneOf createOneOf(boolean ignoreCase, String[] allowedValues, Class<? extends Enum<?>> enumClass) {
+		return new OneOf() {
+			@Override
+			public String[] allowedValues() {
+				return allowedValues;
+			}
+
+			@Override
+			public Class<? extends Enum<?>> enumClass() {
+				return enumClass;
+			}
+
+			@Override
+			public boolean ignoreCase() {
+				return ignoreCase;
+			}
+
+			@Override
+			public String message() {
+				return "";
+			}
+
+			@Override
+			public Class<?>[] groups() {
+				return new Class[0];
+			}
+
+			@Override
+			public Class<? extends Payload>[] payload() {
+				return new Class[0];
+			}
+
+			@Override
+			public Class<OneOf> annotationType() {
+				return OneOf.class;
+			}
+		};
+	}
+
+	private enum TestEnum {
+		ONE, THREE
+	}
+
+}