endpoint-methods-validation.asciidoc

title	order	layout
Appendix: Endpoint Methods Validation	150	page

Appendix: Endpoint Methods Validation

Whenever a Vaadin endpoint method is invoked, its parameters are automatically validated using JSR 380 Bean validation specification after they are deserialized from the endpoint request body.

This is useful in eliminating the boilerplate needed for the initial request validation — the framework automatically checks the constraints placed on beans and sends the response back to the client part, if the validation fails. The browser raises the EndpointValidationError when receives the corresponding response from the server.

Built-in validation constraints and how to use them

The built-in validation constraints are the set of annotations brought by the javax.validation.validation-api dependency and intended to be placed on Java beans on the server side.

Full list of the constraints can be found here: https://beanvalidation.org/2.0/spec/#builtinconstraints

All that is required to use those annotations is to add those to the class field or method parameter. Example:

public class Account {

  @Positive
  private Long id;

  @NotEmpty(message = "Each account must have a non-empty username")
  private String username;

  private void sendAccountData(@NotNull String destination) {
    // ...
  }
}

Custom validation constraints

There’s a possibility to create custom constraints, in order to do that, a custom annotation and a custom validator need to be created.

Refer to the official documentation for more details.

Manual validation

Since all the dependencies needed for validating beans and methods are present, it’s possible to reuse those in any part of the project, not only the endpoint methods.

In order do to that, you can use the code similar to the next example:

// A validator for validating beans
Validator validator = Validation.buildDefaultValidatorFactory().getValidator();
// non-empty set if there are any constraint validation errors
Set<ConstraintViolation<Object>> violations = validator.validate(bean);

// A validator for validating methods and constructors (return values, parameters)
ExecutableValidator executableValidator = validator.forExecutables();
// non-empty set if there are any constraint validation errors
Set<ConstraintViolation<Object>> violations = executableValidator.validateReturnValue(object, method, returnValue);

If needed, it’s possible to throw a EnpointValidationException from the endpoint method. This exception will be caught by TypeScript and the corresponding EndpointValidationError will be raised.

See the official documentation for more details on validating bean and method constraints.

Vaadin validation implementation details

Vaadin validates only the beans and method parameters that are used in the endpoint classes (classes, annotated with @Endpoint annotation). No other types are validated, even if they have a constraint annotations on them.

If any validation errors occur, a non-200 response is sent back which is interpreted in TypeScript as a reason to throw a EndpointValidationError. Similar effect is achieved if a EnpointValidationException is thrown by any of the Java endpoint methods.