T
- the response body type.@FunctionalInterface public static interface HttpResponse.BodyHandler<T>
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")));
Modifier and Type | Method | Description |
---|---|---|
HttpResponse.BodyProcessor<T> |
apply(int statusCode,
HttpHeaders responseHeaders) |
Return 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.
|
HttpResponse.BodyProcessor<T> apply(int statusCode, HttpHeaders responseHeaders)
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()
.statusCode
- the HTTP status code receivedresponseHeaders
- the response headers receivedstatic <U> HttpResponse.BodyHandler<U> discard(U value)
U
- the response body typevalue
- the value of U to return as the bodystatic HttpResponse.BodyHandler<String> asString(Charset charset)
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.charset
- the name of the charset to interpret the body as. If
null
then charset determined from Content-encoding headerstatic HttpResponse.BodyHandler<Path> asFile(Path file)
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
.
file
- the file to store the body instatic HttpResponse.BodyHandler<Path> asFileDownload(Path directory, OpenOption... openOptions)
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
.directory
- the directory to store the file inopenOptions
- open optionsstatic HttpResponse.BodyHandler<Path> asFile(Path file, OpenOption... openOptions)
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
.
file
- the filename to store the body inopenOptions
- any options to use when opening/creating the filestatic HttpResponse.BodyHandler<Void> asByteArrayConsumer(Consumer<Optional<byte[]>> consumer)
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.
consumer
- a Consumer to accept the response bodystatic HttpResponse.BodyHandler<byte[]> asByteArray()
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.
static HttpResponse.BodyHandler<String> asString()
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.
Submit a bug or feature
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 2015, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-Ubuntu+0-9b151-2