Класс HttpResponse.BodyHandlers

java.lang.Object

java.net.http.HttpResponse.BodyHandlers

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

public static class HttpResponse.BodyHandlers extends Object

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

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

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

// Receives the response body as a String
HttpResponse<String> response = client
  .send(request, BodyHandlers.ofString());

// Receives the response body as a file
HttpResponse<Path> response = client
  .send(request, BodyHandlers.ofFile(Paths.get("example.html")));

// Receives the response body as an InputStream
HttpResponse<InputStream> response = client
  .send(request, BodyHandlers.ofInputStream());

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

С:: 11

Краткое описание методов

Модификатор и тип	Метод	Описание
`static <T> HttpResponse.BodyHandler<T>`	`buffering(HttpResponse.BodyHandler<T> downstreamHandler, int bufferSize)`	Возвращает `BodyHandler`, который при вызове возвращает буферизованного подписчика тела, который буферизует данные перед передачей их подписчику-получателю.
`static HttpResponse.BodyHandler<Void>`	`discarding()`	Возвращает обработчик тела ответа, который игнорирует тело ответа.
`static HttpResponse.BodyHandler<Void>`	`fromLineSubscriber(Flow.Subscriber<? super String> subscriber)`	Возвращает обработчик тела ответа, который возвращает `BodySubscriber<Void>` полученный из `BodySubscribers.fromLineSubscriber(subscriber, s -> null, charset, null)` с заданным `subscriber`.
`static <S extends Flow.Subscriber<? super String>, T> HttpResponse.BodyHandler<T>`	`fromLineSubscriber(S subscriber, Function<? super S,? extends T> finisher, String lineSeparator)`	Возвращает обработчик тела ответа, который возвращает `BodySubscriber<T>` полученный из `BodySubscribers.fromLineSubscriber(subscriber, finisher, charset, lineSeparator)` с заданным `subscriber`, `finisher` функцией и разделителем строк.
`static HttpResponse.BodyHandler<Void>`	`fromSubscriber(Flow.Subscriber<? super List<ByteBuffer>> subscriber)`	Возвращает обработчик тела ответа, который возвращает `BodySubscriber<Void>` полученный из `HttpResponse.BodySubscribers.fromSubscriber(Subscriber)` с заданным `subscriber`.
`static <S extends Flow.Subscriber<? super List<ByteBuffer>>, T> HttpResponse.BodyHandler<T>`	`fromSubscriber(S subscriber, Function<? super S,? extends T> finisher)`	Возвращает обработчик тела ответа, который возвращает `BodySubscriber<T>` полученный из `HttpResponse.BodySubscribers.fromSubscriber(Subscriber, Function)` с заданной `subscriber` и `finisher` функцией.
`static HttpResponse.BodyHandler<byte[]>`	`ofByteArray()`	Возвращает `BodyHandler<byte[]>`, который возвращает `BodySubscriber<byte[]>` полученный из `BodySubscribers.ofByteArray()`.
`static HttpResponse.BodyHandler<Void>`	`ofByteArrayConsumer(Consumer<Optional<byte[]>> consumer)`	Возвращает `BodyHandler<Void>`, который возвращает `BodySubscriber<Void>` полученный из `BodySubscribers.ofByteArrayConsumer(Consumer)`.
`static HttpResponse.BodyHandler<Path>`	`ofFile(Path file)`	Возвращает `BodyHandler<Path>`, который возвращает `BodySubscriber<Path>`.
`static HttpResponse.BodyHandler<Path>`	`ofFile(Path file, OpenOption... openOptions)`	Возвращает `BodyHandler<Path>`, который возвращает `BodySubscriber<Path>` полученный из `BodySubscribers.ofFile(Path,OpenOption...)`.
`static HttpResponse.BodyHandler<Path>`	`ofFileDownload(Path directory, OpenOption... openOptions)`	Возвращает `BodyHandler<Path>`, который возвращает `BodySubscriber`<`Path`>, где каталог загрузки указан, а имя файла взято из `Content-Disposition` заголовка ответа.
`static HttpResponse.BodyHandler<InputStream>`	`ofInputStream()`	Возвращает `BodyHandler<InputStream>`, который возвращает `BodySubscriber<InputStream>` полученный из `BodySubscribers.ofInputStream`.
`static HttpResponse.BodyHandler<Stream<String>>`	`ofLines()`	Возвращает `BodyHandler<Stream<String>>`, который возвращает `BodySubscriber<Stream<String>>` полученный из `BodySubscribers.ofLines(charset)`.
`static HttpResponse.BodyHandler<Flow.Publisher<List<ByteBuffer>>>`	`ofPublisher()`	Возвращает `BodyHandler<Publisher<List<ByteBuffer>>>`, который создаёт `BodySubscriber<Publisher<List<ByteBuffer>>>` полученный из `BodySubscribers.ofPublisher()`.
`static HttpResponse.BodyHandler<String>`	`ofString()`	Возвращает `BodyHandler<String>`, который возвращает `BodySubscriber<String>` полученный из `BodySubscribers.ofString(Charset)`.
`static HttpResponse.BodyHandler<String>`	`ofString(Charset charset)`	Возвращает `BodyHandler<String>`, который возвращает `BodySubscriber<String>` полученный из `BodySubscribers.ofString(Charset)`.
`static <U> HttpResponse.BodyHandler<U>`	`replacing(U value)`	Возвращает обработчик тела ответа, который возвращает заданное значение замены после игнорирования тела ответа.

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

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

Подробное описание методов

fromSubscriber

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

Возвращает обработчик тела ответа, который возвращает BodySubscriber<Void> полученный из HttpResponse.BodySubscribers.fromSubscriber(Subscriber), с заданным subscriber.

Тело ответа недоступно через этот или HttpResponse API, но вместо этого всё тело ответа передается заданному subscriber, что должно сделать его доступным, если это необходимо, например, через запись в базе данных и т.п.

Примечание API:

Этот метод может быть использован в качестве адаптера между


 BodySubscriber

и Flow.Subscriber.

Например:

TextSubscriber subscriber = new TextSubscriber();
HttpResponse<Void> response = client.sendAsync(request,
    BodyHandlers.fromSubscriber(subscriber)).join();
System.out.println(response.statusCode());

Параметры:

subscriber - подписчик

Возвращает:

обработчик тела ответа

fromSubscriber

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

Возвращает обработчик тела ответа, который возвращает BodySubscriber<T> полученный из HttpResponse.BodySubscribers.fromSubscriber(Subscriber, Function), с заданным subscriber и finisher функцией.

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

Примечание API:

Этот метод может быть использован в качестве адаптера между


 BodySubscriber

и Flow.Subscriber.

Например:

TextSubscriber subscriber = ...;  // accumulates bytes and transforms them into a String
HttpResponse<String> response = client.sendAsync(request,
    BodyHandlers.fromSubscriber(subscriber, TextSubscriber::getTextResult)).join();
String text = response.body();

Параметры типа:

S - тип подписчика

T - тип тела ответа

Параметры:

subscriber - подписчик

finisher - функция, которая применяется после завершения работы подписчика

Возвращает:

обработчик тела ответа

fromLineSubscriber

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

Возвращает обработчик тела ответа, который возвращает BodySubscriber<Void> полученный из BodySubscribers.fromLineSubscriber(subscriber, s -> null, charset, null), с заданным subscriber. Кодировка charset, используемая для декодирования байтов тела ответа, извлекается из заголовков HTTP-ответа в соответствии со спецификацией ofString(), а строки разделяются так, как описано в BufferedReader.readLine().

Примечание API:

Этот метод может быть использован в качестве адаптера между


 BodySubscriber

и основанным на тексте Flow.Subscriber парсером, который анализирует текст по строкам.

Например:

// A PrintSubscriber that implements Flow.Subscriber<String>
// and print lines received by onNext() on System.out
PrintSubscriber subscriber = new PrintSubscriber(System.out);
client.sendAsync(request, BodyHandlers.fromLineSubscriber(subscriber))
    .thenApply(HttpResponse::statusCode)
    .thenAccept((status) -> {
        if (status != 200) {
            System.err.printf("ERROR: %d status received%n", status);
        }
    });

Параметры:

subscriber - подписчик

Возвращает:

обработчик тела ответа

fromLineSubscriber

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

Возвращает обработчик тела ответа, который возвращает BodySubscriber<T> полученный из BodySubscribers.fromLineSubscriber(subscriber, finisher, charset, lineSeparator), с заданным subscriber, finisher функцией и разделителем строк. Кодировка charset, используемая для декодирования байтов тела ответа, извлекается из заголовков HTTP-ответа в соответствии со спецификацией ofString().

Примечание API:

Этот метод может быть использован в качестве адаптера между


 BodySubscriber

и основанным на тексте Flow.Subscriber парсером, который анализирует текст по строкам.

Например:

// A LineParserSubscriber that implements Flow.Subscriber<String>
// and accumulates lines that match a particular pattern
Pattern pattern = ...;
LineParserSubscriber subscriber = new LineParserSubscriber(pattern);
HttpResponse<List<String>> response = client.send(request,
    BodyHandlers.fromLineSubscriber(subscriber, s -> s.getMatchingLines(), "\n"));
if (response.statusCode() != 200) {
    System.err.printf("ERROR: %d status received%n", response.statusCode());
}

Параметры типа:

S - тип подписчика

T - тип тела ответа

Параметры:

subscriber - подписчик

finisher - функция, которая применяется после завершения работы подписчика

lineSeparator - необязательный разделитель строк: может быть null, в этом случае строки будут разделяться в соответствии с BufferedReader.readLine().

Возвращает:

обработчик тела ответа

Исключения:

IllegalArgumentException - если переданный lineSeparator пустая строка

discarding

public static HttpResponse.BodyHandler<Void> discarding()

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

Возвращает:: обработчик тела ответа

replacing

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

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

Параметры типа:: U - тип тела ответа
Параметры:: value - значение U, которое нужно вернуть в качестве тела, может быть null
Возвращает:: обработчик тела ответа

ofString

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

Возвращает BodyHandler<String>, который возвращает BodySubscriber<String> полученный из BodySubscribers.ofString(Charset). Тело декодируется с использованием заданного набора символов.

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

ofFile

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

Возвращает BodyHandler<Path>, который возвращает BodySubscriber<Path> полученный из BodySubscribers.ofFile(Path,OpenOption...).

При возврате объекта HttpResponse тело полностью записано в файл, и HttpResponse.body() возвращает ссылку на его Path.

В случае стандартного поставщика файловой системы проверки разрешений менеджера безопасности выполняются в этом методе-фабрике при создании BodyHandler. В противном случае, проверки разрешений могут выполняться асинхронно в контексте вызывающего кода при доступе к файлу. Необходимо позаботиться о том, чтобы BodyHandler не был предоставлен небезопасным кодом.

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

ofFile

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

Возвращает BodyHandler<Path>, который возвращает BodySubscriber<Path>.

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

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

ofFileDownload

public static HttpResponse.BodyHandler<Path> ofFileDownload(Path directory, OpenOption... openOptions)

Возвращает BodyHandler<Path>, который возвращает BodySubscriber<Path>, где каталог загрузки указан, но имя файла извлекается из заголовка ответа Content-Disposition. Заголовок Content-Disposition должен указывать тип вложения и также содержать параметр имя файла. Если имя файла указывает несколько компонентов пути, используется только последний компонент в качестве имени файла (с заданным именем каталога).

При возвращении объекта HttpResponse, тело полностью записывается в файл, и HttpResponse.body() возвращает объект Path для файла. Возвращаемое значение Path — это комбинация заданного имени каталога и имени файла, предоставленного сервером. Если целевой каталог не существует или в него нельзя записать, ответ завершится с IOException.

Проверки разрешений менеджера безопасности выполняются в этом методе-фабрике при создании BodyHandler. Необходимо следить за тем, чтобы BodyHandler не использовался с небезопасным кодом.

Parameters:: directory - каталог для хранения файла; openOptions - параметры открытия, используемые при открытии файла
Returns:: обработчик тела ответа
Throws:: IllegalArgumentException - если указанный путь не существует, не является файловой системой по умолчанию, не является каталогом, не доступен для записи или если указан неверный набор параметров открытия; SecurityException - в случае провайдера файловой системы по умолчанию и установленного менеджера безопасности, который запрещает доступ для чтения к каталогу, или запрещает доступ для записи к каталогу, или запрещает доступ для записи к файлам внутри каталога.

ofInputStream

public static HttpResponse.BodyHandler<InputStream> ofInputStream()

Возвращает BodyHandler<InputStream>, который возвращает BodySubscriber<InputStream> полученный из BodySubscribers.ofInputStream.

При возвращении объекта HttpResponse, заголовки ответа будут полностью прочитаны, но тело может быть ещё не полностью получено. Метод HttpResponse.body() возвращает InputStream, из которого можно читать тело по мере получения.

API Note:: См. HttpResponse.BodySubscribers.ofInputStream() для получения дополнительной информации.
Returns:: обработчик тела ответа

ofLines

public static HttpResponse.BodyHandler<Stream<String>> ofLines()

Возвращает BodyHandler<Stream<String>>, который возвращает BodySubscriber<Stream<String>> полученный из BodySubscribers.ofLines(charset). Кодировка, используемая для декодирования байтов тела ответа, получена из заголовков HTTP-ответа, как указано в ofString(), а строки разделяются так же, как в BufferedReader.readLine().

При возвращении объекта HttpResponse, тело может быть ещё не полностью получено.

Returns:: обработчик тела ответа

ofByteArrayConsumer

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

Возвращает BodyHandler<Void>, который возвращает BodySubscriber<Void> полученный из BodySubscribers.ofByteArrayConsumer(Consumer).

При возвращении объекта HttpResponse, тело полностью записано в потребитель.

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

ofByteArray

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

Возвращает BodyHandler<byte[]>, который возвращает BodySubscriber<byte[]> полученный из BodySubscribers.ofByteArray().

При возвращении объекта HttpResponse, тело полностью записано в массив байтов.

Returns:: обработчик тела ответа

ofString

public static HttpResponse.BodyHandler<String> ofString()

Возвращает BodyHandler<String>, который возвращает BodySubscriber<String> полученный из BodySubscribers.ofString(Charset). Тело декодируется с помощью кодировки символов, указанной в заголовке ответа Content-Type. Если такого заголовка нет или кодировка не поддерживается, используется UTF_8.

При возвращении объекта HttpResponse, тело полностью записано в строку.

Returns:: обработчик тела ответа

ofPublisher

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

Возвращает BodyHandler<Publisher<List<ByteBuffer>>>, который создаёт BodySubscriber<Publisher<List<ByteBuffer>>> полученный из BodySubscribers.ofPublisher().

При возвращении объекта HttpResponse, заголовки ответа будут полностью прочитаны, но тело может быть ещё не полностью получено. Метод HttpResponse.body() возвращает Publisher<List<ByteBuffer>>, из которого можно получить байты тела ответа по мере их получения. Публикатор может и должен быть подписан только один раз.

API Note:: См. HttpResponse.BodySubscribers.ofPublisher() для получения дополнительной информации.
Returns:: обработчик тела ответа

buffering

public static <T> HttpResponse.BodyHandler<T> buffering(HttpResponse.BodyHandler<T> downstreamHandler, int bufferSize)

Возвращает BodyHandler который, при вызове, возвращает буферизованный BodySubscriber, который буферизует данные перед передачей их в последующий подписчик. Эти BodySubscriber экземпляры создаются вызовом BodySubscribers.buffering с подписчиком, полученным из данного обработчика, и параметром bufferSize.

Type Parameters:: T - тип тела ответа
Parameters:: downstreamHandler - обработчик последующего подписчика; bufferSize - размер буфера, переданный в BodySubscribers.buffering
Returns:: обработчик тела
Throws:: IllegalArgumentException - если bufferSize <= 0

© 1993, 2023, 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/21/docs/api/java.net.http/java/net/http/HttpResponse.BodyHandlers.html