Класс 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`, который при вызове возвращает буферизирующий BodySubscriber, который буферизует данные перед их передачей подписчику ниже по потоку.
`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 не был доступен недоверенному коду.

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

ofInputStream

public static HttpResponse.BodyHandler<InputStream> ofInputStream()

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

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

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

ofLines

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

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

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

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

ofByteArrayConsumer

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

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

Когда возвращается объект HttpResponse, тело полностью записывается в потребителя.

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

ofByteArray

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

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

Когда возвращается объект HttpResponse, тело полностью записывается в массив байтов.

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

ofString

public static HttpResponse.BodyHandler<String> ofString()

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

Когда возвращается объект HttpResponse, тело полностью записывается в строку.

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

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:: См. HttpResponse.BodySubscribers.ofPublisher() для получения дополнительной информации.
Возвращает:: обработчик тела ответа

buffering

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

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

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

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