Java Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE

1. Introduction

In the tutorial Java Bean Validation Basics, we saw how we can apply javax validations using JSR 380 to various types. And in the tutorial Spring MVC Custom Validation, we saw how to create custom validations.

In this next tutorial, we'll focus on building validations for enums using custom annotations.

2. Validating Enums

Unfortunately, most standard annotations can not be applied to enums.

For example, when applying the @Pattern annotation to an enum we receive an error like this one with Hibernate Validator:

javax.validation.UnexpectedTypeException: HV000030: No validator could be found for constraint 
 'javax.validation.constraints.Pattern' validating type 'org.baeldung.javaxval.enums.demo.CustomerType'. 
 Check configuration for 'customerTypeMatchesPattern'

Actually, the only standard annotations which can be applied to enum's are @NotNull and @Null.

3. Validating the Pattern of an Enum

Let's start by defining an annotation to validate the pattern of an enum:

@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = EnumNamePatternValidator.class)
public @interface EnumNamePattern {
    String regexp();
    String message() default "must match \"{regexp}\"";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Now we can simply add this new annotation using a regular expression to our CustomerType enum:

@EnumNamePattern(regexp = "NEW|DEFAULT")
private CustomerType customerType;

As we can see, the annotation does not actually contain the validation logic. Therefore, we need to provide a ConstraintValidator:

public class EnumNamePatternValidator implements ConstraintValidator<EnumNamePattern, Enum<?>> {
    private Pattern pattern;

    @Override
    public void initialize(EnumNamePattern annotation) {
        try {
            pattern = Pattern.compile(annotation.regexp());
        } catch (PatternSyntaxException e) {
            throw new IllegalArgumentException("Given regex is invalid", e);
        }
    }

    @Override
    public boolean isValid(Enum<?> value, ConstraintValidatorContext context) {
        if (value == null) {
            return true;
        }

        Matcher m = pattern.matcher(value.name());
        return m.matches();
    }
}

In this example, the implementation is very similar to the standard @Pattern validator. However, this time, we match the name of the enum.

4. Validating a Subset of an Enum

Matching an enum with a regular expression is not type-safe. Instead, it makes more sense to compare with the actual values of an enum.

However, because of the limitations of annotations, such an annotation cannot be made generic. This is because arguments for annotations can only be concrete values of a specific enum, not instances of the enum parent class.

Let's see how to create a specific subset validation annotation for our CustomerType enum:

@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = CustomerTypeSubSetValidator.class)
public @interface CustomerTypeSubset {
    CustomerType[] anyOf();
    String message() default "must be any of {anyOf}";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

This annotation can then be applied to enums of the type CustomerType:

@CustomerTypeSubset(anyOf = {CustomerType.NEW, CustomerType.OLD})
private CustomerType customerType;

Next, we need to define the CustomerTypeSubSetValidator to check whether the list of given enum values contains the current one:

public class CustomerTypeSubSetValidator implements ConstraintValidator<CustomerTypeSubset, CustomerType> {
    private CustomerType[] subset;

    @Override
    public void initialize(CustomerTypeSubset constraint) {
        this.subset = constraint.anyOf();
    }

    @Override
    public boolean isValid(CustomerType value, ConstraintValidatorContext context) {
        return value == null || Arrays.asList(subset).contains(value);
    }
}

While the annotation has to be specific for a certain enum, we can of course share code between different validators.

5. Validating that a String Matches a Value of an Enum

Instead of validating an enum to match a String, we could also do the opposite. For this, we can create an annotation that checks if the String is valid for a specific enum.

@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = ValueOfEnumValidator.class)
public @interface ValueOfEnum {
    Class<? extends Enum<?>> enumClass();
    String message() default "must be any of enum {enumClass}";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

This annotation can be added to a String field and we can pass any enum class.

@ValueOfEnum(enumClass = CustomerType.class)
private String customerTypeString;

Let's define the ValueOfEnumValidator to check whether the String (or any CharSequence) is contained in the enum:

public class ValueOfEnumValidator implements ConstraintValidator<ValueOfEnum, CharSequence> {
    private List<String> acceptedValues;

    @Override
    public void initialize(ValueOfEnum annotation) {
        acceptedValues = Stream.of(annotation.enumClass().getEnumConstants())
                .map(Enum::name)
                .collect(Collectors.toList());
    }

    @Override
    public boolean isValid(CharSequence value, ConstraintValidatorContext context) {
        if (value == null) {
            return true;
        }

        return acceptedValues.contains(value.toString());
    }
}

This validation can especially be useful when working with JSON objects. Because the following exception appears, when mapping an incorrect value from a JSON object to an enum:

Cannot deserialize value of type CustomerType from String value 'UNDEFINED': value not one
 of declared Enum instance names: [...]

We can, of course, handle this exception. However, this does not allow us to report all violations at once.

Instead of mapping the value to an enum, we can map it to a String. We'd then use our validator to check whether it matches any of the enum values.

6. Bringing it all Together

We can now validate beans using any of our new validations. Most importantly, all of our validations accept null values. Consequently, we can also combine it with the annotation @NotNull:

public class Customer {
    @ValueOfEnum(enumClass = CustomerType.class)
    private String customerTypeString;

    @NotNull
    @CustomerTypeSubset(anyOf = {CustomerType.NEW, CustomerType.OLD})
    private CustomerType customerTypeOfSubset;

    @EnumNamePattern(regexp = "NEW|DEFAULT")
    private CustomerType customerTypeMatchesPattern;

    // constructor, getters etc.
}

In the next section, we’ll see how we can test our new annotations.

7. Testing Our Javax Validations for Enums

In order to test our validators, we'll set up a validator, which supports our newly defined annotations. We'll the Customer bean for all our tests.

First, we want to make sure that a valid Customer instance does not cause any violations:

@Test 
public void whenAllAcceptable_thenShouldNotGiveConstraintViolations() { 
    Customer customer = new Customer(); 
    customer.setCustomerTypeOfSubset(CustomerType.NEW); 
    Set violations = validator.validate(customer); 
    assertThat(violations).isEmpty(); 
}

Second, we want our new annotations to support and accept null values. We only expect a single violation. This should be reported on customerTypeOfSubset by the @NotNull annotation:

@Test
public void whenAllNull_thenOnlyNotNullShouldGiveConstraintViolations() {
    Customer customer = new Customer();
    Set<ConstraintViolation> violations = validator.validate(customer);
    assertThat(violations.size()).isEqualTo(1);

    assertThat(violations)
      .anyMatch(havingPropertyPath("customerTypeOfSubset")
      .and(havingMessage("must not be null")));
}

Finally, we validate our validators to report violations, when the input is not valid:

@Test
public void whenAllInvalid_thenViolationsShouldBeReported() {
    Customer customer = new Customer();
    customer.setCustomerTypeString("invalid");
    customer.setCustomerTypeOfSubset(CustomerType.DEFAULT);
    customer.setCustomerTypeMatchesPattern(CustomerType.OLD);

    Set<ConstraintViolation> violations = validator.validate(customer);
    assertThat(violations.size()).isEqualTo(3);

    assertThat(violations)
      .anyMatch(havingPropertyPath("customerTypeString")
      .and(havingMessage("must be any of enum class org.baeldung.javaxval.enums.demo.CustomerType")));
    assertThat(violations)
      .anyMatch(havingPropertyPath("customerTypeOfSubset")
      .and(havingMessage("must be any of [NEW, OLD]")));
    assertThat(violations)
      .anyMatch(havingPropertyPath("customerTypeMatchesPattern")
      .and(havingMessage("must match \"NEW|DEFAULT\"")));
}

8. Conclusion

In this tutorial, we covered three options to validate enums using custom annotations and validators.

First, we learned how to validate the name of an enum using a regular expression.

Second, we discussed a validation for a subset of values of a specific enum. We also explained why we cannot build a generic annotation to do this.

Finally, we also looked at how to build a validator for strings. In order to check whether a String conforms to a particular value of a given enum.

As always, the full source code of the article is available over on Github.

Java bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE
Comments are closed on this article!