Аннотации для полей и свойств компонентов классов ресурсов

Аннотации JAX-RS для классов ресурсов позволяют извлекать определённые части и значения из URI или заголовка запроса.

JAX-RS предоставляет аннотации, перечисленные в таблице 32-1.

Таблица 32-1 Дополнительных аннотации JAX-RS

Аннотация

Описание

@Context

Инъецирует информацию в поле класса, свойство компонента или параметр метода

@CookieParam

Извлекает информацию из файлов cookie, объявленных в заголовке запроса cookie.

@FormParam

Извлекает информацию из запроса с типом MIME application/x-www-form-urlencoded

@HeaderParam

Извлекает значение заголовка

@MatrixParam

Извлекает значение параметра матрицы URI

@PathParam

Извлекает значение параметра шаблона URI

@QueryParam

Извлекает значение параметра запроса URI

Извлечение параметров пути

Шаблоны пути URI — это URI с переменными, встроенными в синтаксис URI. Аннотация @PathParam позволяет использовать переменные фрагменты пути URI при вызове метода.

В следующем фрагменте кода показано, как извлечь фамилию сотрудника, если указан адрес его электронной почты:

@Path("/employees/{firstname}.{lastname}@{domain}.com")
public class EmpResource {

    @GET
    @Produces("text/xml")
    public String getEmployeelastname(@PathParam("lastname") String lastName) {
      ...
    }
}

В этом примере аннотация @Path определяет переменные URI (или параметры пути) {firstname}, {lastname} и {domain}. @PathParam в параметре метода метода запроса извлекает фамилию из адреса электронной почты.

Если ваш HTTP-запрос GET /employees/john.doe@example.com, значение «doe» вставляется в {lastname}.

Вы можете указать несколько параметров пути в одном URI.

Вы можете объявить регулярное выражение с помощью переменной URI. Например, если требуется, чтобы фамилия состояла только из строчных и прописных символов, вы можете объявить следующее регулярное выражение:

@Path("/employees/{firstname}.{lastname[a-zA-Z]*}@{domain}.com")

Если фамилия не соответствует регулярному выражению, возвращается ответ 404.

Извлечение параметров запроса

Используйте аннотацию @QueryParam для извлечения параметров запроса из URI запроса.

Например, для запроса всех сотрудников, которые присоединились в течение определённого диапазона лет, используйте сигнатуру метода, подобную следующей:

@Path("/employees/")
@GET
public Response getEmployees(
        @DefaultValue("2014") @QueryParam("minyear") int minyear,
        @DefaultValue("2017") @QueryParam("maxyear") int maxyear)
    {...}

Этот фрагмент кода определяет два параметра запроса: minyear и maxyear. Следующий HTTP-запрос будет запрашивать всех сотрудников, нанятых в период с 2014 по 2017 год:

GET /employees?maxyear=2017&minyear=2014

Аннотация @DefaultValue определяет значение по умолчанию, которое следует использовать, если для параметров запроса не указаны значения. По умолчанию JAX-RS назначает null для значений Object и ноль для примитивных типов данных. Вы можете использовать аннотацию @DefaultValue, чтобы явно указать значений по умолчанию для параметров.

Извлечение данных формы

Используйте аннотацию @FormParam для извлечения параметров формы из форм HTML. Например, следующая форма принимает имя, адрес сотрудника и имя его руководителя:

<FORM action="http://example.com/employees/" method="post">
  <p>
    <fieldset>
      Employee name: <INPUT type="text" name="empname" tabindex="1">
      Employee address: <INPUT type="text" name="empaddress" tabindex="2">
      Manager name: <INPUT type="text" name="managername" tabindex="3">
    </fieldset>
  </p>
</FORM>

Используйте следующий фрагмент кода, чтобы извлечь имя руководителя из этой HTML-формы:

@POST
@Consumes("application/x-www-form-urlencoded")
public void post(@FormParam("managername") String managername) {
    // Сохранение значения
    ...
}

Чтобы получить сопоставление имён параметров формы со значениями, используйте фрагмент кода:

@POST
@Consumes("application/x-www-form-urlencoded")
public void post(MultivaluedMap<String, String> formParams) {
    // Сохранение сообщения
}

Извлечение Java-типа запроса или ответа

Аннотация javax.ws.rs.core.Context извлекает типы Java, связанные с запросом или ответом.

Интерфейс javax.ws.rs.core.UriInfo предоставляет информацию о компонентах URI запроса. В следующем фрагменте кода показано, как получить отображение имён параметров запроса и пути их значениям:

@GET
public String getParams(@Context UriInfo ui) {
    MultivaluedMap<String, String> queryParams = ui.getQueryParameters();
    MultivaluedMap<String, String> pathParams = ui.getPathParameters();
}

Интерфейс javax.ws.rs.core.HttpHeaders предоставляет информацию о заголовках запросов и cookie. В следующем фрагменте кода показано, как получить сопоставление имён параметров заголовка и cookie со значениями:

@GET
public String getHeaders(@Context HttpHeaders hh) {
    MultivaluedMap<String, String> headerParams = hh.getRequestHeaders();
    MultivaluedMap<String, Cookie> pathParams = hh.getCookies();
}