Module jdk.incubator.httpclient
Package jdk.incubator.http

## Interface HttpResponse.BodyHandler<T>

- Type Parameters:
    `T` - the response body type.
  Enclosing class:
    HttpResponse<T>
  Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

      @FunctionalInterface
      public static interface HttpResponse.BodyHandler<T>

  A handler for response bodies.
  Incubating Feature. Will be removed in a future release.

  This is a function that takes two parameters: the response status code, and the response headers, and which returns a `HttpResponse.BodyProcessor`. The function is always called just before the response body is read. Its implementation may examine the status code or headers and must decide, whether to accept the response body or discard it, and if accepting it, exactly how to handle it.

  Some pre-defined implementations which do not utilize the status code or headers (meaning the body is always accepted) are defined:

  - `asByteArray()`
  - `asByteArrayConsumer(Consumer)`
  - `asFileDownload(Path,OpenOption...)`
  - `discard(Object)`
  - `asString(Charset)`

  These implementations return the equivalent `HttpResponse.BodyProcessor`. Alternatively, the handler can be used to examine the status code or headers and return different body processors as appropriate.

  Examples of handler usage

  The first example uses one of the predefined handler functions which ignore the response headers and status, and always process the response body in the same way.

            HttpResponse<Path> resp = HttpRequest
                    .create(URI.create("http://www.foo.com"))
                    .GET()
                    .response(BodyHandler.asFile(Paths.get("/tmp/f")));

  Note, that even though these pre-defined handlers ignore the status code and headers, this information is still accessible from the `HttpResponse` when it is returned.

  In the second example, the function returns a different processor depending on the status code.

            HttpResponse<Path> resp1 = HttpRequest
                    .create(URI.create("http://www.foo.com"))
                    .GET()
                    .response(
                        (status, headers) -> status == 200
                            ? BodyProcessor.asFile(Paths.get("/tmp/f"))
                            : BodyProcessor.discard(Paths.get("/NULL")));

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `HttpResponse.BodyProcessor<T>` | `apply​(int statusCode, HttpHeaders responseHeaders)` | Returns a `BodyProcessor` considering the given response status code and headers.
    `static HttpResponse.BodyHandler<byte[]>` | `asByteArray​()` | Returns a `BodyHandler<byte[]>` that returns a `BodyProcessor`<`byte[]`> obtained from `BodyProcessor.asByteArray()`.
    `static HttpResponse.BodyHandler<Void>` | `asByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)` | Returns a `BodyHandler<Void>` that returns a `BodyProcessor``<Void>` obtained from `BodyProcessor.asByteArrayConsumer(Consumer)`.
    `static HttpResponse.BodyHandler<Path>` | `asFile​(Path file)` | Returns a `BodyHandler<Path>` that returns a `BodyProcessor``<Path>` obtained from `BodyProcessor.asFile(Path)`.
    `static HttpResponse.BodyHandler<Path>` | `asFile​(Path file, OpenOption... openOptions)` | Returns a `BodyHandler<Path>` that returns a `BodyProcessor``<Path>` obtained from `BodyProcessor.asFile(Path,OpenOption...)`.
    `static HttpResponse.BodyHandler<Path>` | `asFileDownload​(Path directory, OpenOption... openOptions)` | Returns a `BodyHandler<Path>` that returns a `BodyProcessor`<`Path`> where the download directory is specified, but the filename is obtained from the `Content-Disposition` response header.
    `static HttpResponse.BodyHandler<String>` | `asString​()` | Returns a `BodyHandler<String>` that returns a `BodyProcessor``<String>` obtained from `BodyProcessor.asString(Charset)`.
    `static HttpResponse.BodyHandler<String>` | `asString​(Charset charset)` | Returns a `BodyHandler<String>` that returns a `BodyProcessor``<String>` obtained from `BodyProcessor.asString(Charset)`.
    `static <U> HttpResponse.BodyHandler<U>` | `discard​(U value)` | Returns a response body handler which discards the response body and uses the given value as a replacement for it.

- - ### Method Detail

    - #### apply

          HttpResponse.BodyProcessor<T> apply​(int statusCode,
                                              HttpHeaders responseHeaders)

      Returns a `BodyProcessor` considering the given response status code and headers. This method is always called before the body is read and its implementation can decide to keep the body and store it somewhere or else discard it, by returning the `BodyProcessor` returned from `discard()`.
      Parameters:
        `statusCode` - the HTTP status code received
        `responseHeaders` - the response headers received
      Returns:
        a response body handler

    - #### discard

          static <U> HttpResponse.BodyHandler<U> discard​(U value)

      Returns a response body handler which discards the response body and uses the given value as a replacement for it.
      Type Parameters:
        `U` - the response body type
      Parameters:
        `value` - the value of U to return as the body
      Returns:
        a response body handler

    - #### asString

          static HttpResponse.BodyHandler<String> asString​(Charset charset)

      Returns a `BodyHandler<String>` that returns a `BodyProcessor``<String>` obtained from `BodyProcessor.asString(Charset)`. If a charset is provided, the body is decoded using it. If charset is `null` then the processor tries to determine the character set from the `Content-encoding` header. If that charset is not supported then `UTF_8` is used.
      Parameters:
        `charset` - the name of the charset to interpret the body as. If `null` then charset determined from Content-encoding header
      Returns:
        a response body handler

    - #### asFile

          static HttpResponse.BodyHandler<Path> asFile​(Path file)

      Returns a `BodyHandler<Path>` that returns a `BodyProcessor``<Path>` obtained from `BodyProcessor.asFile(Path)`.

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

      Parameters:
        `file` - the file to store the body in
      Returns:
        a response body handler

    - #### asFileDownload

          static HttpResponse.BodyHandler<Path> asFileDownload​(Path directory,
                                                               OpenOption... openOptions)

      Returns a `BodyHandler<Path>` that returns a `BodyProcessor`<`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`.
      Parameters:
        `directory` - the directory to store the file in
        `openOptions` - open options
      Returns:
        a response body handler

    - #### asFile

          static HttpResponse.BodyHandler<Path> asFile​(Path file,
                                                       OpenOption... openOptions)

      Returns a `BodyHandler<Path>` that returns a `BodyProcessor``<Path>` obtained from `BodyProcessor.asFile(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`.

      Parameters:
        `file` - the filename to store the body in
        `openOptions` - any options to use when opening/creating the file
      Returns:
        a response body handler

    - #### asByteArrayConsumer

          static HttpResponse.BodyHandler<Void> asByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)

      Returns a `BodyHandler<Void>` that returns a `BodyProcessor``<Void>` obtained from `BodyProcessor.asByteArrayConsumer(Consumer)`.

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

      Parameters:
        `consumer` - a Consumer to accept the response body
      Returns:
        a response body handler

    - #### asByteArray

          static HttpResponse.BodyHandler<byte[]> asByteArray​()

      Returns a `BodyHandler<byte[]>` that returns a `BodyProcessor`<`byte[]`> obtained from `BodyProcessor.asByteArray()`.

      When the `HttpResponse` object is returned, the body has been completely written to the byte array.

      Returns:
        a response body handler

    - #### asString

          static HttpResponse.BodyHandler<String> asString​()

      Returns a `BodyHandler<String>` that returns a `BodyProcessor``<String>` obtained from `BodyProcessor.asString(Charset)`. The body is decoded using the character set specified in the `Content-encoding` 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