Chapter 19. Bean Validation Support

The JAX-RS Server API provides support for extracting request values and mapping them into Java fields, properties and parameters using annotations such as @HeaderParam, @QueryParam, etc. It also supports mapping of the request entity bodies into Java objects via non-annotated parameters (i.e., parameters without any JAX-RS annotations).

The Bean Validation specification supports the use of constraint annotations as a way of declaratively validating beans, method parameters and method returned values. For example, consider resource class from Example 19.3, “Constraint annotations on input parameters” augmented with constraint annotations.

@Path("/")
class MyResourceClass {

    @POST
    @Consumes("application/x-www-form-urlencoded")
    public void registerUser(
            @NotNull @FormParam("firstName") String firstName,
            @NotNull @FormParam("lastName") String lastName,
            @Email @FormParam("email") String email) {
        ...
    }
}

The annotations @NotNull and @Email impose additional constraints on the form parameters firstName, lastName and email. The @NotNull constraint is built-in to the Bean Validation API; the @Email constraint is assumed to be user defined in the example above. These constraint annotations are not restricted to method parameters, they can be used in any location in which JAX-RS binding annotations are allowed with the exception of constructors and property setters.

Rather than using method parameters, the MyResourceClass shown above could have been written as in Example 19.4, “Constraint annotations on fields”.

@Path("/")
class MyResourceClass {

    @NotNull
    @FormParam("firstName")
    private String firstName;

    @NotNull
    @FormParam("lastName")
    private String lastName;

    private String email;

    @FormParam("email")
    public void setEmail(String email) {
        this.email = email;
    }

    @Email
    public String getEmail() {
        return email;
    }

    ...
}

Note that in this version, firstName and lastName are fields initialized via injection and email is a resource class property. Constraint annotations on properties are specified in their corresponding getters.

Constraint annotations are also allowed on resource classes. In addition to annotating fields and properties, an annotation can be defined for the entire class. Let us assume that @NonEmptyNames validates that one of the two name fields in MyResourceClass is provided. Using such an annotation, the example above can be extended to look like Example 19.5, “Constraint annotations on class”

@Path("/")
@NonEmptyNames
class MyResourceClass {

    @NotNull
    @FormParam("firstName")
    private String firstName;

    @NotNull
    @FormParam("lastName")
    private String lastName;

    private String email;

    ...
}

Constraint annotations on resource classes are useful for defining cross-field and cross-property constraints.

Annotation constraints and validators are defined in accordance with the Bean Validation specification. The @Email annotation used in Example 19.4, “Constraint annotations on fields” is defined using the Bean Validation @Constraint meta-annotation, see Example 19.6, “Definition of a constraint annotation”.

@Target({ METHOD, FIELD, PARAMETER })
@Retention(RUNTIME)
@Constraint(validatedBy = EmailValidator.class)
public @interface Email {

    String message() default "{com.example.validation.constraints.email}";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

The @Constraint annotation must include a reference to the validator class that will be used to validate decorated values. The EmailValidator class must implement ConstraintValidator<Email, T> where T is the type of values being validated, as described in Example 19.7, “Validator implementation.”.

public class EmailValidator implements ConstraintValidator<Email, String> {

    public void initialize(Email email) {
        ...
    }

    public boolean isValid(String value, ConstraintValidatorContext context) {
        ...
    }
}

Thus, EmailValidator applies to values annotated with @Email that are of type String. Validators for other Java types can be defined for the same constraint annotation.

Request entity bodies can be mapped to resource method parameters. There are two ways in which these entities can be validated. If the request entity is mapped to a Java bean whose class is decorated with Bean Validation annotations, then validation can be enabled using @Valid as in Example 19.8, “Entity validation”.

@StandardUser
class User {

    @NotNull
    private String firstName;

    ...
}


@Path("/")
class MyResourceClass {

    @POST
    @Consumes("application/xml")
    public void registerUser(@Valid User user) {
        ...
    }
}

In this case, the validator associated with @StandardUser (as well as those for non-class level constraints like @NotNull) will be called to verify the request entity mapped to user.

Alternatively, a new annotation can be defined and used directly on the resource method parameter (Example 19.9, “Entity validation 2”).

@Path("/")
class MyResourceClass {

    @POST
    @Consumes("application/xml")
    public void registerUser(@PremiumUser User user) {
        ...
    }
}

In the example above, @PremiumUser rather than @StandardUser will be used to validate the request entity. These two ways in which validation of entities can be triggered can also be combined by including @Valid in the list of constraints. The presence of @Valid will trigger validation of all the constraint annotations decorating a Java bean class.

Response entity bodies returned from resource methods can be validated in a similar manner by annotating the resource method itself. To exemplify, assuming both @StandardUser and @PremiumUser are required to be checked before returning a user, the getUser method can be annotated as shown in Example 19.10, “Response entity validation”.

@Path("/")
class MyResourceClass {

    @GET
    @Path("{id}")
    @Produces("application/xml")
    @Valid @PremiumUser
    public User getUser(@PathParam("id") String id) {
        User u = findUser(id);
        return u;
    }

    ...
}

Note that @PremiumUser is explicitly listed and @StandardUser is triggered by the presence of the @Valid annotation - see definition of User class earlier in this section.

The rules for inheritance of constraint annotation are defined in Bean Validation specification. It is worth noting that these rules are incompatible with those defined by JAX-RS. Generally speaking, constraint annotations in Bean Validation are cumulative (can be strengthen) across a given type hierarchy while JAX-RS annotations are inherited or, overridden and ignored.

For Bean Validation annotations Jersey follows the constraint annotation rules defined in the Bean Validation specification.

By default, (during mapping ConstraintViolationExceptions) Jersey doesn't return any entities that would include validation errors to the client. This default behaviour could be changed by enabling ServerProperties.BV_SEND_ERROR_IN_RESPONSE property in your application (Example 19.1, “Configuring Jersey specific properties for Bean Validation.”). When this property is enabled then our custom ExceptionMapper<E extends Throwable> (that is handling ValidationExceptions) would transform ConstraintViolationException(s) into ValidationError(s) and set this object (collection) as the new response entity which Jersey is able to sent to the client. Four MediaTypes are currently supported when sending ValidationErrors to the client:

Let's take a look at ValidationError class to see which properties are send to the client:

@XmlRootElement
public final class ValidationError {

    private String message;

    private String messageTemplate;

    private String path;

    private String invalidValue;

    ...
}

The message property is the interpolated error message, messageTemplate represents a non-interpolated error message (or key from your constraint definition e.g. {jakarta.validation.constraints.NotNull.message}), path contains information about the path in the validated object graph to the property holding invalid value and invalidValue is the string representation of the invalid value itself.

Here are few examples of ValidationError messages sent to client:

HTTP/1.1 500 Internal Server Error
Content-Length: 114
Content-Type: text/plain
Vary: Accept
Server: Jetty(6.1.24)

Contact with given ID does not exist. (path = ContactCardResource.getContact.<return value>, invalidValue = null)

HTTP/1.1 500 Internal Server Error
Content-Length: ...
Content-Type: text/plain
Vary: Accept
Server: Jetty(6.1.24)

<div class="validation-errors">
    <div class="validation-error">
        <span class="message">Contact with given ID does not exist.</span>
        (
        <span class="path">
            <strong>path</strong>
            = ContactCardResource.getContact.<return value>
        </span>
        ,
        <span class="invalid-value">
            <strong>invalidValue</strong>
            = null
        </span>
        )
    </div>
</div>

HTTP/1.1 500 Internal Server Error
Content-Length: ...
Content-Type: text/plain
Vary: Accept
Server: Jetty(6.1.24)

<?xml version="1.0" encoding="UTF-8"?>
<validationErrors>
    <validationError>
        <message>Contact with given ID does not exist.</message>
        <messageTemplate>{contact.does.not.exist}</messageTemplate>
        <path>ContactCardResource.getContact.&lt;return value&gt;</path>
    </validationError>
</validationErrors>

HTTP/1.1 500 Internal Server Error
Content-Length: 174
Content-Type: application/json
Vary: Accept
Server: Jetty(6.1.24)

[ {
   "message" : "Contact with given ID does not exist.",
   "messageTemplate" : "{contact.does.not.exist}",
   "path" : "ContactCardResource.getContact.<return value>"
} ]