Constraints are applied to JavaBeans as either static constraints or dynamic constraints.

Static constraints are an integral part of any JavaBean. For example, com.elasticpath.domain.customer.Customer has the following constraints:

  @NotNull
  @NotBlank
  @Size(max = GlobalConstants.SHORT_TEXT_MAX_LENGTH)
  String getUsername();

Dynamic constraints are added conditionally at runtime. For example, the constraints for com.elasticpath.domain.cartmodifier.CartItemModifierField are specified in the database and applied at the runtime during the validation process.

Every constraint has a default set of fields required by its specification. For example the javax.validation.constraints.NotNull constraint has the following fields:

  @Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER})
  @Retention(RetentionPolicy.RUNTIME)
  @Documented
  @Constraint(
      validatedBy = {}
  )
  public @interface NotNull {
      String message() default "{javax.validation.constraints.NotNull.message}";
      Class<?>[] groups() default {};
      Class<? extends Payload>[] payload() default {};
      
      @Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER})
      @Retention(RetentionPolicy.RUNTIME)
      @Documented
      public @interface List {
          NotNull[] value();
    }
  } 

Generally, every constraint has a message field where a plain text or a message property key is specified. The validation frameworks will try to interpolate the message by looking at the ValidationMessages.properties file, if it exists. If a key is found, the message value is returned. Otherwise, any value specified in the message field is presented as is. The validation frameworks may also provide the means to override the messaging mechanism so that message key-value pairs can be specified in a file other than ValidationMessages.properties.

Upon validation of a bean in Commerce Engine, the framework returns zero or more ConstraintViolation instances. The ConstraintViolation objects are then transformed into a collection com.elasticpath.common.dto.StructuredErrorMessage objects which Cortex can consume.

If custom (non JSR-303/349) validation is performed, the implementer must create an instance of a StructuredErrorMessage and provide required data:

  public class StructuredErrorMessage {
      private final String messageId;
      private final String debugMessage;
      private final Map<String, String> data;
  }     

Where:

• messageId contains the message property key used by the client developer for further message customization and presentation.
• debugMessage is a text description of the error as a debugging convenience.
• data is a map that may contain additional data, like a field name and its invalid value as well as optional placeholders (for example, expected min/max values) that may provide a meaningful and understandable response.

If validation fails, the application developer must call the transformer and throw a new com.elasticpath.commons.exception.EpValidationException. They must then attach the set of validation errors.

For example, this might be an exception thrown by CustomerServiceImpl:

  Set<ConstraintViolation<Customer>> customerViolations = validator.validate(customer);
  if (CollectionUtils.isNotEmpty(customerViolations)) {
  
      // Attach the validation errors
      List<StructuredErrorMessage> structuredErrorMessageList = constraintViolationTransformer.transform(customerViolations);
        
      // Throw the exception
      throw new EpValidationException("Customer validation failure.", structuredErrorMessageList);
  }      

Apart from conversion, the transformer is also responsible for proper mapping and normalization of message keys, that can be further localized by the application developer. The normalization is done using a map, defined in commerce-engine/core/ep-core/src/main/resources/spring/commons/structuredErrorMessage.xml, which can be expanded further if needed.

The second transformation is from StructuredErrorMessage to com.elasticpath.rest.advise.Message which is wrapped in a ResourceOperationFailure. Once the EpValidationException is thrown, it has to be handled in the upper layer (Cortex) where another transformation takes place.

The following example shows how a com.elasticpath.commons.exception.EpValidationException is handled by CustomerRepositoryImpl. ReactiveAdapter methods handle EpValidationException (HTTP 400) exceptions automatically, and return appropriate structured error messages.

  return reactiveAdapter.fromServiceAsCompletable(() -> customerService.update(customer));

Under the covers a StructuredErrorMessageTransformer is used. The transformer also performs additional normalization of message keys, by utilizing a map defined in structuredMessage.xml. The map is created based on javax.validation.ConstraintViolation.propertyPath property which captures the bean's field name being validated.

The final transformation transforms com.elasticpath.rest.advise.Message to a set of com.elasticpath.schema.StructuredMessage. This step is transparent to the application developer and no further customization is required at this level.

Standard validators cannot be changed in terms of their functionality, but can be extended.

While you can customize a constraint's existing properties like message, or its custom properties, like min or max, you cannot extend the constraint itself.

In the event that you need more functionality, you can either add a new field to an existing constraint, create a new constraint (and thus a new validation error), or create a new method.