Обзор клиентского API

Клиентский API JAX-RS предоставляет высокоуровневый API для доступа к любым ресурсам REST, а не только к сервисам JAX-RS. Клиентский API определён в пакете javax.ws.rs.client.

Здесь рассматриваются следующие темы:

Создание базового клиентского запроса с использованием клиентского API
Получение объекта клиента
Установка цели (target) клиента
Установка параметров пути в цели
Вызов запроса

Создание базового клиентского запроса с использованием клиентского API

Следующие шаги необходимы для доступа к ресурсу REST с помощью клиентского API.

Получите объект интерфейса javax.ws.rs.client.Client.
Настройте объект Client, указав цель (target).
Создайте запрос для цели.
Вызовите запрос.

Клиентский API спроектирован так, чтобы свободно, с объединёнными в цепочку вызовами методов настройки и отправки запроса к ресурсу REST уместиться всего в несколько строк кода.

Client client = ClientBuilder.newClient();
String name = client.target("http://example.com/webapi/hello")
        .request(MediaType.TEXT_PLAIN)
        .get(String.class);

В этом примере объект клиента сначала создаётся путём вызова метода javax.ws.rs.client.ClientBuilder.newClient. Затем запрос конфигурируется и вызывается цепочкой вызовов методов одной строкой кода. Метод Client.target устанавливает цель с указанным URI. Метод javax.ws.rs.client.WebTarget.request устанавливает тип MIME для возвращаемого объекта. Метод javax.ws.rs.client.Invocation.Builder.get вызывает сервис, используя HTTP-запрос GET, устанавливая тип возвращаемого объекта в String.

Получение объекта клиента

Интерфейс Client определяет действия и инфраструктуру, необходимые клиенту REST для использования RESTful веб-сервиса. Объекты Client получены путём вызова метода ClientBuilder.newClient.

Client client = ClientBuilder.newClient();

Используйте метод close, чтобы закрыть объекты Client после выполнения всех вызовов для цели:

Client client = ClientBuilder.newClient();
...
client.close();

Объекты Client являются тяжеловесными объектами. По соображениям производительности ограничьте количество объектов Client в приложении, так как инициализация и уничтожение этих объектов может оказаться дорогостоящим для среды выполнения.

Установка цели (target) клиента

Цель клиента — ресурс REST для определённого URI — представлена объектом интерфейса javax.ws.rs.client.WebTarget. Объект WebTarget получается вызовом метода Client.target с передачей URI целевого ресурса REST.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi");

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

Client client = ClientBuilder.newClient();
WebTarget base = client.target("http://example.com/webapi");
// WebTarget at http://example.com/webapi/read
WebTarget read = base.path("read");
// WebTarget at http://example.com/webapi/write
WebTarget write = base.path("write");

Метод WebTarget.path создаёт новый объект WebTarget, добавляя URI текущей цели с указанным путём.

Установка параметров пути в цели

Параметры пути в клиентских запросах могут быть указаны в качестве параметров шаблона URI, аналогично параметрам шаблона, используемым при определении URI ресурса в сервисе JAX-RS. Параметры шаблона указываются путём помещения переменной шаблона в фигурные скобки ({}). Вызовите метод resolveTemplate для замены {username}, а затем вызовите метод queryParam, чтобы добавить другую переменную для передачи.

WebTarget myResource = client.target("http://example.com/webapi/read")
        .path("{userName}")
        .resolveTemplate("userName", "janedoe")
        .queryParam("chapter", "1");// http://example.com/webapi/read/janedoe?chapter=1
Response response = myResource.request(...)
        .get();

Вызов запроса

После применения всех параметров конфигурации к объекту цели вызовите один из методов WebTarget.request, чтобы начать формирование запроса. Обычно это достигается передачей в WebTarget.request принятого типа MIME ответа на запрос либо в виде строки типа MIME, либо с использованием одной из констант в javax.ws.rs.core.MediaType. Метод WebTarget.request возвращает объект javax.ws.rs.client.Invocation.Builder — вспомогательный объект, который предоставляет методы для подготовки клиентского запроса.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
Invocation.Builder builder = myResource.request(MediaType.TEXT_PLAIN);

Использование константы MediaType эквивалентно использованию строки, определяющей тип MIME.

Invocation.Builder builder = myResource.request("text/plain");

После установки типа MIME вызовите запрос, вызвав один из методов объекта Invocation.Builder, который соответствует типу HTTP-запроса, ожидаемого целевым ресурсом REST. Это методы:

get()
post()
delete()
put()
head()
options()

Например, если целевой ресурс REST предназначен для HTTP GET-запроса, вызовите метод Invocation.Builder.get. Тип возвращаемого значения должен соответствовать сущности, возвращаемой целевым ресурсом REST.

Client client = ClientBuilder.newClient();
WebTarget myResource = client.target("http://example.com/webapi/read");
String response = myResource.request(MediaType.TEXT_PLAIN)
        .get(String.class);

Если целевой ресурс REST ожидает HTTP-запрос POST, вызовите метод Invocation.Builder.post.

Client client = ClientBuilder.newClient();
StoreOrder order = new StoreOrder(...);
WebTarget myResource = client.target("http://example.com/webapi/write");
TrackingNumber trackingNumber = myResource.request(MediaType.APPLICATION_XML)
                                   .post(Entity.xml(order), TrackingNumber.class);

В предыдущем примере возвращаемый тип является пользовательским классом и извлекается путём установки типа в методе Invocation.Builder.post(Entity<‬?> entity, Class<T> responseType) ,

Если возвращаемый тип является коллекцией, используйте javax.ws.rs.core.GenericType<T> в качестве параметра типа ответа, где T — тип коллекции:

List<StoreOrder> orders = client.target("http://example.com/webapi/read")
        .path("allOrders")
        .request(MediaType.APPLICATION_XML)
        .get(new GenericType<List<StoreOrder>>() {});

Этот пример показывает, как вызывается цепочка методов клиентского API, чтобы упростить настройку и вызов запросов.