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
Сгенерированный проект Джерси будет работать поверх контейнера Grizzly.
Теперь, по умолчанию, конечной точкой для нашего приложения будет http://localhost:8080/myapp .
Давайте добавим ресурс items , который мы будем использовать для наших экспериментов:
@Path("items") public class ItemsController { // our endpoints are defined here }
Кстати, обратите внимание, что Джерси также отлично работает с пружинными контроллерами .
3. Типы аннотированных параметров
Итак, прежде чем мы действительно прочитаем какие-либо параметры запроса, давайте проясним несколько правил. Допустимыми типами параметров являются:
- Примитивные типы, такие как float и char
- Типы, имеющие конструктор с одним аргументом String
- Типы, которые имеют либо Из строки или Ценность статический метод; для тех, кто одиночный Строка аргумент является обязательным
- Коллекции – такие как List , Set и SortedSet – типов , описанных выше
Кроме того, мы можем зарегистрировать реализацию ParamConverterProvider JAX-RS extension SPI. Возвращаемым типом должен быть экземпляр ParamConverter , способный к преобразованию из String в тип.
4. Файлы cookie
Мы можем разрешить значения файлов cookie в наших методах Джерси, используя @CookieParam аннотацию:
@GET public String jsessionid(@CookieParam("JSESSIONId") String jsessionId) { return "Cookie parameter value is [" + jsessionId+ "]"; }
> 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. Параметры запроса
Мы обычно используем параметры запроса в API RESTful для получения дополнительной информации.
Для чтения таких значений мы можем использовать аннотацию @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. Параметры формы
@POST public String itemShipment(@FormParam("deliveryAddress") String deliveryAddress, @FormParam("quantity") Long quantity) { return "Form parameters are [deliveryAddress=" + deliveryAddress+ ", quantity=" + quantity + "]"; }
Нам также необходимо установить надлежащий Тип контента чтобы имитировать действие отправки формы. Давайте установим параметры формы с помощью -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;имя=значение/элементы , параметр матрицы равен имя .
Чтобы прочитать такие значения, мы можем использовать доступную @MatrixParam аннотацию:
@GET public String itemColors(@MatrixParam("colors") Listcolors) { 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. Чтобы уточнить, параметр 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 мы добавили эти три типа параметров, и в итоге получим один Заказ товара объект:
> 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 .