Module java.httpclient
Package java.net.http

## Class HttpResponse

- java.lang.Object
- - java.net.http.HttpResponse

    public abstract class HttpResponse
    extends Object

Represents a response to a `HttpRequest`. A `HttpResponse` is available when the response status code and headers have been received, but before the response body is received.

Methods are provided in this class for accessing the response headers, and status code immediately and also methods for retrieving the response body. Static methods are provided which implement `HttpResponse.BodyProcessor` for standard body types such as `String, byte arrays, files`.

The `body` or `bodyAsync` which retrieve any response body must be called to ensure that the TCP connection can be re-used subsequently, and any response trailers accessed, if they exist, unless it is known that no response body was received.

Since:
  9

### Nested Class Summary

Nested Classes
`static interface` `HttpResponse.BodyProcessor<T>` A processor for response bodies, which determines the type of the response body returned from `HttpResponse`.
`static interface` `HttpResponse.MultiProcessor<T>` A response processor for a HTTP/2 multi response.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`static HttpResponse.BodyProcessor<byte[]>` `asByteArray()` Returns a `HttpResponse.BodyProcessor`<byte[]> which returns the response body as a `byte array`.
`static HttpResponse.BodyProcessor<Void>` `asByteArrayConsumer(Consumer<byte[]> consumer)` Returns a response processor which supplies the response body to the given Consumer.
`static HttpResponse.BodyProcessor<Path>` `asFile(Path file)` Returns a `HttpResponse.BodyProcessor`<`Path`> where the file is created if it does not already exist.
`static HttpResponse.BodyProcessor<Path>` `asFile(Path file, OpenOption... openOptions)` Returns a `HttpResponse.BodyProcessor`<`Path`>.
`static HttpResponse.BodyProcessor<Path>` `asFileDownload(Path directory, OpenOption... openOptions)` Returns a `HttpResponse.BodyProcessor`<`Path`> where the download directory is specified, but the filename is obtained from the Content-Disposition response header.
`static HttpResponse.BodyProcessor<InputStream>` `asInputStream()` Returns a response body processor which provides an InputStream to read the body.
`static HttpResponse.BodyProcessor<String>` `asString()` Returns a response processor which decodes the body using the character set specified in the `Content-encoding` response header.
`static HttpResponse.BodyProcessor<String>` `asString(Charset charset)` Returns a `HttpResponse.BodyProcessor`<`String`>.
`abstract <T> T` `body(HttpResponse.BodyProcessor<T> processor)` Returns the body, blocking if necessary.
`abstract <T> CompletableFuture<T>` `bodyAsync(HttpResponse.BodyProcessor<T> processor)` Returns a `CompletableFuture` of type T.
`abstract HttpHeaders` `headers()` Returns the received response headers.
`static HttpResponse.BodyProcessor<Void>` `ignoreBody()` Returns a response processor which ignores the response body.
`static HttpResponse.MultiProcessor<Map<URI,Path>>` `multiFile(Path destination)` Returns a MultiProcessor that handles multiple responses, writes the response bodies to files and which returns an aggregate response object that is a `Map<URI,Path>`.
`abstract HttpRequest` `request()` Returns the `HttpRequest` for this response.
`abstract SSLParameters` `sslParameters()` Returns the `SSLParameters` in effect for this response.
`abstract int` `statusCode()` Returns the status code for this response.
`abstract HttpHeaders` `trailers()` Returns the received response trailers, if there are any.
`abstract URI` `uri()` Returns the URI that the response was received from.
`abstract HttpClient.Version` `version()` Returns the HTTP protocol version that was used for this response.

### Methods inherited from class java.lang.Object

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

### Method Detail

#### statusCode

    public abstract int statusCode()

Returns the status code for this response.

Returns:
  the response code

#### request

    public abstract HttpRequest request()

Returns the `HttpRequest` for this response.

Returns:
  the request

#### headers

    public abstract HttpHeaders headers()

Returns the received response headers.

Returns:
  the response headers

#### trailers

    public abstract HttpHeaders trailers()

Returns the received response trailers, if there are any. This must only be called after the response body has been received.

Returns:
  the response trailers (may be empty)
Throws:
  `IllegalStateException` - if the response body has not been received yet

#### body

    public abstract <T> T body(HttpResponse.BodyProcessor<T> processor)

Returns the body, blocking if necessary. The type T is determined by the `HttpResponse.BodyProcessor` implementation supplied. The body object will be returned immediately if it is a type (such as `InputStream` which reads the data itself. If the body object represents the fully read body then it blocks until it is fully read.

Type Parameters:
  `T` - the type of the returned body object
Parameters:
  `processor` - the processor to handle the response body
Returns:
  the body
Throws:
  `UncheckedIOException` - if an I/O error occurs reading the response

#### bodyAsync

    public abstract <T> CompletableFuture<T> bodyAsync(HttpResponse.BodyProcessor<T> processor)

Returns a `CompletableFuture` of type T. This always returns immediately and the future completes when the body object is available. The body will be available immediately if it is a type (such as `InputStream` which reads the data itself. If the body object represents the fully read body then it will not be available until it is fully read.

Type Parameters:
  `T` - the type of the returned body object
Parameters:
  `processor` - the processor to handle the response body
Returns:
  a CompletableFuture

#### sslParameters

    public abstract SSLParameters sslParameters()

Returns the `SSLParameters` in effect for this response. Returns `null` if this is not a https response.

Returns:
  the SSLParameters associated with the response

#### uri

    public abstract URI uri()

Returns the URI that the response was received from. This may be different from the request URI if redirection occurred.

Returns:
  the URI of the response

#### version

    public abstract HttpClient.Version version()

Returns the HTTP protocol version that was used for this response.

Returns:
  HTTP protocol version

#### asFile

    public static HttpResponse.BodyProcessor<Path> asFile(Path file)

Returns a `HttpResponse.BodyProcessor`<`Path`> where the file is created if it does not already exist. When the Path object is returned, the body has been completely written to the file.

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

#### asFileDownload

    public static HttpResponse.BodyProcessor<Path> asFileDownload(Path directory,
                                                                  OpenOption... openOptions)

Returns a `HttpResponse.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 Path object is returned, the body has been completely written to 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 `BodyProcessor`

#### asFile

    public static HttpResponse.BodyProcessor<Path> asFile(Path file,
                                                          OpenOption... openOptions)

Returns a `HttpResponse.BodyProcessor`<`Path`>.

`HttpResponse`s returned using this response processor complete after the entire response, including body has been read.

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

#### asByteArrayConsumer

    public static HttpResponse.BodyProcessor<Void> asByteArrayConsumer(Consumer<byte[]> consumer)

Returns a response processor which supplies the response body to the given Consumer. Each time data is received the consumer is invoked with a byte[] containing at least one byte of data. After the final buffer is received, the consumer is invoked one last time, with an empty byte array.

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

#### asInputStream

    public static HttpResponse.BodyProcessor<InputStream> asInputStream()

Returns a response body processor which provides an InputStream to read the body.

Implementation Note:
  This mechanism is provided primarily for backwards compatibility for code that expects InputStream. It is recommended for better performance to use one of the other response processor implementations.
Returns:
  a `BodyProcessor`

#### asByteArray

    public static HttpResponse.BodyProcessor<byte[]> asByteArray()

Returns a `HttpResponse.BodyProcessor`<byte[]> which returns the response body as a `byte array`.

Returns:
  a `BodyProcessor`

#### asString

    public static HttpResponse.BodyProcessor<String> asString()

Returns a response processor which decodes the body 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 `ISO_8859_1` is used.

Returns:
  a `BodyProcessor`

#### multiFile

    public static HttpResponse.MultiProcessor<Map<URI,Path>> multiFile(Path destination)

Returns a MultiProcessor that handles multiple responses, writes the response bodies to files and which returns an aggregate response object that is a `Map<URI,Path>`. The keyset of the Map represents the URIs of the original request and any additional requests generated by the server. The values are the paths of the destination files. Each path uses the URI path of the request offset from the destination parent directory provided.

All incoming additional requests (push promises) are accepted by this multi response processor. Errors are effectively ignored and any failed responses are simply omitted from the result Map. Other implementations of MultiProcessor can handle these situations

Example usage

        CompletableFuture<Map<URI,Path>> cf =
        HttpRequest.create(new URI("https://www.foo.com/"))
                   .version(Version.HTTP2)
                   .GET()
                   .sendAsyncMulti(HttpResponse.multiFile("/usr/destination"));

        Map<URI,Path> results = cf.join();

Parameters:
  `destination` - the destination parent directory of all response bodies
Returns:
  a MultiProcessor

#### asString

    public static HttpResponse.BodyProcessor<String> asString(Charset charset)

Returns a `HttpResponse.BodyProcessor`<`String`>.

Parameters:
  `charset` - the name of the charset to interpret the body as. If `null` then the processor tries to determine the character set from the `Content-encoding` header. If that charset is not supported then `ISO_8859_1` is used.
Returns:
  a `BodyProcessor`

#### ignoreBody

    public static HttpResponse.BodyProcessor<Void> ignoreBody()

Returns a response processor which ignores the response body.

Returns:
  a `BodyProcessor`