Изучаем Java EE 7 - [244]
| Метод | Описание |
|---|---|
| accepted() | Создает новый объект ResponseBuilder с состоянием 202 — Принято |
| created() | Создает новый объект ResponseBuilder для созданного ресурса (с его URI) |
| noContent() | Создает новый объект ResponseBuilder для пустого ответа |
| notModified() | Создает новый объект ResponseBuilder с состоянием 304 — Не изменялось |
| Метод | Описание |
| ok() | Создает новый объект ResponseBuilder с состоянием 200 — Хорошо |
| serverError() | Создает новый объект ResponseBuilder с состоянием 500 — Серверная ошибка |
| status() | Создает новый объект ResponseBuilder с предоставленным состоянием |
| temporaryRedirect() | Создает новый объект ResponseBuilder с временным перенаправлением |
| getCookies() | Получает cookie из сообщения ответа |
| getHeaders() | Получает заголовки из сообщения ответа |
| getLinks() | Получает ссылки, прикрепленные к сообщению в заголовке |
| getStatus() | Получает код состояния, ассоциированный с ответом |
| readEntity() | Получает объект сообщения как экземпляр указанного типа Java. При этом используется интерфейс MessageBodyReader, поддерживающий отображение сообщения на запрошенный тип |
Response и ResponseBuilder следуют шаблону проектирования «текучий интерфейс». Это означает, что вы вполне можете написать ответ, воспользовавшись конкатенацией методов. В таком случае код также становится более удобочитаемым. Вот примеры кода, который мы можем написать с помощью этого API:
>Response.ok(). build();
>Response.ok(). cookie(new NewCookie("SessionID", "5G79GDIFY09")). build();
>Response.ok("Plain Text"). expires(new Date()). build();
>Response.ok(new Customer ("Джон", "Смит"), MediaType.APPLICATION_JSON).
>build();
>Response.noContent(). build();
>Response.accepted(new Customer("Джон", "Смит", "[email protected]",
>"12 34565")). build();
>Response.notModified(). header("Браузер", "Mozilla"). build();
Сопоставление HTTP-методов
Итак, мы рассмотрели, как протокол HTTP работает со своими запросами, ответами и операциями (GET, POST, PUT и т. д.) JAX-RS определяет эти распространенные HTTP-методы с помощью аннотаций @GET, @POST, @PUT, @DELETE, @HEAD и @OPTIONS. В качестве методов ресурсов могут предоставляться только общедоступные методы. В листинге 15.13 показана пользовательская веб-служба в стиле REST, предоставляющая методы из разряда CRUD: @GET для получения ресурсов, @POST для создания нового ресурса, @PUT для обновления имеющегося ресурса и @DELETE для удаления ресурса.
>@Path("/customer")
>@Produces(MediaType.APPLICATION_XML)
>@Consumes(MediaType.APPLICATION_XML)
>public class CustomerRestService {
>··@GET
>··public Response getCustomers() {
>····//..
>····return Response.ok(customers). build();
>··}
>··@GET
>··@Path("{customerId}")
>··public Response getCustomer(@PathParam("customerId") String customerId) {
>····//..
>····return Response.ok(customer). build();
>··}
>··@POST
>··public Response createCustomer(Customer customer) {
>····//..
>····return Response.created(createdCustomerURI). build();
>··}
>··@PUT
>··public Response updateCustomer(Customer customer) {
>····//..
>····return Response.ok(customer). build();
>··}
>··@DELETE
>··@Path("{customerId}")
>··public Response deleteCustomer(@PathParam("customerId") String customerId) {
>····//..
>····return Response.noContent(). build();
>··}
>}
В спецификации HTTP определяется, какие коды состояния HTTP должны выдаваться при успешном ответе. Вы можете быть уверены, что JAX-RS будет возвращать те же самые стандартные коды ответа.
• Методы GET получают (в виде объекта) любую информацию, на которую указывает запрошенный URI. GET должен возвращать код 200 — Хорошо.
• Метод PUT ссылается на уже существующий ресурс, который необходимо обновить. Если обновляется существующий ресурс, то должен быть возвращен один из следующих кодов состояния: 200 — Хорошо или 204 — Нет содержимого. Такие ответы означают успешное завершение запроса.
• Метод POST используется для создания нового ресурса, идентифицируемого URI запроса. В ответ должен возвращаться код 201 — Создано с URI нового ресурса или код 204 — Нет содержимого, если метод не создал ресурса, который можно было бы идентифицировать по URI.
• Метод DELETE требует, чтобы сервер удалил ресурс, на который указывает содержащийся в запросе URI. При успешном ответе должен возвращаться код 200 — Хорошо (если в ответе содержится объект), 202 — Принято (если действие пока не запущено) или 204 — Нет содержимого, если действие было запущено, но в ответе отсутствует объект.
Построение URI. Гиперссылки — центральная составляющая REST-приложений. Чтобы развиваться в процессе движения приложения между состояниями, веб-службы в стиле REST должны гибко управлять переходами и так же гибко строить URI. В JAX-RS предоставляется объект javax.ws.rs.core.UriBuilder, призванный заменить java.net.URI и упростить безопасное построение URI. Класс UriBuilder обладает набором методов, с помощью которых удобно строить новые URI с нуля или на основе уже существующих URI. В листинге 15.14 показаны примеры использования UriBuilder для создания любого URI с параметрами, указывающими путь, запрос или матрицу.
