public abstract class HttpResponse extends Object
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.
Modifier and Type | Class | Description |
---|---|---|
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.
|
Modifier and Type | Method | Description |
---|---|---|
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.
|
public abstract int statusCode()
public abstract HttpRequest request()
HttpRequest
for this response.public abstract HttpHeaders headers()
public abstract HttpHeaders trailers()
IllegalStateException
- if the response body has not been received
yetpublic abstract <T> T body(HttpResponse.BodyProcessor<T> processor)
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.T
- the type of the returned body objectprocessor
- the processor to handle the response bodyUncheckedIOException
- if an I/O error occurs reading the
responsepublic abstract <T> CompletableFuture<T> bodyAsync(HttpResponse.BodyProcessor<T> processor)
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.T
- the type of the returned body objectprocessor
- the processor to handle the response bodypublic abstract SSLParameters sslParameters()
SSLParameters
in effect for this
response. Returns null
if this is not a https response.public abstract URI uri()
public abstract HttpClient.Version version()
public static HttpResponse.BodyProcessor<Path> asFile(Path file)
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.file
- the file to store the body inBodyProcessor
public static HttpResponse.BodyProcessor<Path> asFileDownload(Path directory, OpenOption... openOptions)
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.directory
- the directory to store the file inopenOptions
- open optionsBodyProcessor
public static HttpResponse.BodyProcessor<Path> asFile(Path file, OpenOption... openOptions)
HttpResponse.BodyProcessor
<Path
>.
HttpResponse
s returned using this response processor complete
after the entire response, including body has been read.
file
- the filename to store the body inopenOptions
- any options to use when opening/creating the fileBodyProcessor
public static HttpResponse.BodyProcessor<Void> asByteArrayConsumer(Consumer<byte[]> consumer)
consumer
- a Consumer to accept the response bodyBodyProcessor
public static HttpResponse.BodyProcessor<InputStream> asInputStream()
BodyProcessor
public static HttpResponse.BodyProcessor<byte[]> asByteArray()
HttpResponse.BodyProcessor
<byte[]> which returns the response
body as a byte array
.BodyProcessor
public static HttpResponse.BodyProcessor<String> asString()
Content-encoding
response header. If there
is no such header, or the character set is not supported, then
ISO_8859_1
is used.BodyProcessor
public static HttpResponse.MultiProcessor<Map<URI,Path>> multiFile(Path destination)
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();
destination
- the destination parent directory of all response
bodiespublic static HttpResponse.BodyProcessor<String> asString(Charset charset)
HttpResponse.BodyProcessor
<String
>.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.BodyProcessor
public static HttpResponse.BodyProcessor<Void> ignoreBody()
BodyProcessor
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2016, Oracle and/or its affiliates. All rights reserved.
DRAFT 9-Ubuntu+0-9b139-1