Класс HttpResponse.BodySubscribers

java.lang.Object

java.net.http.HttpResponse.BodySubscribers

Вложенный интерфейс:: HttpResponse<T>

public static class HttpResponse.BodySubscribers extends Object

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

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

// Streams the response body to a File
HttpResponse<Path> response = client
  .send(request, responseInfo -> BodySubscribers.ofFile(Paths.get("example.html"));

// 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));

Примечание API:: Некоторые реализации тела, созданные подписчиками тела, могут позволять потоковую передачу байтов ответа вызывающей стороне. Эти реализации обычно являются AutoCloseable и могут потребовать явного закрытия, чтобы ресурсы, связанные с запросом и клиентом, были в конечном итоге освобождены. Некоторые другие реализации являются публикаторами, которые необходимо subscribed, чтобы их связанные ресурсы были освобождены, а связанный запрос был завершен.
С:: 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<String>`, где каждая строка в потоке соответствует строке, как определено в `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)

Переданная функция 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)

Примечание 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)

Возвращает подписчика тела, который хранит тело ответа как строку, преобразованную с использованием заданного 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 с использованием этого подписчика доступен после чтения всего ответа.

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

ofFile

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

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

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

Параметры:: file - файл для хранения тела
Возвращает:: подписчик тела

ofByteArrayConsumer

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

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


 Optional

будет пустым.

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

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

END_OF_DOCUMENT_MARKER

ofInputStream

public static HttpResponse.BodySubscriber<InputStream> ofInputStream()

Возвращает BodySubscriber, который передает тело ответа как потоковый ввод.

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

API Note:: Для правильного освобождения всех ресурсов, связанных с соответствующим обменом, вызывающая сторона должна гарантировать чтение всех байтов до достижения конца потока или вызов close(), если это невозможно или нежелательно. Вызов close до исчерпания потока может привести к закрытию базового соединения HTTP и предотвратить его повторное использование для последующих операций.
Implementation Note:: Метод read интерфейса InputStream, возвращаемый по умолчанию этим методом, бросит IOException с статусом прерывания потока, если поток будет прерван во время блокировки на чтение. В этом случае запрос также будет отменён, и поток InputStream будет закрыт.
Returns:: подписчик потокового тела, который передает тело ответа как потоковый ввод.

ofLines

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

Возвращает BodySubscriber, который передает тело ответа как поток<String>, где каждая строка в потоке соответствует строке, определенной lines().

API Note:

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

Parameters:

charset - кодировка символов, которая будет использована при преобразовании байтов в символы

Returns:

подписчик потокового тела, который передает тело ответа как поток<String>.

See Also:

ofPublisher

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

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

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

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

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

replacing

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

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

Type Parameters:: U - тип тела ответа
Parameters:: value - значение, которое будет возвращено из HttpResponse.body(), может быть null
Returns:: подписчик тела

discarding

public static HttpResponse.BodySubscriber<Void> discarding()

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

Returns:: подписчик тела ответа

buffering

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

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

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

Type Parameters:: T - тип тела ответа
Parameters:: downstream - подписчик; bufferSize - размер буфера
Returns:: буферизующий подписчик тела
Throws:: 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), предпочтительнее отобразить на поставщик желаемого типа и отложить блокирующую операцию до вызова get() потоком вызывающей стороны, как показано в следующем примере, использующем известный парсер JSON для преобразования InputStream в любой аннотированный тип Java.

Например:

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

   BodySubscriber<Supplier<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;
}

Type Parameters:: T - тип тела исходного подписчика; U - тип подписчика тела, возвращаемого после отображения
Parameters:: upstream - подписчик тела; mapper - функция отображения
Returns:: подписчик тела с отображением

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.net.http/java/net/http/HttpResponse.BodySubscribers.html