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:

    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 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

      • 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

      • 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