Module bus.http
Package org.miaixz.bus.http

Class Response

java.lang.Object
org.miaixz.bus.http.Response
All Implemented Interfaces:
Closeable, AutoCloseable
public final class Response extends Object implements Closeable
An HTTP response, encapsulating all information from the server, including the request, protocol, status code, headers, and response body.

Note: All properties of this class are immutable except for the response body. The response body is a one-shot resource that must be closed after reading and can only be consumed once.

Since:
Java 17+
Author:
Kimi Liu

  • Method Details

    • request

      public Request request()
      Returns the original request that initiated this response.

      Note: This request may differ from the one issued by the application if it was modified by the HTTP client (e.g., by adding a Content-Length header) or if a new request was generated due to a redirect or authentication (the URL may be different).

      Returns:
      The Request object that initiated the response.

    • protocol

      public org.miaixz.bus.core.net.Protocol protocol()
      Returns the HTTP protocol that was used.
      Returns:
      The protocol, such as HTTP/1.1 or HTTP/2.

    • code

      public int code()
      Returns the HTTP status code.
      Returns:
      The status code (e.g., 200, 404).

    • isSuccessful

      public boolean isSuccessful()
      Returns whether the request was successful (status code in the range [200..300)).
      Returns:
      true if the request was successfully received, understood, and accepted.

    • message

      public String message()
      Returns the HTTP status message.
      Returns:
      The status message (e.g., "OK", "Not Found").

    • handshake

      public Handshake handshake()
      Returns the TLS handshake information.
      Returns:
      The Handshake object, or null for non-TLS connections.

    • headers

      public List<String> headers(String name)
      Returns a list of header values for the given name.
      Parameters:
      name - The header name.
      Returns:
      A list of header values, which may be empty.

    • header

      public String header(String name)
      Returns the first header value for the given name.
      Parameters:
      name - The header name.
      Returns:
      The header value, or null if not found.

    • header

      public String header(String name, String defaultValue)
      Returns the first header value for the given name, with a default value.
      Parameters:
      name - The header name.
      defaultValue - The default value to return if the header is not found.
      Returns:
      The header value or the default value.

    • headers

      public Headers headers()
      Returns all response headers.
      Returns:
      The Headers object.

    • trailers

      public Headers trailers() throws IOException
      Returns the trailer headers of the response.

      Note: This must be called after the response body has been fully consumed, otherwise an IllegalStateException will be thrown.

      Returns:
      The trailer Headers object, which may be empty.
      Throws:
      IOException - if the trailers could not be retrieved.
      IllegalStateException - if the response body has not been fully consumed.

    • peekBody

      public ResponseBody peekBody(long byteCount) throws IOException
      Peeks at the response body content, up to a specified number of bytes.

      Returns a new ResponseBody containing up to byteCount bytes of the response body. If the body is smaller than byteCount, the entire content is returned; otherwise, it is truncated.

      Note: This method loads the requested bytes into memory, so it is recommended to set a reasonable byteCount (e.g., 1MB). Calling this after the response body has been consumed will result in an error.

      Parameters:
      byteCount - The maximum number of bytes to peek.
      Returns:
      A new ResponseBody object.
      Throws:
      IOException - if reading the response body fails.

    • body

      public ResponseBody body()
      Returns the response body.

      Note: The response body is a one-shot resource that must be closed and can only be consumed once. For responses returned by cacheResponse, networkResponse, and priorResponse, this method returns null.

      Returns:
      The ResponseBody object, which may be null.

    • newBuilder

      public Response.Builder newBuilder()
      Creates a new builder instance initialized with this response's properties.
      Returns:
      A new Response.Builder instance.

    • isRedirect

      public boolean isRedirect()
      Returns whether this response is a redirect.
      Returns:
      true if the status code indicates a redirect (300, 301, 302, 303, 307, 308).

    • networkResponse

      public Response networkResponse()
      Returns the network response.

      If the response was served directly from the network (not from cache), this returns the original response; otherwise, it returns null. The body of the returned response should not be read.

      Returns:
      The network Response object, which may be null.

    • cacheResponse

      public Response cacheResponse()
      Returns the cache response.

      If the response was served from the cache, this returns the cached response; otherwise, it returns null. For conditional GET requests, both a cache and network response may be present. The body of the returned response should not be read.

      Returns:
      The cached Response object, which may be null.

    • priorResponse

      public Response priorResponse()
      Returns the prior response.

      If this response was triggered by a redirect or authentication challenge, this returns the prior response; otherwise, it returns null. The body of the returned response should not be read (it has already been consumed).

      Returns:
      The prior Response object, which may be null.

    • challenges

      public List<Challenge> challenges()
      Returns a list of RFC 7235 authentication challenges.

      For a 401 (Unauthorized) status code, this returns "WWW-Authenticate" challenges. For a 407 (Proxy Authentication Required) status code, it returns "Proxy-Authenticate" challenges. Other status codes return an empty list.

      Returns:
      A list of authentication challenges, which may be empty.

    • cacheControl

      public CacheControl cacheControl()
      Returns the cache control directives.

      This returns a non-null CacheControl object even if the response does not have a "Cache-Control" header. Lazily initialized for performance.

      Returns:
      The CacheControl object.

    • sentRequestAtMillis

      public long sentRequestAtMillis()
      Returns the timestamp when the request was sent.
      Returns:
      The timestamp in milliseconds (from System.currentTimeMillis()).

    • receivedResponseAtMillis

      public long receivedResponseAtMillis()
      Returns the timestamp when the response headers were received.
      Returns:
      The timestamp in milliseconds (from System.currentTimeMillis()).

    • close

      public void close()
      Closes the response body.

      This is equivalent to calling body().close(). For responses without a body (like those from cacheResponse, networkResponse, or priorResponse), this will throw an exception.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IllegalStateException - if the response does not have a body.

    • toString

      public String toString()
      Returns a string representation of this response.
      Overrides:
      toString in class Object
      Returns:
      A string containing the protocol, status code, message, and URL.