Endpoint Method Validation

In Hilla, the parameters of an endpoint method are automatically validated and, if validation fails, a corresponding response is sent back to the browser.

Whenever a Hilla endpoint method is invoked, its parameters are automatically validated using the 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 side if the validation fails. The browser raises an EndpointValidationError when it 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 provided by the javax.validation.validation-api dependency. They are intended to be placed on Java beans on the server side.

You can find a full list of the constraints here: https://beanvalidation.org/2.0/spec#builtinconstraints

All that is required to use these annotations is to add them 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

It is possible to create custom constraints. To do this, you need to create a custom annotation and a custom validator.

Refer to the official documentation for more details.

Manual Validation

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

In order do to this, you can use code similar to the following 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 required, it is possible to throw an EndpointValidationException 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.

Hilla Validation Implementation Details

Hilla validates only the beans and method parameters that are used in the endpoint classes (that is, classes carrying the @Endpoint annotation). No other types are validated, even if they have 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 an EndpointValidationError. A similar effect is achieved if an EndpointValidationException is thrown by any of the Java endpoint methods.

Hilla Documentation