Endpoint Method Validation
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’s 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’s 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’s 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’s possible to throw an EndpointValidationException
from the endpoint method.
This exception will be caught by TypeScript and the corresponding EndpointValidationError
will be raised.
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.