Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Java Bean Validation

Java Bean Validation

Java Bean Validation, also known as JSR-303, is an annotation based validation specification for validating fields on objects. Java Bean Validation uses flexible annotations, which can be overridden or extended through the Java code or in an XML file, to apply validation constraints.

Elastic Path uses the Apache BVal implementation of JSR-303 in our Customer and Attribute domain objects to validate incoming information.

Apache BVal provides:

  • Spring support
  • Customizable constraints
  • Extensible validation
  • Constraint grouping

The Elastic Path platform uses BVal in the following locations:

  • Customer Fields in Customer.java
  • Addresses Fields in Address.java
  • Attributes Fields (Short-Text, Long-Text, and Short-Text multivalue) in AttributeValueWithType.java

To get started with Java Bean Validation, take a look at the following documentation:

This section gives an overview on how Elastic Path uses Java Bean Validation.

Constraint Annotations

Constraints specify the criteria the validation framework uses to determine if an object is valid. In Bean Validation, constraints are primarily provided in the form of annotations.

In Elastic Path, annotations are placed directly above an object's interfaces, classes, fields, and getter methods as shown:

@RegisteredCustomerPasswordNotBlankWithSize(min = Customer.MINIMUM_PASSWORD_LENGTH, max = GlobalConstants.SHORT_TEXT_MAX_LENGTH)
public interface Customer extends Entity, UserDetails, DatabaseLastModifiedDate {

...


	/**
	 * Get the username.
	 *
	 * @return the username
	 */
	@Override
	@NotNull
	@NotBlank
	@Size(max = GlobalConstants.SHORT_TEXT_MAX_LENGTH)
	@CustomerUsernameCheck
	String getUsername();

Common Annotations

The following table lists some common bean validation annotations in the Elastic Path code:

Annotation Purpose
@NotNull Verifies the value is not null.
@Email Verifies the email address is valid.
@Size Verifies a value's length is between the minimum and maximum value
@Valid Verifies the value passed validation

In addition, there are custom Elastic Path Bean Validation annotations. Some are listed in the following table:

Annotation Purpose
@NotBlank Verifies a field is not empty and containing only whitespace.
@EpEmail Verifies an email has a "." in the domain name. For example: Oliver@elasticpath.com
@AttributeRequired Verifies an entity's required attributes are defined.
@ValidCountry Verifies a country and sub-country are valid.
@CustomerUsernameUserIdModeEmail

Verifies a user name is valid.
@RegisteredCustomerPasswordNotBlankWithSize

Verifies a password is valid.

Custom Annotations

In addition to the out-of-the-box annotations, you can create custom constraints to suit your needs. For more information on how to create custom constraints, see Creating a Custom Constraint.

Validation Groups

Bean Validation supports group validation, which allows you to group constraints into subsets that validate input at different times.

By default, constraints do not validate in a particular order. However, you can specify a validation order by using validation groups. For example, you can create two groups to validate a country / sub-country relationship. In the first group, you verify that the country exists. In the second group, you verify the sub-country exists within the country.

XML Constraints

In Bean Validation, constraints can be specified in an XML file. This allows you to overwrite or extend an entity's validation without modifying the entity's source code. For more information on how to use XML constraints, refer to Applying Constraints with XML.

Validating an entity

To validate entities in Elastic Path:

  1. Get the validator instance
  2. Pass the object to the validator through the validate(object) method

For example, this is how you validate a customer:

Validator validator = beanFactory.getBean("validator");
Set<ConstraintViolation<Customer>> violations = validator.validate(customer);

The validate(object) method returns a set of constraint violations. If this set is empty, the object passes validation. Otherwise, you can pass the constraint violations set to loggers or UI widgets to display validation errors.