Изучите параметры запроса Джерси

1. Введение

Jersey — это популярная платформа Java для создания веб-сервисов RESTful.

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

2. Настройка проекта

Используя архетипы Maven, мы сможем создать рабочий проект для нашей статьи:

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2
  -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false
  -DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example
  -DarchetypeVersion=2.28

Сгенерированный проект Jersey будет работать поверх контейнера Grizzly.

Теперь по умолчанию конечной точкой нашего приложения будет http://localhost:8080/myapp .

Давайте добавим ресурс элементов , который мы будем использовать для наших экспериментов:

@Path("items")
public class ItemsController {
    // our endpoints are defined here
}

Обратите внимание, кстати, что Jersey отлично работает и с контроллерами Spring .

3. Аннотированные типы параметров

Итак, прежде чем мы на самом деле прочитаем какие-либо параметры запроса, давайте проясним несколько правил. Допустимые типы параметров:

• Примитивные типы, такие как float и char

• Типы, у которых есть конструктор с одним строковым аргументом

• Типы, имеющие статический метод fromString или valueOf ; для них один аргумент String является обязательным

• Коллекции — такие как List , Set и SortedSet — типов, описанных выше.

Также мы можем зарегистрировать реализацию расширения ParamConverterProvider JAX-RS SPI. Тип возвращаемого значения должен быть экземпляром ParamConverter , допускающим преобразование из String в тип.

4. Файлы cookie

Мы можем разрешать значения cookie в наших методах Джерси, используя аннотацию @CookieParam :

@GET
public String jsessionid(@CookieParam("JSESSIONId") String jsessionId) {
    return "Cookie parameter value is [" + jsessionId+ "]";
}

Если мы запустим наш контейнер, мы можем cURL этой конечной точки увидеть ответ:

> curl --cookie "JSESSIONID=5BDA743FEBD1BAEFED12ECE124330923" http://localhost:8080/myapp/items
Cookie parameter value is [5BDA743FEBD1BAEFED12ECE124330923]

5. Заголовки

Или мы можем разрешить заголовки HTTP с помощью аннотации @HeaderParam :

@GET
public String contentType(@HeaderParam("Content-Type") String contentType) {
    return "Header parameter value is [" + contentType+ "]";
}

Проверим еще раз:

> curl --header "Content-Type: text/html" http://localhost:8080/myapp/items
Header parameter value is [text/html]

6. Параметры пути

Особенно с API RESTful обычно включают информацию в путь.

Мы можем извлечь элементы пути с помощью @PathParam :

@GET
@Path("/{id}")
public String itemId(@PathParam("id") Integer id) {
    return "Path parameter value is [" + id + "]";
}

Давайте отправим еще одну команду curl со значением 3 :

> curl http://localhost:8080/myapp/items/3
Path parameter value is [3]

7. Параметры запроса

Мы обычно используем параметры запроса в RESTful API для дополнительной информации.

Чтобы прочитать такие значения, мы можем использовать аннотацию @QueryParam :

@GET
public String itemName(@QueryParam("name") String name) {
    return "Query parameter value is [" + name + "]";
}

Итак, теперь мы можем протестировать с помощью curl , как и раньше:

> curl http://localhost:8080/myapp/items?name=Toaster
Query parameter value if [Toaster]

8. Параметры формы

Для чтения параметров из отправки формы мы будем использовать аннотацию @FormParam :

@POST
public String itemShipment(@FormParam("deliveryAddress") String deliveryAddress, 
  @FormParam("quantity") Long quantity) {
    return "Form parameters are [deliveryAddress=" + deliveryAddress+ ", quantity=" + quantity + "]";
}

Нам также необходимо установить правильный Content-Type , чтобы имитировать действие отправки формы. Зададим параметры формы с помощью флага -d :

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  -d 'deliveryAddress=Washington nr 4&quantity=5' \
  http://localhost:8080/myapp/items
Form parameters are [deliveryAddress=Washington nr 4, quantity=5]

9. Параметры матрицы

Параметр матрицы является более гибким параметром запроса, поскольку его можно добавить в любом месте URL-адреса.

Например, в http://localhost:8080/myapp;name=value/items параметром матрицы является имя .

Чтобы прочитать такие значения, мы можем использовать доступную аннотацию @MatrixParam :

@GET
public String itemColors(@MatrixParam("colors") List<String> colors) {
    return "Matrix parameter values are " + Arrays.toString(colors.toArray());
}

И теперь мы снова проверим нашу конечную точку:

> curl http://localhost:8080/myapp/items;colors=blue,red
Matrix parameter values are [blue,red]

10. Параметры компонента

Наконец, мы проверим, как комбинировать параметры запроса, используя параметры bean-компонента. Чтобы уточнить, параметр компонента на самом деле является объектом, который объединяет различные типы параметров запроса.

Здесь мы будем использовать параметр заголовка, путь и форму:

public class ItemOrder {
    @HeaderParam("coupon")
    private String coupon;

    @PathParam("itemId")
    private Long itemId;

    @FormParam("total")
    private Double total;

    //getter and setter

    @Override
    public String toString() {
        return "ItemOrder {coupon=" + coupon + ", itemId=" + itemId + ", total=" + total + '}';
    }
}

Также для получения такой комбинации параметров воспользуемся аннотацией @BeanParam :

@POST
@Path("/{itemId}")
public String itemOrder(@BeanParam ItemOrder itemOrder) {
    return itemOrder.toString();
}

В команде curl мы добавили эти три типа параметров, и в итоге мы получим один объект ItemOrder :

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  --header 'coupon:FREE10p' \
  -d total=70 \
  http://localhost:8080/myapp/items/28711
ItemOrder {coupon=FREE10p, itemId=28711, total=70}

11. Заключение

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

Реализация всех этих фрагментов доступна на Github .