Валидация данных ресурса с Bean Validation

JAX-RS поддерживает Bean Validation для валидации классов ресурсов JAX-RS. Эта поддержка состоит из:

Добавление аннотаций ограничений к параметрам метода ресурса
Обеспечение валидности данных объекта, когда объект передаётся в качестве параметра

Здесь рассматриваются следующие темы:

Использование аннотаций ограничений на методах ресурсов
Валидация данных объекта
Коды обработки исключений и ответов

Использование аннотаций ограничений на методах ресурсов

Аннотации ограничений Bean Validation могут применяться к параметрам для ресурса. Сервер провалидирует параметры и либо передаст их, либо выбросит javax.validation.ValidationException.

@POST
@Path("/createUser")
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public void createUser(@NotNull @FormParam("username") String username,
                       @NotNull @FormParam("firstName") String firstName,
                       @NotNull @FormParam("lastName") String lastName,
                       @Email @FormParam("email") String email) {
    ...
}

В предыдущем примере предустановленное ограничение @NotNull применяется к полям формы username, firstName и lastName. Другое предустановленное ограничение @Email проверяет на корректность форматирование адреса электронной почты, указанного в поле формы email.

Ограничения также могут применяться к полям в классе ресурсов.

@Path("/createUser")
public class CreateUserResource {
  @NotNull
  @FormParam("username")
  private String username;

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

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

  @Email
  @FormParam("email")
  private String email;

  ...
}

В этом примере те же ограничения, которые были применены к параметрам метода в предыдущем примере, применяются к полям класса. Поведение одинаково в обоих примерах.

Ограничения могут также применяться к свойствам JavaBeans класса ресурсов путём добавления аннотаций ограничений к get-методу.

@Path("/createuser")
public class CreateUserResource {
  private String username;

  @FormParam("username")
  public void setUsername(String username) {
    this.username = username;
  }

  @NotNull
  public String getUsername() {
    return username;
  }
  ...
}

Ограничения могут также применяться на уровне класса ресурсов. В следующем примере @PhoneRequired — это пользовательское ограничение, которое гарантирует, что пользователь вводит хотя бы один номер телефона. То есть homePhone или mobilePhone может быть null, но не оба сразу.

@Path("/createUser")
@PhoneRequired
public class CreateUserResource {
  @FormParam("homePhone")
  private Phone homePhone;

  @FormParam("mobilePhone")
  private Phone mobilePhone;
  ...
}

Валидация данных объекта

Классы, которые содержат аннотации ограничений валидации, могут использоваться в параметрах метода в классе ресурса. Чтобы провалидировать эти классы сущностей, используйте аннотацию @Valid для параметра метода. Например, следующий пользовательский класс содержит как стандартные, так и пользовательские ограничения валидации.

@PhoneRequired
public class User {
  @NotNull
  private String username;

  private Phone homePhone;

  private Phone mobilePhone;
  ...
}

Этот класс сущности используется в качестве параметра метода ресурса.

@Path("/createUser")
public class CreateUserResource {
  ...
  @POST
  @Consumers(MediaType.APPLICATION_XML)
  public void createUser(@Valid User user) {
    ...
  }
  ...
}

Аннотация @Valid обеспечивает валидацию класса сущности во время выполнения. Дополнительные пользовательские ограничения также могут инициировать валидацию сущности.

@Path("/createUser")
public class CreateUserResource {
  ...
  @POST
  @Consumers(MediaType.APPLICATION_XML)
  public void createUser(@ActiveUser User user) {
    ...
  }
  ...
}

В предыдущем примере пользовательское ограничение @ActiveUser применяется к классу User в дополнение к ограничениям @PhoneRequired и @NotNull, определённым в классе сущности.

Если метод ресурса возвращает класс сущности, валидация может быть запущена путём применения @Valid или любой другой определённой пользователем аннотации ограничения к методу ресурса.

@Path("/getUser")
public class GetUserResource {
  ...
  @GET
  @Path("{username}")
  @Produces(MediaType.APPLICATION_XML)
  @ActiveUser
  @Valid
  public User getUser(@PathParam("username") String username) {
    // извлечение пользователя
    return user;
  }
  ...
}

Как и в предыдущем примере, ограничение @ActiveUser применяется к возвращённому классу сущностей, а также к ограничениям @PhoneRequired и @NotNull, определённым в классе сущности.

Коды обработки исключений и ответов

Если генерируется javax.validation.ValidationException или любой дочерний класс ValidationException, кроме ConstraintValidationException, среда выполнения JAX-RS ответит на запрос клиента с помощью код состояния HTTP 500 (Internal Server Error).

Если генерируется ConstraintValidationException, среда выполнения JAX-RS ответит клиенту одним из следующих кодов состояния HTTP:

500 (Internal Server Error), если возникла исключительная ситуация при валидации возвращённого методом типа
400 (Bad Request) во всех остальных случаях