Validations

Almost anything can be validated on resource endpoints. To give a quick example, the following endpoint doesn’t allow a null or empty name query parameter.

@GET
public String find(@QueryParam("name") @NotEmpty String arg) {
    // ...
}

If a client sends an empty or nonexistent name query param, Dropwizard will respond with a 400 Bad Request code with the error: query param name may not be empty.

Additionally, annotations such as HeaderParam, CookieParam, FormParam, etc, can be constrained with violations giving descriptive errors and 400 status codes.

public class Person {

    @NotEmpty // ensure that name isn't null or blank
    private final String name;

    @JsonCreator
    public Person(@JsonProperty("name") String name) {
        this.name = name;
    }

    @JsonProperty("name")
    public String getName() {
        return name;
    }
}

@PUT
public Person replace(@NotNull @Valid Person person) {
    // ...
}

@POST
// The @NotNull is supposed to mean that the parameter is required but the Max(3) is supposed to
// apply to the contained integer. Currently, this code will fail saying that Max can't
// be applied on an IntParam
public List<Person> createNum(@QueryParam("num") @UnwrapValidatedValue(false)
                              @NotNull @Max(3) IntParam num) {
    // ...
}

@GET
// Similarly, the underlying validation framework can't unwrap nested types (an integer wrapped
// in an IntParam wrapped in an Optional), regardless if the @UnwrapValidatedValue is used
public Person retrieve(@QueryParam("num") @Max(3) Optional<IntParam> num) {
    // ...
}

@POST
// Workaround to handle required int params and validations
public List<Person> createNum(@QueryParam("num") @Max(3) IntParam num) {
    if (num == null) {
        throw new WebApplicationException("query param num must not be null", 400);
    }
    // ...
}

@GET
// Workaround to handle optional int params and validations with DefaultValue
public Person retrieve(@QueryParam("num") @DefaultValue("0") @Max(3) IntParam num) {
    // ...
}

@GET
// Workaround to handle optional int params and validations with Optional
public Person retrieve2(@QueryParam("num") @Max(3) IntParam num) {
    Optional.fromNullable(num);
    // ...
}

@POST
@NotNull
@Valid
public Person create() {
    return new Person(null);
}

Limitations

Jersey allows for BeanParam to have setters with *Param annotations. While nice for simple transformations it does obstruct validation, so clients won’t receive as instructive of error messages. The following example shows the behavior:

@Path("/root")
@Produces(MediaType.APPLICATION_JSON)
public class Resource {

    @GET
    @Path("params")
    public String getBean(@Valid @BeanParam MyBeanParams params) {
        return params.getField();
    }

    public static class MyBeanParams {
        @NotEmpty
        private String field;

        public String getField() {
            return field;
        }

        @QueryParam("foo")
        public void setField(String field) {
            this.field = Strings.nullToEmpty(field).trim();
        }
    }
}

A client submitting the query parameter foo as blank will receive the following error message:

{"errors":["getBean.arg0.field may not be empty"]}

Workarounds include:

• Name BeanParam fields the same as the *Param annotation values
• Supply validation message on annotation: @NotEmpty(message = "query param foo must not be empty")
• Perform transformations and validations on *Param inside endpoint

The same kind of limitation applies for Configuration objects:

public class MyConfiguration extends Configuration {
    @NotNull
    @JsonProperty("foo")
    private String baz;
}

Even though the property’s name is foo, the error when property is null will be:

* baz may not be null

Annotations

In addition to the annotations defined in Hibernate Validator, Dropwizard contains another set of annotations, which are briefly shown below.

public class Person {
    @NotEmpty
    private final String name;

    @NotEmpty
    @OneOf(value = {"m", "f"}, ignoreCase = true, ignoreWhitespace = true)
    // @OneOf forces a value to value within certain values.
    private final String gender;

    @Max(10)
    @Min(0)
    // The integer contained, if present, can attain a min value of 0 and a max of 10.
    private final Optional<Integer> animals;

    @JsonCreator
    public Person(@JsonProperty("name") String name) {
        this.name = name;
    }

    @JsonProperty("name")
    public String getName() {
        return name;
    }

    // Method that must return true for the object to be valid
    @ValidationMethod(message="name may not be Coda")
    @JsonIgnore
    public boolean isNotCoda() {
        return !"Coda".equals(name);
    }
}

The reason why Dropwizard defines @ValidationMethod is that more complex validations (for example, cross-field comparisons) are often hard to do using declarative annotations. Adding @ValidationMethod to any boolean-returning method which begins with is is a short and simple workaround:

public interface Version1Checks { }

public interface Version2Checks { }

public class Person {
    @NotEmpty(groups = Version1Checks.class)
    @Length(max = 5, groups = Version2Checks.class)
    private String name;

    @JsonCreator
    public Person(@JsonProperty("name") String name) {
        this.name = name;
    }

    @JsonProperty
    public String getName() {
        return name;
    }
}

@Path("/person")
@Produces(MediaType.APPLICATION_JSON)
public class PersonResource {
    @POST
    @Path("/v1")
    public void createPersonV1(@Valid @Validated(Version1Checks.class) Person person) {
    }

    @POST
    @Path("/v2")
    public void createPersonV2(@Valid @Validated({Version1Checks.class, Version2Checks.class}) Person person) {
    }
}

Testing

It is critical to test the constraints so that you can ensure the assumptions about the data hold and see what kinds of error messages clients will receive for bad input. The recommended way for testing annotations is through Testing Resources, as Dropwizard does a bit of magic behind the scenes when a constraint violation occurs to set the response’s status code and ensure that the error messages are user friendly.

@Test
public void personNeedsAName() {
    // Tests what happens when a person with a null name is sent to
    // the endpoint.
    final Response post = resources.client()
            .target("/person/v1").request()
            .post(Entity.json(new Person(null)));

    // Clients will receive a 422 on bad request entity
    assertThat(post.getStatus()).isEqualTo(422);

    // Check to make sure that errors are correct and human readable
    ValidationErrorMessage msg = post.readEntity(ValidationErrorMessage.class);
    assertThat(msg.getErrors())
            .containsOnly("name may not be empty");
}

Extending

While Dropwizard provides good defaults for error messages, one size may not fit all and so there are a series of extension points. To register your own ExceptionMapper<JerseyViolationException> you’ll need to first set registerDefaultExceptionMappers to false in the configuration file or in code before registering your exception mapper with jersey. Then, optionally, register other default exception mappers:

• LoggingExceptionMapper<Throwable>
• JsonProcessingExceptionMapper
• EarlyEofExceptionMapper

If you need to validate entities outside of resource endpoints, the validator can be accessed in the Environment when the application is first ran.

Validator validator = environment.getValidator();
Set<ConstraintViolation> errors = validator.validate(/* instance of class */)

The method used to determine what status code to return based on violations is ConstraintViolations.determineStatus

The method used to determine the human friendly error message due to a constraint violation is ConstraintMessage.getMessage.