Энтони Гонсалвес - Изучаем Java EE 7

представлениями. Так, книга может иметь вид веб-страницы, PDF-документа или изображения, на котором показана лишь обложка. В JAX-RS указывается несколько типов Java, способных представлять ресурсы, например String, InputStream и компоненты JAXB. Аннотации @javax.ws.rs.Consumes и @javax.ws.rs.Produces могут применяться с таким ресурсом, который способен иметь несколько представлений. Здесь определяются медиатипы представления, которыми могут обмениваться клиент и сервер. В JAX-RS есть класс javax.ws.rs.core.MediaType, действующий в качестве абстракции для MIME-типа. Он содержит несколько методов и определяет константы, перечисленные в табл. 15.5.

Таблица 15.5. MIME-типы, определяемые в классе MediaType

Имя константы MIME-тип APPLICATION_ATOM_XML "application/atom+xml" APPLICATION_FORM_URLENCODED "application/x-www-form-urlencoded" APPLICATION_JSON "application/json" APPLICATION_OCTET_STREAM "application/octet-stream" APPLICATION_SVG_XML "application/svg+xml" APPLICATION_XHTML_XML "application/xhtml+xml" APPLICATION_XML "application/xml" MULTIPART_FORM_DATA "multipart/form-data" TEXT_HTML "text/html" TEXT_PLAIN "text/plain" TEXT_XML "text/xml" WILDCARD "*/*"
Если в методе используются аннотации @Consumes и @Produces, то они переопределяют любые аннотации, которыми может сопровождаться класс ресурса для аргумента метода или возвращаемого типа. При отсутствии любой из двух этих аннотаций предполагается поддержка любого медиатипа (*/*). По умолчанию CustomerRestService порождает обычные текстовые представления, которые переопределяются в некоторых методах (листинг 15.11). Обратите внимание: getAsJsonAndXML порождает массив представлений (XML или JSON).

Листинг 15.11. Ресурс Customer с несколькими представлениями

@Path("/customer")

@Produces(MediaType.TEXT_PLAIN)

public class CustomerRestService {

··@GET

··public Response getAsPlainText() {

····//…

··}

··@GET

··@Produces(MediaType.TEXT_HTML)

··public Response getAsHtml() {

····//…

··}

··@GET

··@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})

··public Response getAsJsonAndXML() {

····//…

··}

··@PUT

··@Consumes(MediaType.TEXT_PLAIN)

··public void putName(String customer) {

····//…

··}

}

Если веб-служба REST в состоянии произвести более одного медиатипа, то целевой метод будет соответствовать наиболее приемлемому медиатипу согласно информации, указанной клиентом в заголовке Accept HTTP-запроса. Например, если заголовок Accept таков:

Accept: text/plain

а URI при этом — /customer, то будет вызван метод getAsPlainText(). Но клиент мог бы использовать и такой HTTP-заголовок:

Accept: text/plain; q=0.8, text/html

Он объявляет, что клиент может принимать медиатипы text/plain и text/html, но предпочитает второй. Для указания выбора используется коэффициент качества (он же — вес предпочтения), равный 0,8 («Я предпочитаю text/html, но пришлите мне text/plain, если это наилучший доступный вариант после 80 %-ного снижения качества»). При включении такого заголовка и указании на URI /customer будет вызван метод getAsHtml().

Возвращаемые типы

До сих пор мы в основном говорили о том, как вызывать метод (с помощью параметров, медиатипа, HTTP-операций…), а возвращаемый тип нас не интересовал. Что же может возвращать веб-служба в стиле REST? Как и любой класс Java, метод может возвратить любой стандартный тип Java, компонент JAXB и вообще любой объект, обладающий текстовым представлением, которое можно передать по протоколу HTTP. В данном случае среда времени исполнения определяет MIME-тип возвращаемого объекта и вызывает соответствующий поставщик объектов (Entity Provider, см. ниже) для получения нужного представления. Среда времени исполнения также определяет подходящий код состояния, который HTTP должен вернуть потребителю (например, 204 — Нет содержимого, если возвращаемый тип метода ресурса равен void или null; либо 200 — Хорошо, если возвращено ненулевое значение). Но иногда требуется более тщательный контроль над возвращаемой информацией: разумеется, вас интересует тело ответа, называемое в терминологии HTTP объектом, но также могут быть важны и код ответа, и/или заголовки и cookie ответа. В таких случаях вы возвращаете объект Reponse. Целесообразно возвращать javax.ws.rs.core.Response, поскольку так гарантируется тип возвращаемого содержимого. В листинге 15.12 показаны различные возвращаемые типы.

Листинг 15.12. Служба Customer, возвращающая типы данных, компонент JAXB и ответ

@Path("/customer")

public class CustomerRestService {

··@GET

··public String getAsPlainText() {

····return --">