Класс HttpResponse.BodySubscribers

Вложенный интерфейс:
HttpResponse<T>
public static class HttpResponse.BodySubscribers
extends Object

Реализации BodySubscriber, которые реализуют различные полезные подписчики, такие как преобразование байтов тела ответа в строку или потоковое передача байтов в файл.

Ниже приведены примеры использования предопределенных подписчиков тела для преобразования потока данных тела ответа в обычные объекты Java высокого уровня: 

// Streams the response body to a File
   HttpResponse<byte[]> response = client
     .send(request, responseInfo -> BodySubscribers.ofByteArray());

   // Accumulates the response body and returns it as a byte[]
   HttpResponse<byte[]> response = client
     .send(request, responseInfo -> BodySubscribers.ofByteArray());

   // Discards the response body
   HttpResponse<Void> response = client
     .send(request, responseInfo -> BodySubscribers.discarding());

   // Accumulates the response body as a String then maps it to its bytes
   HttpResponse<byte[]> response = client
     .send(request, responseInfo ->
        BodySubscribers.mapping(BodySubscribers.ofString(UTF_8), String::getBytes));
С:
11

Методы

Модификатор и тип Метод Описание
static <T> HttpResponse.BodySubscriber<T> buffering​(HttpResponse.BodySubscriber<T> downstream, int bufferSize)

Возвращает BodySubscriber, который буферизует данные перед их передачей заданному подписчику.
static HttpResponse.BodySubscriber<Void> discarding()

Возвращает подписчика ответа, который игнорирует тело ответа.
static HttpResponse.BodySubscriber<Void> fromLineSubscriber​(Flow.Subscriber<? super String> subscriber)

Возвращает подписчика тела, который передает все тело ответа заданному Flow.Subscriber, по строкам.
static <S extends Flow.Subscriber<? super String>,​T>
HttpResponse.BodySubscriber<T>		 fromLineSubscriber​(S subscriber, Function<? super S,​? extends T> finisher, Charset charset, String lineSeparator)

Возвращает подписчика тела, который передает все тело ответа заданному Flow.Subscriber, по строкам.
static HttpResponse.BodySubscriber<Void> fromSubscriber​(Flow.Subscriber<? super List<ByteBuffer>> subscriber)

Возвращает подписчика тела, который передает все тело ответа заданному Flow.Subscriber.
static <S extends Flow.Subscriber<? super List<ByteBuffer>>,​T>
HttpResponse.BodySubscriber<T>		 fromSubscriber​(S subscriber, Function<? super S,​? extends T> finisher)

Возвращает подписчика тела, который передает все тело ответа заданному Flow.Subscriber.
static <T,​U>
HttpResponse.BodySubscriber<U>		 mapping​(HttpResponse.BodySubscriber<T> upstream, Function<? super T,​? extends U> mapper)

Возвращает BodySubscriber, значение тела ответа которого является результатом применения заданной функции к объекту тела заданного upstream BodySubscriber.
static HttpResponse.BodySubscriber<byte[]> ofByteArray()

Возвращает BodySubscriber, который хранит тело ответа в виде массива байтов.
static HttpResponse.BodySubscriber<Void> ofByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)

Возвращает BodySubscriber, который предоставляет поступающие данные тела заданному потребителю Optional<byte[]>.
static HttpResponse.BodySubscriber<Path> ofFile​(Path file)

Возвращает BodySubscriber, который хранит тело ответа в файле с заданным именем.
static HttpResponse.BodySubscriber<Path> ofFile​(Path file, OpenOption... openOptions)

Возвращает BodySubscriber, который хранит тело ответа в файле, открытом с заданными параметрами и именем.
static HttpResponse.BodySubscriber<InputStream> ofInputStream()

Возвращает BodySubscriber, который передает тело ответа как InputStream.
static HttpResponse.BodySubscriber<Stream<String>> ofLines​(Charset charset)

Возвращает BodySubscriber, который передает тело ответа как Stream, где каждая строка в потоке соответствует строке, как определено в BufferedReader.lines().
static HttpResponse.BodySubscriber<Flow.Publisher<List<ByteBuffer>>> ofPublisher()

Возвращает подписчика ответа, который публикует тело ответа через Publisher<List<ByteBuffer>>.
static HttpResponse.BodySubscriber<String> ofString​(Charset charset)

Возвращает подписчика тела, который хранит тело ответа как String, преобразованный с использованием заданного Charset.
static <U> HttpResponse.BodySubscriber<U> replacing​(U value)

Возвращает подписчика ответа, который игнорирует тело ответа.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Методы

fromSubscriber

public static HttpResponse.BodySubscriber<Void> fromSubscriber(Flow.Subscriber<? super List<ByteBuffer>> subscriber)

Возвращает подписчика на тело ответа, который пересылает всё тело ответа заданному Flow.Subscriber. Стадия завершения (completion stage) возвращённого подписчика на тело завершается после вызова одного из заданных подписчиков onComplete или onError.

Примечание API:
Этот метод может использоваться в качестве адаптера между BodySubscriber и Flow.Subscriber.
Параметры:
subscriber - подписчик
Возвращает:
подписчик на тело ответа

fromSubscriber

public static <S extends Flow.Subscriber<? super List<ByteBuffer>>,T> HttpResponse.BodySubscriber<T> fromSubscriber​(S subscriber,
                                                                                                                          Function<? super S,​? extends T> finisher)

Возвращает подписчика на тело ответа, который пересылает всё тело ответа заданному Flow.Subscriber. Стадия завершения (completion stage) возвращённого подписчика на тело завершается после вызова одного из заданных подписчиков onComplete или onError.

Указанная функция finisher применяется после вызова метода onComplete заданного подписчика. Функция finisher вызывается с указанным подписчиком и возвращает значение, которое устанавливается в качестве тела ответа.

Примечание API:
Этот метод может использоваться в качестве адаптера между BodySubscriber и Flow.Subscriber.
Параметры типа:
S - тип подписчика
T - тип тела ответа
Параметры:
subscriber - подписчик
finisher - функция, применяемая после завершения работы подписчика
Возвращает:
подписчик на тело ответа

fromLineSubscriber

public static HttpResponse.BodySubscriber<Void> fromLineSubscriber(Flow.Subscriber<? super String> subscriber)

Возвращает подписчика на тело ответа, который пересылает всё тело ответа заданному Flow.Subscriber, строка за строкой. Стадия завершения (completion stage) возвращённого подписчика на тело завершается после вызова одного из заданных подписчиков onComplete или onError. Байты декодируются с помощью кодировки UTF-8, а строки разделяются так же, как в BufferedReader.readLine().

Примечание API:
Этот метод может использоваться в качестве адаптера между BodySubscriber и Flow.Subscriber.
Примечание реализации:
Эквивалентно вызову 
fromLineSubscriber(subscriber, s -> null, StandardCharsets.UTF_8, null)
Параметры:
subscriber - подписчик
Возвращает:
подписчик на тело ответа

fromLineSubscriber

public static <S extends Flow.Subscriber<? super String>,T> HttpResponse.BodySubscriber<T> fromLineSubscriber​(S subscriber,
                                                                                                                    Function<? super S,​? extends T> finisher,
                                                                                                                    Charset charset,
                                                                                                                    String lineSeparator)

Возвращает подписчика на тело ответа, который пересылает всё тело ответа заданному Flow.Subscriber, строка за строкой. Стадия завершения (completion stage) возвращённого подписчика на тело завершается после вызова одного из заданных подписчиков onComplete или onError.

Указанная функция finisher применяется после вызова метода onComplete заданного подписчика. Функция finisher вызывается с указанным подписчиком и возвращает значение, которое устанавливается в качестве тела ответа.

Примечание API:
Этот метод может использоваться в качестве адаптера между BodySubscriber и Flow.Subscriber.
Параметры типа:
S - тип подписчика
T - тип тела ответа
Параметры:
subscriber - подписчик
finisher - функция, применяемая после завершения подписчика
charset - Charset для декодирования байтов
lineSeparator - необязательный разделитель строк: может быть null, в этом случае строки будут разделяться так же, как в BufferedReader.readLine().
Возвращает:
подписчик на тело ответа
Исключения:
IllegalArgumentException - если переданный lineSeparator пустая строка

ofString

public static HttpResponse.BodySubscriber<String> ofString(Charset charset)

Возвращает подписчика на тело ответа, который сохраняет тело ответа в виде String, преобразованного с помощью заданной Charset.

HttpResponse, использующий этого подписчика, доступен после чтения всего ответа.

Параметры:
charset - кодировка для преобразования строки
Возвращает:
подписчик на тело ответа

ofByteArray

public static HttpResponse.BodySubscriber<byte[]> ofByteArray()

Возвращает BodySubscriber, который сохраняет тело ответа в виде массива байтов.

HttpResponse, использующий этого подписчика, доступен после чтения всего ответа.

Возвращает:
подписчик на тело ответа

ofFile

public static HttpResponse.BodySubscriber<Path> ofFile(Path file,
                                                       OpenOption... openOptions)

Возвращает BodySubscriber, который сохраняет тело ответа в файле, открытом с заданными параметрами и именем. Файл будет открыт с заданными параметрами с помощью FileChannel.open непосредственно перед чтением тела. Любое исключение будет возвращено или выброшено из HttpClient::send или HttpClient::sendAsync соответственно.

HttpResponse, использующий этого подписчика, доступен после чтения всего ответа.

Проверки разрешений менеджера безопасности выполняются в этом фабричном методе, когда создаётся BodySubscriber. Следует позаботиться о том, чтобы BodyHandler не был доступен небезопасным кодам.

Параметры:
file - файл для сохранения тела
openOptions - список параметров для открытия файла
Возвращает:
подписчик на тело ответа
Исключения:
IllegalArgumentException - если задан недопустимый набор параметров открытия
SecurityException - если установлен менеджер безопасности, и он запрещает write access для файла

ofFile

public static HttpResponse.BodySubscriber<Path> ofFile(Path file)

Возвращает BodySubscriber, который сохраняет тело ответа в файле с указанным именем.

Эквивалентно: ofFile(file, CREATE, WRITE)

Проверки разрешений менеджера безопасности выполняются в этом фабричном методе, когда создаётся BodySubscriber. Следует позаботиться о том, чтобы BodyHandler не был доступен небезопасным кодам.

Параметры:
file - файл для сохранения тела
Возвращает:
подписчик на тело ответа
Исключения:
SecurityException - если установлен менеджер безопасности, и он запрещает write access для файла

ofByteArrayConsumer

public static HttpResponse.BodySubscriber<Void> ofByteArrayConsumer(Consumer<Optional<byte[]>> consumer)

Возвращает BodySubscriber, который предоставляет поступающие данные тела указанному Consumer массивов байтов. Каждый вызов Consumer.accept() будет содержать непустой Optional, за исключением последнего вызова после чтения всех данных тела, когда Optional будет пустым.

HttpResponse, использующий этого подписчика, доступен после чтения всего ответа.

Примечание API:
Этот подписчик не управляет потоком. Поэтому предоставленный consumer должен быть способен обрабатывать любое количество данных в своём темпе.
Параметры:
consumer - Consumer массивов байтов
Возвращает:
BodySubscriber

ofInputStream

public static HttpResponse.BodySubscriber<InputStream> ofInputStream()

Возвращает BodySubscriber, который транслирует тело ответа в виде InputStream.

HttpResponse, использующий этого подписчика, доступен сразу после чтения заголовков ответа, без необходимости ожидания обработки всего тела. Тело ответа затем можно читать непосредственно из InputStream.

Примечание API:
Чтобы гарантировать, что все ресурсы, связанные с соответствующим обменом, будут правильно освобождены, вызывающий метод должен либо прочитать все байты до достижения EOF, либо вызвать InputStream.close(), если это невозможно или нежелательно. Вызов close перед исчерпанием потока может привести к закрытию базового HTTP-соединения и предотвратить его повторное использование для последующих операций.
Возвращает:
подписчик на тело ответа, который транслирует тело ответа в виде InputStream.

ofLines

public static HttpResponse.BodySubscriber<Stream<String>> ofLines(Charset charset)

Возвращает BodySubscriber, который транслирует тело ответа в виде Stream, где каждая строка в потоке соответствует строке, определённой в BufferedReader.lines().

HttpResponse, использующий этого подписчика, доступен сразу после чтения заголовков ответа, без необходимости ожидания обработки всего тела. Тело ответа затем можно читать непосредственно из Stream.

Примечание API:
Для правильного освобождения всех ресурсов, связанных с соответствующим обменом, вызывающий метод должен убедиться, что он либо прочитал все строки до исчерпания потока, либо вызвал BaseStream.close(), если это невозможно или нежелательно. Вызов close до исчерпания потока может привести к закрытию базового HTTP-соединения и помешать его повторному использованию для последующих операций.
Параметры:
charset - кодировка символов, используемая при преобразовании байтов в символы
Возвращает:
подписчик тела, который передает тело ответа как Stream.
См. также:
BufferedReader.lines()

ofPublisher

public static HttpResponse.BodySubscriber<Flow.Publisher<List<ByteBuffer>>> ofPublisher()

Возвращает подписчика ответа, который публикует тело ответа через Publisher<List<ByteBuffer>>.

HttpResponse, использующий этого подписчика, доступен сразу после чтения заголовков ответа, без необходимости ожидания обработки всего тела. Байты тела ответа можно получить, подписавшись на издателя, возвращаемого методом HttpResponse body.

Издатель, возвращаемый методом body, может быть подписан только один раз. Первый подписчик получит байты тела ответа при успешном подключении или приведет к отмене подписки в противном случае. Если будут предприняты дополнительные попытки подписки, последующие подписчики будут немедленно подключены с пустой подпиской, и их метод onError будет вызван с IllegalStateException.

Примечание API:
Для правильного освобождения всех ресурсов, связанных с соответствующим обменом, вызывающий метод должен убедиться, что предоставленный издатель подписан один раз, и либо запрашивает все байты до onComplete или onError, либо отменяет предоставленную подписку, если это невозможно или нежелательно. Обратите внимание, что в зависимости от фактического используемого HTTP-протокола версии для обмена отмена подписки вместо исчерпания потока может привести к закрытию базового HTTP-соединения и предотвратить его повторное использование для последующих операций.
Возвращает:
BodySubscriber который публикует тело ответа через Publisher<List<ByteBuffer>>.

replacing

public static <U> HttpResponse.BodySubscriber<U> replacing(U value)

Возвращает подписчика ответа, который отбрасывает тело ответа. Предоставленное значение — это значение, которое будет возвращено из HttpResponse.body().

Параметры типа:
U - тип тела ответа
Параметры:
value - значение для возврата из HttpResponse.body(), может быть null
Возвращает:
BodySubscriber

discarding

public static HttpResponse.BodySubscriber<Void> discarding()

Возвращает подписчика ответа, который отбрасывает тело ответа.

Возвращает:
подписчик тела ответа

buffering

public static <T> HttpResponse.BodySubscriber<T> buffering(HttpResponse.BodySubscriber<T> downstream,
                                                           int bufferSize)

Возвращает BodySubscriber , который буферизует данные перед передачей их заданному подписчику вниз по потоку. Подписчик гарантирует доставку buffersize байтов данных каждому вызову метода onNext подписчика вниз по потоку, за исключением заключительного вызова, непосредственно перед вызовом onComplete. Заключительный вызов onNext может содержать меньше, чем bufferSize байт.

Возвращаемый подписчик делегирует свой метод getBody() подписчику вниз по потоку.

Параметры типа:
T - тип тела ответа
Параметры:
downstream - подписчик вниз по потоку
bufferSize - размер буфера
Возвращает:
подписчик буферизованного тела
Исключения:
IllegalArgumentException - если bufferSize <= 0

mapping

public static <T,U> HttpResponse.BodySubscriber<U> mapping​(HttpResponse.BodySubscriber<T> upstream,
                                                                 Function<? super T,​? extends U> mapper)

Возвращает BodySubscriber , значение тела ответа которого равно результату применения заданной функции к объекту тела данного upstream BodySubscriber.

Функция отображения выполняется с помощью исполнителя клиента executor и поэтому может использоваться для сопоставления любого типа тела ответа, включая блокирующий InputStream, как показано в следующем примере, который использует известный парсер JSON для преобразования InputStream в любой аннотированный тип Java.

Например: 

public static <W> BodySubscriber<W> asJSON(Class<W> targetType) {
     BodySubscriber<InputStream> upstream = BodySubscribers.ofInputStream();

     BodySubscriber<W> downstream = BodySubscribers.mapping(
           upstream,
           (InputStream is) -> {
               try (InputStream stream = is) {
                   ObjectMapper objectMapper = new ObjectMapper();
                   return objectMapper.readValue(stream, targetType);
               } catch (IOException e) {
                   throw new UncheckedIOException(e);
               }
           });
    return downstream;
 }
Параметры типа:
T - тип тела источника
U - тип возвращаемого подписчика тела
Параметры:
upstream - подписчик тела, подлежащий отображению
mapper - функция отображения
Возвращает:
подписчик отображения тела

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpResponse.BodySubscribers.html

Spec-Zone .ru
спецификации, руководства, описания, API