Package org.apache.juneau.rest.client

Class RestResponse

java.lang.Object
org.apache.juneau.rest.client.RestResponse
All Implemented Interfaces:
AutoCloseable, HttpMessage, HttpResponse
Direct Known Subclasses:
MockRestResponse
public class RestResponse extends Object implements HttpResponse, AutoCloseable
Represents a response from a remote REST resource.

Instances of this class are created by calling the RestRequest.run() method.

Example:

// Create a request and response, automatically closing both. try ( RestRequest req = client.get("/myResource"); RestResponse res = req.run() ) { String body = res.getContent().asString(); }

Alternatively, you can rely on RestRequest.close() to automatically close the response:

// Only specify RestRequest - it will close the response automatically. try (RestRequest req = client.get("/myResource")) { String body = req.run().getContent().asString(); }

Notes:
  • This class implements AutoCloseable and can be used in try-with-resources blocks. The close() method allows unchecked exceptions to propagate for debuggability, while catching and logging checked exceptions to follow AutoCloseable best practices.
See Also:

  • Constructor Details

  • Method Details

    • getRequest

      public RestRequest getRequest()
      Returns the request object that created this response object.
      Returns:
      The request object that created this response object.

    • consume

      public RestResponse consume()
      Consumes the response body.

      This is equivalent to closing the input stream.

      Any exceptions thrown during close are logged but not propagated.

      Returns:
      This object.

    • getStatusCode

      public int getStatusCode()
      Returns the status code of the response. Shortcut for calling getStatusLine().getStatusCode().
      Returns:
      The status code of the response.

    • getReasonPhrase

      public String getReasonPhrase()
      Returns the status line reason phrase of the response. Shortcut for calling getStatusLine().getReasonPhrase().
      Returns:
      The status line reason phrase of the response.

    • assertStatus

      public FluentResponseStatusLineAssertion<RestResponse> assertStatus()
      Provides the ability to perform fluent-style assertions on the response StatusLine object.
      Examples:

      MyBean bean = client .get(URI) .run() .assertStatus().asCode().is(200) .getContent().as(MyBean.class);

      Returns:
      A new fluent assertion object.

    • assertStatus

      public RestResponse assertStatus(int value)
      Provides the ability to perform fluent-style assertions on the response status code.
      Examples:

      MyBean bean = client .get(URI) .run() .assertStatus(200) .getContent().as(MyBean.class);

      Parameters:
      value - The value to assert.
      Returns:
      A new fluent assertion object.

    • getStringHeader

      public Optional<String> getStringHeader(String name)
      Shortcut for calling getHeader(name).asString().
      Parameters:
      name - The header name.
      Returns:
      The header value, never null

    • getCharacterEncoding

      public String getCharacterEncoding() throws RestCallException
      Shortcut for retrieving the response charset from the Content-Type header.
      Returns:
      The response charset.
      Throws:
      RestCallException - If REST call failed.

    • getContentType

      public Optional<ContentType> getContentType() throws RestCallException
      Shortcut for retrieving the response content type from the Content-Type header.

      This is equivalent to calling getHeader("Content-Type").as(ContentType.class).

      Returns:
      The response charset.
      Throws:
      RestCallException - If REST call failed.

    • assertCharset

      public FluentStringAssertion<RestResponse> assertCharset() throws RestCallException
      Provides the ability to perform fluent-style assertions on the response character encoding.
      Examples:

      // Validates that the response content charset is UTF-8. client .get(URI) .run() .assertCharset().is("utf-8");

      Returns:
      A new fluent assertion object.
      Throws:
      RestCallException - If REST call failed.

    • assertHeader

      public FluentResponseHeaderAssertion<RestResponse> assertHeader(String name)
      Provides the ability to perform fluent-style assertions on a response header.
      Examples:

      // Validates the content type header is provided. client .get(URI) .run() .assertHeader("Content-Type").exists(); // Validates the content type is JSON. client .get(URI) .run() .assertHeader("Content-Type").is("application/json"); // Validates the content type is JSON using test predicate. client .get(URI) .run() .assertHeader("Content-Type").is(x -> x.equals("application/json")); // Validates the content type is JSON by just checking for substring. client .get(URI) .run() .assertHeader("Content-Type").contains("json"); // Validates the content type is JSON using regular expression. client .get(URI) .run() .assertHeader("Content-Type").isPattern(".*json.*"); // Validates the content type is JSON using case-insensitive regular expression. client .get(URI) .run() .assertHeader("Content-Type").isPattern(".*json.*", CASE_INSENSITIVE);

      The assertion test returns the original response object allowing you to chain multiple requests like so:

      // Validates the header and converts it to a bean. MediaType mediaType = client .get(URI) .run() .assertHeader("Content-Type").isNotEmpty() .assertHeader("Content-Type").isPattern(".*json.*") .getHeader("Content-Type").as(MediaType.class);

      Parameters:
      name - The header name.
      Returns:
      A new fluent assertion object.

    • getContent

      public ResponseContent getContent()
      Returns the body of the response. This method can be called multiple times returning the same response body each time.
      Returns:
      The body of the response.

    • assertContent

      public FluentResponseBodyAssertion<RestResponse> assertContent()
      Provides the ability to perform fluent-style assertions on this response body.
      Examples:

      // Validates the response body equals the text "OK". client .get(URI) .run() .assertContent().is("OK"); // Validates the response body contains the text "OK". client .get(URI) .run() .assertContent().isContains("OK"); // Validates the response body passes a predicate test. client .get(URI) .run() .assertContent().is(x -> x.contains("OK")); // Validates the response body matches a regular expression. client .get(URI) .run() .assertContent().isPattern(".*OK.*"); // Validates the response body matches a regular expression using regex flags. client .get(URI) .run() .assertContent().isPattern(".*OK.*", MULTILINE & CASE_INSENSITIVE); // Validates the response body matches a regular expression in the form of an existing Pattern. Pattern pattern = Pattern.compile(".*OK.*"); client .get(URI) .run() .assertContent().isPattern(pattern);

      The assertion test returns the original response object allowing you to chain multiple requests like so:

      // Validates the response body matches a regular expression. MyBean bean = client .get(URI) .run() .assertContent().isPattern(".*OK.*"); .assertContent().isNotPattern(".*ERROR.*") .getContent().as(MyBean.class);

      Notes:
      • If no charset was found on the Content-Type response header, "UTF-8" is assumed.
      • When using this method, the body is automatically cached by calling the ResponseContent.cache().
      • The input stream is automatically closed after this call.
      Returns:
      A new fluent assertion object.

    • assertContent

      public RestResponse assertContent(String value)
      Provides the ability to perform fluent-style assertions on this response body.

      A shortcut for calling assertContent().is(value).

      Examples:

      // Validates the response body equals the text "OK". client .get(URI) .run() .assertContent("OK");

      Parameters:
      value - The value to assert.
      Returns:
      This object.

    • assertContentMatches

      public RestResponse assertContentMatches(String value)
      Provides the ability to perform fluent-style assertions on this response body.

      A shortcut for calling assertContent().asString().isMatches(value).

      Parameters:
      value - The value to assert.
      Returns:
      This object.
      See Also:

    • cacheContent

      public RestResponse cacheContent()
      Caches the response body so that it can be read as a stream multiple times. This is equivalent to calling the following:

      getContent().cache();

      Returns:
      The body of the response.

    • log

      public RestResponse log(Level level, Throwable t, String msg, Object... args)
      Logs a message.
      Parameters:
      level - The log level.
      t - The throwable cause.
      msg - The message with MessageFormat-style arguments.
      args - The arguments.
      Returns:
      This object.

    • log

      public RestResponse log(Level level, String msg, Object... args)
      Logs a message.
      Parameters:
      level - The log level.
      msg - The message with MessageFormat-style arguments.
      args - The arguments.
      Returns:
      This object.

    • getStatusLine

      public ResponseStatusLine getStatusLine()
      Obtains the status line of this response. The status line can be set using one of the setStatusLine methods, or it can be initialized in a constructor.
      Specified by:
      getStatusLine in interface HttpResponse
      Returns:
      The status line, or null if not yet set.

    • setStatusLine

      public void setStatusLine(StatusLine statusline)
      Sets the status line of this response.
      Specified by:
      setStatusLine in interface HttpResponse
      Parameters:
      statusline - The status line of this response

    • setStatusLine

      public void setStatusLine(ProtocolVersion ver, int code)
      Sets the status line of this response.

      The reason phrase will be determined based on the current locale.

      Specified by:
      setStatusLine in interface HttpResponse
      Parameters:
      ver - The HTTP version.
      code - The status code.

    • setStatusLine

      public void setStatusLine(ProtocolVersion ver, int code, String reason)
      Sets the status line of this response with a reason phrase.
      Specified by:
      setStatusLine in interface HttpResponse
      Parameters:
      ver - The HTTP version.
      code - The status code.
      reason - The reason phrase, or null to omit.

    • setStatusCode

      public void setStatusCode(int code)
      Updates the status line of this response with a new status code.
      Specified by:
      setStatusCode in interface HttpResponse
      Parameters:
      code - The HTTP status code.
      Throws:
      IllegalStateException - If the status line has not be set.

    • setReasonPhrase

      public void setReasonPhrase(String reason)
      Updates the status line of this response with a new reason phrase.
      Specified by:
      setReasonPhrase in interface HttpResponse
      Parameters:
      reason - The new reason phrase as a single-line string, or null to unset the reason phrase.
      Throws:
      IllegalStateException - If the status line has not be set.

    • getEntity

      public ResponseContent getEntity()
      Obtains the message entity of this response.

      The entity is provided by calling setEntity.

      Notes:
      • Unlike the HttpResponse.getEntity() method, this method never returns a null response. Instead, getContent().isPresent() can be used to determine whether the response has a body.
      Specified by:
      getEntity in interface HttpResponse
      Returns:
      The response entity. Never null.

    • setEntity

      public void setEntity(HttpEntity entity)
      Associates a response entity with this response.
      Notes:
      • If an entity has already been set for this response and it depends on an input stream (HttpEntity.isStreaming() returns true), it must be fully consumed in order to ensure release of resources.
      Specified by:
      setEntity in interface HttpResponse
      Parameters:
      entity - The entity to associate with this response, or null to unset.

    • getLocale

      public Locale getLocale()
      Obtains the locale of this response. The locale is used to determine the reason phrase for the status code. It can be changed using setLocale(Locale).
      Specified by:
      getLocale in interface HttpResponse
      Returns:
      The locale of this response, never null.

    • setLocale

      public void setLocale(Locale loc)
      Changes the locale of this response.
      Specified by:
      setLocale in interface HttpResponse
      Parameters:
      loc - The new locale.

    • getProtocolVersion

      public ProtocolVersion getProtocolVersion()
      Returns the protocol version this message is compatible with.
      Specified by:
      getProtocolVersion in interface HttpMessage
      Returns:
      The protocol version this message is compatible with.

    • containsHeader

      public boolean containsHeader(String name)
      Checks if a certain header is present in this message.

      Header values are ignored.

      Specified by:
      containsHeader in interface HttpMessage
      Parameters:
      name - The header name to check for.
      Returns:
      true if at least one header with this name is present.

    • getHeaders

      public ResponseHeader[] getHeaders(String name)
      Returns all the headers with a specified name of this message. Header values are ignored.
      Headers are ordered in the sequence they were sent over a connection.
      Specified by:
      getHeaders in interface HttpMessage
      Parameters:
      name - The name of the headers to return.
      Returns:
      All the headers with a specified name of this message.

    • getFirstHeader

      public ResponseHeader getFirstHeader(String name)
      Returns the first header with a specified name of this message.

      If there is more than one matching header in the message the first element of getHeaders(String) is returned.

      This method always returns a value so that you can perform assertions on the result.

      Specified by:
      getFirstHeader in interface HttpMessage
      Parameters:
      name - The name of the header to return.
      Returns:
      The header, never null.

    • getLastHeader

      public ResponseHeader getLastHeader(String name)
      Returns the last header with a specified name of this message.

      If there is more than one matching header in the message the last element of getHeaders(String) is returned.

      This method always returns a value so that you can perform assertions on the result.

      Specified by:
      getLastHeader in interface HttpMessage
      Parameters:
      name - The name of the header to return.
      Returns:
      The header, never null.

    • getHeader

      public ResponseHeader getHeader(String name)
      Returns the response header with the specified name.

      If more that one header with the given name exists the values will be combined with ", " as per RFC 2616 Section 4.2.

      Parameters:
      name - The name of the header to return.
      Returns:
      The header, never null.

    • getAllHeaders

      public ResponseHeader[] getAllHeaders()
      Returns all the headers of this message. Headers are ordered in the sequence they were sent over a connection.
      Specified by:
      getAllHeaders in interface HttpMessage
      Returns:
      All the headers of this message.

    • addHeader

      public void addHeader(Header header)
      Adds a header to this message. The header will be appended to the end of the list.
      Specified by:
      addHeader in interface HttpMessage
      Parameters:
      header - The header to append.

    • addHeader

      public void addHeader(String name, String value)
      Adds a header to this message. The header will be appended to the end of the list.
      Specified by:
      addHeader in interface HttpMessage
      Parameters:
      name - The name of the header.
      value - The value of the header.

    • setHeader

      public void setHeader(Header header)
      Overwrites the first header with the same name. The new header will be appended to the end of the list, if no header with the given name can be found.
      Specified by:
      setHeader in interface HttpMessage
      Parameters:
      header - The header to set.

    • setHeader

      public void setHeader(String name, String value)
      Overwrites the first header with the same name. The new header will be appended to the end of the list, if no header with the given name can be found.
      Specified by:
      setHeader in interface HttpMessage
      Parameters:
      name - The name of the header.
      value - The value of the header.

    • setHeaders

      public void setHeaders(Header[] headers)
      Overwrites all the headers in the message.
      Specified by:
      setHeaders in interface HttpMessage
      Parameters:
      headers - The array of headers to set.

    • removeHeader

      public void removeHeader(Header header)
      Removes a header from this message.
      Specified by:
      removeHeader in interface HttpMessage
      Parameters:
      header - The header to remove.

    • removeHeaders

      public void removeHeaders(String name)
      Removes all headers with a certain name from this message.
      Specified by:
      removeHeaders in interface HttpMessage
      Parameters:
      name - The name of the headers to remove.

    • headerIterator

      public HeaderIterator headerIterator()
      Returns an iterator of all the headers.
      Specified by:
      headerIterator in interface HttpMessage
      Returns:
      Iterator that returns Header objects in the sequence they are sent over a connection.

    • headerIterator

      public HeaderIterator headerIterator(String name)
      Returns an iterator of the headers with a given name.
      Specified by:
      headerIterator in interface HttpMessage
      Parameters:
      name - The name of the headers over which to iterate, or null for all headers.
      Returns:
      Iterator that returns Header objects with the argument name in the sequence they are sent over a connection.

    • getParams

      @Deprecated public HttpParams getParams()
      Deprecated.
      Use configuration classes provided org.apache.http.config and org.apache.http.client.config.
      Returns the parameters effective for this message as set by setParams(HttpParams).
      Specified by:
      getParams in interface HttpMessage
      Returns:
      The parameters effective for this message as set by setParams(HttpParams).

    • setParams

      @Deprecated public void setParams(HttpParams params)
      Deprecated.
      Use configuration classes provided org.apache.http.config and org.apache.http.client.config.
      Provides parameters to be used for the processing of this message.
      Specified by:
      setParams in interface HttpMessage
      Parameters:
      params - The parameters.

    • close

      public void close()
      Closes this response.

      This method is idempotent and can be called multiple times without side effects.

      Implementation Notes:

      This implementation represents a compromise between strict AutoCloseable compliance and debuggability:

      • Unchecked exceptions (RuntimeException and Error) from interceptors are allowed to propagate. This ensures programming errors and serious issues are visible during development and testing.
      • Checked exceptions (including RestCallException) are caught and logged but not thrown. This follows AutoCloseable best practices and prevents close exceptions from interfering with try-with-resources cleanup or masking the original exception.
      Specified by:
      close in interface AutoCloseable

    • getPartParserSession

      protected HttpPartParserSession getPartParserSession(HttpPartParser parser)
      Creates a session of the specified part parser.
      Parameters:
      parser - The parser to create a session for.
      Returns:
      A session of the specified parser.

    • getPartParserSession

      protected HttpPartParserSession getPartParserSession()
      Creates a session of the client-default parat parser.
      Returns:
      A session of the specified parser.