Изучаем Java EE 7 - [242]

В листинге 15.7 продемонстрировано, как аннотация @PathParam используется для извлечения значения параметра шаблона URI. Параметр имеет имя и представляется в виде переменной, заключенной в фигурные скобки, либо переменной, за которой следует регулярное выражение. Метод searchCustomers принимает любой строковый параметр, тогда как в параметрах метода getCustomerByLogin допускаются только строчные и прописные буквы алфавита ([a-zA-Z]*), а в параметрах метода getCustomerById — только цифры (\\d+).

Листинг 15.7. Извлечение параметров пути и регулярных выражений

@Path("/customer")
@Produces(MediaType.APPLICATION_JSON)
public class CustomerRestService {

··@Path("search/{text}")
··public Customers searchCustomers(@PathParam("text") String textToSearch) {
····// URI: /customer/search/smith
··}
··@GET
··@Path("{login: [a-zA-Z]*}")
··public Customer getCustomerByLogin(@PathParam("login") String login) {
····// URI: /customer/foobarsmith
··}

··@GET
··@Path("{customerId: \\d+}")
··public Customer getCustomerById(@PathParam("customerId") Long id) {
····// URI: /customer/12345
··}
}

Аннотация @QueryParam извлекает значение параметра запроса, содержащегося в URI. Параметры запроса — это пары «ключ/значение», разделительным символом между которыми служит &. Например: http://www.myserver.com/customer?zip=75012&city=Paris. Аннотация @MatrixParam действует подобно @QueryParam, однако извлекает значение параметра матрицы URI (в качестве разделительного знака используется;). В листинге 15.8 показано, как извлечь из URI оба параметра — содержащий запрос и содержащий матрицу.

Листинг 15.8. Извлечение параметров со значением запроса и матрицы

@Path("/customer")
@Produces(MediaType.APPLICATION_JSON)
public class CustomerRestService {
··@GET

··public Customers getCustomersByZipCode(@QueryParam("zip") Long zip, 

·········································@QueryParam("city") String city) {
····// URI: /customer?zip=75012&city=Paris
··}

··@GET
··@Path("search")

··public Customers getCustomersByName(@MatrixParam("firstname") String 

·······················firstname, @MatrixParam("surname") String surname) {
····// URI: /customer/search;firstname=Antonio;surname=Goncalves
··}
}

Две другие аннотации относятся к внутренней части HTTP, такая информация не отражается непосредственно в URI. Речь идет о cookie и HTTP-заголовках. Аннотация @CookieParam извлекает значение cookie, а аннотация @HeaderParam — значение поля заголовка. В листинге 15.9 мы извлекаем сеансовый ID из cookie и информацию о пользовательском агенте из HTTP-заголовка.

Листинг 15.9. Извлечение значения из cookie и HTTP-заголовка

@Path("/customer")
@Produces(MediaType.TEXT_PLAIN)
public class CustomerRestService {

··@GET
··public String extractSessionID(@CookieParam("sessionID") String sessionID) {
····//…
··}
··@GET
··public String extractUserAgent(@HeaderParam("User-Agent") String userAgent) {
····//…
··}
}

Аннотация @FormParam указывает, что значение параметра должно быть извлечено из формы, содержащейся в теле объекта в запросе. Поддержка аннотации @FormParam у полей и свойств не требуется.

Имея все эти аннотации, можно добавить и аннотацию @DefaultValue для определения значения, которое будет действовать по умолчанию для ожидаемого параметра. Такое значение задействуется в соответствующем параметре, если подобное значение отсутствует в запросе. В листинге 15.10 устанавливаются значения, которые будут действовать по умолчанию для параметров запроса и матрицы. Например, если при работе с методом getCustomersByAge в запросе не окажется параметра age, то по умолчанию будет применено значение 50.

Листинг 15.10. Определение значений, действующих по умолчанию

@Path("/customer")
public class CustomerRestService {
··@GET

··public Customers getCustomersByAge(@DefaultValue("50") @QueryParam("age") 

·····································int age) {
····//…
··}

··@GET
··public Customers getCustomersByCity(@DefaultValue("Paris")

······································@MatrixParam("city") String city) {
····//…
··}
}

Использование и создание типов содержимого

При работе с REST один и тот же ресурс может обладать несколькими представлениями. Так, книга может иметь вид веб-страницы, 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"