To define a new Bean Validation annotation, create an @interface file with four annotations, @Target, @Retention, @Constraint, @Documented, and three attributes, message(), group(), payload():

package com.example.validation.constraints;

...

import com.elasticpath.domain.validators.PersonAvailableValidator;

@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = PersonAvailableValidator.class)
@Documented
public @interface PersonAvailable {

    String message() default "{com.example.validation.validators.impl.PersonAvailableValidator}";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

Standard Annotations:

• @Target - Defines the annotatable elements. The above example sets the @PersonAvailable annotation for type declarations, methods, fields, and other annotations.
• @Retention - Defines when the annotation applies. For Bean Validation annotations, this must be RUNTIME.
• @Constraint - Defines the annotation's validator. This example uses a custom validator named PersonAvailableValidator.
• @Documented - Includes the @PersonAvailable annotation on the Javadoc for all elements annotated with @PersonAvailable.

Standard attributes:

• message() - The message to display if this constraint is violated.
• groups() - The validation group associated with the constraint. According to the Bean Validation specification, you must give an empty array of type Class<?> as the default value.
• payload() - The constraint's payload. A payload is any additional metadata that should be associated with the constraint, such as the violation's severity rating. According to the Bean Validation specification, you must give an empty array of type Class<? extends Payload> as the default value.

The validator determines an element's validity. To define a validator, create a class that implements the ConstraintValidator interface, which requires two parameters and two method implementations:

package com.example.validation.validators.impl;

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

...

public class PersonAvailableValidator implements ConstraintValidator<PersonAvailable, Person> {

	...

	public void initialize(PersonAvailable constraintAnnotation) {
        // do nothing
    }

    public boolean isValid(Person value, ConstraintValidatorContext context) {
        if(personService.isPersonOldEnough(value)) {
            return true;
        }

		final String message = "{com.example.validation.validators.impl.PersonAvailableValidator.age.message}";

		context.disableDefaultConstraintViolation();
        context.buildConstraintViolationWithTemplate(message).addNode("personAvailable").addConstraintViolation();

		return false;
	}
}

ConstraintValidator parameters:

• PersonAvailable - The custom annotation described in the preceding section.
• Person - The entity the custom validator verifies.

ConstraintValidator method implementations:

• initialize() - Sets the validator's fields with additional data from the annotation. If the annotation has no parameters, this method does nothing.
• isValid() - Validates the entity and returns TRUE or FALSE depending on the entity's validity.

A single validator's isValid() method can contain multiple conditions. You can return a different violation message for each condition by specifying custom messages. As you can see inside the example isValid() method, three tasks are done to specify a custom message:

• Define a string for the ValidationMessages.properties message.
• Stop the ConstraintValidator from returning the default message.
• Add the ValidationMessages.properties message to the constraint violations set. The constraint violations set is what the validate(object)method returns at the end of the validation process.

The ValidationMessages.properties file contains the constraint violation messages that Bean Validation returns when custom constraints are violated. In ValidationMessages.properties, define messages in key-value pairs. For example, the ValidationMessages.properties file for @PersonAvailable looks like this:

com.example.validation.validators.impl.PersonAvailableValidator.age.message=This person is not old enough.

You want to customize the out of the box password constraints.

To add these additional constraints, you can create a custom Bean Validation constraint that matches customer passwords with regular expressions.

The tutorial source code is in an Elastic Path extension project:

• <extension_project_root>/src/main
  • java
    • com.example.validation
      • constraints
        • RegisteredCustomerPasswordWithRegex.java
      • validators
        • RegisteredCustomerPasswordWithRegexValidator.java
  • resources
    • ValidationMessages.properties

The following @interface creates a Bean Validation annotation named @RegisteredCustomerPasswordWithRegex:

package com.example.validation.constraints;

import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import javax.validation.Constraint;
import javax.validation.Payload;

import com.example.validation.validators.impl.RegisteredCustomerPasswordWithRegexValidator;

/**
 *
 * Additional validation on the OOTB CustomerPasswordCheck annotation.
 */
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = RegisteredCustomerPasswordWithRegexValidator.class)
@Documented
public @interface RegisteredCustomerPasswordWithRegex {

    /** Regular expression to validate against on the password field. */
    String regex();

    /** Constraint violation message. */
    String message() default "{com.example.validation.constraints.RegisteredCustomerPasswordWithRegex.message}";

    /** Groups associated to this constraint. */
    Class<?>[] groups() default { };

    /** Payload for the constraint. */
    Class<? extends Payload>[] payload() default { };
}

As you can see in RegisteredCustomerPasswordWithRegex, in addition to the three required attributes (message(), groups(), payload()), which are described in detail in the preceding Annotations section, we declare a regex() attribute to receive regular expressions. The regex() attribute is not given a default value. Instead, the value is passed in as a parameter when calling the annotation, which is shown later in Applying a Custom Constraint.

The validator applies regular expressions to a customer password:

package com.example.validation.validators.impl;

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import com.elasticpath.domain.customer.Customer;
import com.example.validation.constraints.RegisteredCustomerPasswordWithRegex;

/**
 * Add some extra validation to the OOTB CustomerPasswordValidator.
 */
public class RegisteredCustomerPasswordWithRegexValidator implements ConstraintValidator<RegisteredCustomerPasswordWithRegex, Customer> {

    private String regex;

    @Override
    public void initialize(final RegisteredCustomerPasswordWithRegex constraintAnnotation) {
        regex = constraintAnnotation.regex();
    };

    /**
     * {@inheritDoc} <br/>
     * Validation check for password matching against the given regular expression.
     */
    @Override
    public boolean isValid(final Customer customer, final ConstraintValidatorContext context) {
        if (customer.isAnonymous()) {
            return true;
        }

        String password = customer.getClearTextPassword();

        if (password == null) {
            return true;
        }

        if (password.matches(regex)) {
            return true;
        } else {
            addConstraintViolation("{com.example.validation.validators.impl.RegisteredCustomerPasswordWithRegexValidator.regex.message}", context);
            return false;
        }
    }

    private void addConstraintViolation(final String message, final ConstraintValidatorContext context) {
        context.disableDefaultConstraintViolation();
        context.buildConstraintViolationWithTemplate(message).addNode("person").addConstraintViolation();
    }
}

As you can see, initialize() sets the validator's regex field to the custom annotation's regex attribute, while the logic inside the isValid() method adds in additional password requirements.

isValid() validates the Customer's password if:

• The customer is anonymous. Anonymous customers don't have passwords, so they automatically pass validation in this case. In this example, it's only registered customers that require password validation.
• The password is null. In this example, matching a null password with the regex causes the validation to fail. Since Customer passwords already include a null check out-of-the-box, a null password returns two violations. To remove the redundant violation, this constraint automatically passes null passwords.
• The password matches the regular expression that was set during initialize().

isValid() invalidates the Customer's password if the password doesn't match the given regular expression. If a password is invalid, addPasswordConstraintViolation() is called to insert the com.example.validation.validators.impl.RegisteredCustomerPasswordWithRegexValidator.regex.message into the constraint validation set.

The @RegisteredCustomerPasswordWithRegex's ValidationMessages.properties file is shown below:

com.elasticpath.validation.constraints.requiredAttribute=attribute is required
com.elasticpath.validation.constraints.notBlank=must not be blank
com.elasticpath.validation.constraints.CustomerUsernameUserIdModeEmail.message=Failed username validation
com.elasticpath.validation.constraints.RegisteredCustomerPasswordNotBlankWithSize.message=Failed password validation
com.elasticpath.validation.validators.impl.RegisteredCustomerPasswordNotBlankWithSizeValidator.blank.message=Password must not be blank
com.elasticpath.validation.validators.impl.RegisteredCustomerPasswordNotBlankWithSizeValidator.size.message=Password must be between {min} to {max} characters inclusive
com.elasticpath.validation.constraints.validCountry=does not exist in list of supported codes
com.elasticpath.validation.constraints.validSubCountry=does not exist in list of supported codes
com.elasticpath.validation.constraints.subCountry.missing=must not be blank
com.elasticpath.validation.constraints.emailPattern=not a well-formed email address

com.example.validation.constraints.RegisteredCustomerPasswordWithRegex.message=Failed password regex check

The com.example.validation.validators.impl.RegisteredCustomerPasswordWithRegexValidator.regex.message property shown above defines the message Bean Validation returns when @RegisteredCustomerPasswordWithRegex is violated.