Module java.net.http
Package java.net.http

Class HttpResponse.BodyHandlers

  • Enclosing interface:
    HttpResponse<T>
    public static class HttpResponse.BodyHandlers
extends Object
    Implementations of BodyHandler that implement various useful handlers, such as handling the response body as a String, or streaming the response body to a file.

    These implementations do not examine the status code, meaning the body is always accepted. They typically return an equivalently named BodySubscriber. Alternatively, a custom handler can be used to examine the status code and headers, and return a different body subscriber, of the same type, as appropriate.

    The following are examples of using the predefined body handlers to convert a flow of response body data into common high-level Java objects: 

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

    Since:
    11

    • Method Detail

      • fromSubscriber

        public static HttpResponse.BodyHandler<Void> fromSubscriber​(Flow.Subscriber<? super List<ByteBuffer>> subscriber)
        Returns a response body handler that returns a BodySubscriber<Void> obtained from HttpResponse.BodySubscribers.fromSubscriber(Subscriber), with the given subscriber.

        The response body is not available through this, or the HttpResponse API, but instead all response body is forwarded to the given subscriber, which should make it available, if appropriate, through some other mechanism, e.g. an entry in a database, etc.

        API Note:
        This method can be used as an adapter between BodySubscriber and Flow.Subscriber.

        For example: 

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

        Parameters:
        subscriber - the subscriber
        Returns:
        a response body handler

      • fromSubscriber

        public static <S extends Flow.Subscriber<? super List<ByteBuffer>>,​T> HttpResponse.BodyHandler<T> fromSubscriber​(S subscriber,
                                                                                                                       Function<? super S,​? extends T> finisher)
        Returns a response body handler that returns a BodySubscriber<T> obtained from HttpResponse.BodySubscribers.fromSubscriber(Subscriber, Function), with the given subscriber and finisher function.

        The given finisher function is applied after the given subscriber's onComplete has been invoked. The finisher function is invoked with the given subscriber, and returns a value that is set as the response's body.

        API Note:
        This method can be used as an adapter between BodySubscriber and Flow.Subscriber.

        For example: 

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

        Type Parameters:
        S - the type of the Subscriber
        T - the type of the response body
        Parameters:
        subscriber - the subscriber
        finisher - a function to be applied after the subscriber has completed
        Returns:
        a response body handler

      • fromLineSubscriber

        public static HttpResponse.BodyHandler<Void> fromLineSubscriber​(Flow.Subscriber<? super String> subscriber)
        Returns a response body handler that returns a BodySubscriber<Void> obtained from BodySubscribers.fromLineSubscriber(subscriber, s -> null, charset, null), with the given subscriber. The charset used to decode the response body bytes is obtained from the HTTP response headers as specified by ofString(), and lines are delimited in the manner of BufferedReader.readLine().

        The response body is not available through this, or the HttpResponse API, but instead all response body is forwarded to the given subscriber, which should make it available, if appropriate, through some other mechanism, e.g. an entry in a database, etc.

        API Note:
        This method can be used as an adapter between a BodySubscriber and a text based Flow.Subscriber that parses text line by line.

        For example: 

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

        Parameters:
        subscriber - the subscriber
        Returns:
        a response body handler

      • fromLineSubscriber

        public static <S extends Flow.Subscriber<? super String>,​T> HttpResponse.BodyHandler<T> fromLineSubscriber​(S subscriber,
                                                                                                                 Function<? super S,​? extends T> finisher,
                                                                                                                 String lineSeparator)
        Returns a response body handler that returns a BodySubscriber<T> obtained from BodySubscribers.fromLineSubscriber(subscriber, finisher, charset, lineSeparator), with the given subscriber, finisher function, and line separator. The charset used to decode the response body bytes is obtained from the HTTP response headers as specified by ofString().

        The given finisher function is applied after the given subscriber's onComplete has been invoked. The finisher function is invoked with the given subscriber, and returns a value that is set as the response's body.

        API Note:
        This method can be used as an adapter between a BodySubscriber and a text based Flow.Subscriber that parses text line by line.

        For example: 

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

        Type Parameters:
        S - the type of the Subscriber
        T - the type of the response body
        Parameters:
        subscriber - the subscriber
        finisher - a function to be applied after the subscriber has completed
        lineSeparator - an optional line separator: can be null, in which case lines will be delimited in the manner of BufferedReader.readLine().
        Returns:
        a response body handler
        Throws:
        IllegalArgumentException - if the supplied lineSeparator is the empty string

      • discarding

        public static HttpResponse.BodyHandler<Void> discarding()
        Returns a response body handler that discards the response body.
        Returns:
        a response body handler

      • replacing

        public static <U> HttpResponse.BodyHandler<U> replacing​(U value)
        Returns a response body handler that returns the given replacement value, after discarding the response body.
        Type Parameters:
        U - the response body type
        Parameters:
        value - the value of U to return as the body, may be null
        Returns:
        a response body handler

      • ofFile

        public static HttpResponse.BodyHandler<Path> ofFile​(Path file,
                                                    OpenOption... openOptions)
        Returns a BodyHandler<Path> that returns a BodySubscriber<Path> obtained from BodySubscribers.ofFile(Path,OpenOption...).

        When the HttpResponse object is returned, the body has been completely written to the file, and HttpResponse.body() returns a reference to its Path.

        Security manager permission checks are performed in this factory method, when the BodyHandler is created. Care must be taken that the BodyHandler is not shared with untrusted code.

        Parameters:
        file - the file to store the body in
        openOptions - any options to use when opening/creating the file
        Returns:
        a response body handler
        Throws:
        IllegalArgumentException - if an invalid set of open options are specified
        SecurityException - If a security manager has been installed and it denies write access to the file.

      • ofFile

        public static HttpResponse.BodyHandler<Path> ofFile​(Path file)
        Returns a BodyHandler<Path> that returns a BodySubscriber<Path>.

        Equivalent to: ofFile(file, CREATE, WRITE)

        Security manager permission checks are performed in this factory method, when the BodyHandler is created. Care must be taken that the BodyHandler is not shared with untrusted code.

        Parameters:
        file - the file to store the body in
        Returns:
        a response body handler
        Throws:
        SecurityException - If a security manager has been installed and it denies write access to the file.

      • ofFileDownload

        public static HttpResponse.BodyHandler<Path> ofFileDownload​(Path directory,
                                                            OpenOption... openOptions)
        Returns a BodyHandler<Path> that returns a BodySubscriber<Path> where the download directory is specified, but the filename is obtained from the Content-Disposition response header. The Content-Disposition header must specify the attachment type and must also contain a filename parameter. If the filename specifies multiple path components only the final component is used as the filename (with the given directory name).

        When the HttpResponse object is returned, the body has been completely written to the file and HttpResponse.body() returns a Path object for the file. The returned Path is the combination of the supplied directory name and the file name supplied by the server. If the destination directory does not exist or cannot be written to, then the response will fail with an IOException.

        Security manager permission checks are performed in this factory method, when the BodyHandler is created. Care must be taken that the BodyHandler is not shared with untrusted code.

        Parameters:
        directory - the directory to store the file in
        openOptions - open options used when opening the file
        Returns:
        a response body handler
        Throws:
        IllegalArgumentException - if the given path does not exist, is not a directory, is not writable, or if an invalid set of open options are specified
        SecurityException - If a security manager has been installed and it denies read access to the directory, or it denies write access to the directory, or it denies write access to the files within the directory.

      • ofByteArrayConsumer

        public static HttpResponse.BodyHandler<Void> ofByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)
        Returns a BodyHandler<Void> that returns a BodySubscriber<Void> obtained from BodySubscribers.ofByteArrayConsumer(Consumer).

        When the HttpResponse object is returned, the body has been completely written to the consumer.

        API Note:
        The subscriber returned by this handler is not flow controlled. Therefore, the supplied consumer must be able to process whatever amount of data is delivered in a timely fashion.
        Parameters:
        consumer - a Consumer to accept the response body
        Returns:
        a response body handler

      • ofString

        public static HttpResponse.BodyHandler<String> ofString()
        Returns a BodyHandler<String> that returns a BodySubscriber<String> obtained from BodySubscribers.ofString(Charset). The body is decoded using the character set specified in the Content-Type response header. If there is no such header, or the character set is not supported, then UTF_8 is used.

        When the HttpResponse object is returned, the body has been completely written to the string.

        Returns:
        a response body handler