Package org.apache.juneau.rest.client

Class RestRequest

java.lang.Object
org.apache.juneau.ContextSession
org.apache.juneau.BeanSession
org.apache.juneau.rest.client.RestRequest
All Implemented Interfaces:
AutoCloseable, Configurable, HttpUriRequest, HttpMessage, HttpRequest
Direct Known Subclasses:
MockRestRequest
public class RestRequest extends BeanSession implements HttpUriRequest, Configurable, AutoCloseable
Represents a request to a remote REST resource.

Instances of this class are created by the various creator methods on the RestClient class.

Example:

// Create a request and automatically close it. try (RestRequest req = client.get("/myResource")) { req .queryData("foo", "bar") .run() .assertStatus().asCode().is(200); }

The close() method will automatically close any associated RestResponse if one was created via run().

Notes:
  • This class is not thread safe.
  • 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

    • RestRequest

      protected RestRequest(RestClient client, URI uri, String method, boolean hasBody) throws RestCallException
      Constructs a REST call with the specified method name.
      Parameters:
      client - The client that created this request.
      Cannot be null.
      uri - The target URI.
      Cannot be null.
      method - The HTTP method name (uppercase).
      Cannot be null.
      hasBody - Whether this method has a body.
      Throws:
      RestCallException - If an exception or non-200 response code occurred during the connection attempt.

  • Method Details

    • abort

      public void abort() throws UnsupportedOperationException
      Aborts this http request. Any active execution of this method should return immediately. If the request has not started, it will abort after the next execution.
      Aborting this request will cause all subsequent executions with this request to fail.
      Specified by:
      abort in interface HttpUriRequest
      Throws:
      UnsupportedOperationException

    • accept

      public RestRequest accept(String value) throws RestCallException
      Sets the value for the Accept request header.

      This overrides the media type specified on the parser, but is overridden by calling header("Accept", value);

      Parameters:
      value - The new header value.
      Can be null (header will not be set).
      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • acceptCharset

      public RestRequest acceptCharset(String value) throws RestCallException
      Sets the value for the Accept-Charset request header.

      This is a shortcut for calling header("Accept-Charset", value);

      Parameters:
      value - The new header value.
      Can be null (header will not be set).
      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • addHeader

      public void addHeader(Header header)
      Adds a header to this message. The header will be appended to the end of the list.
      Notes:
      • header(Header) is an equivalent method and the preferred method for fluent-style coding.
      Specified by:
      addHeader in interface HttpMessage
      Parameters:
      header - The header to append.
      Can be null (ignored).

    • 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.
      Notes:
      Specified by:
      addHeader in interface HttpMessage
      Parameters:
      name - The name of the header.
      Cannot be null or empty (header will not be created).
      value - The value of the header.
      Can be null.

    • cancellable

      public RestRequest cancellable(Cancellable cancellable)
      Sets Cancellable for the ongoing operation.
      Parameters:
      cancellable - The cancellable object.
      Can be null (no cancellation will be available).
      Returns:
      This object.

    • close

      public void close()
      Closes this request and its associated response (if one was created).

      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 the response close 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

    • complete

      public RestResponse complete() throws RestCallException
      Same as run() but immediately calls RestResponse.consume() to clean up the response.

      Use this method if you're only interested in the status line of the response and not the response entity. Attempts to call any of the methods on the response object that retrieve the body (e.g. ResponseContent.asReader() will cause a RestCallException to be thrown.

      Notes:
      Example:

      // Get the response code. // No need to call close() on the RestResponse object. int rc = client.get(URI).complete().getResponseCode();

      Returns:
      The response object.
      Throws:
      RestCallException - If an exception or non-200 response code occurred during the connection attempt.

    • completed

      @Deprecated public RestRequest completed()
      Deprecated.
      Used in combination with cancellable(Cancellable).
      Returns:
      This object.

    • completeFuture

      public Future<RestResponse> completeFuture() throws RestCallException
      Same as complete() but allows you to run the call asynchronously.
      Example:

      Future<RestResponse> future = client.get(URI).completeFuture(); // Do some other stuff int rc = future.get().getResponseStatus();

      Notes:
      Returns:
      The HTTP status code.
      Throws:
      RestCallException - If the executor service was not defined.

    • config

      public RestRequest config(RequestConfig value)
      Sets the actual request configuration.
      Parameters:
      value - The new value.
      Can be null (default configuration will be used).
      Returns:
      This object.

    • 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.
      Cannot be null.
      Returns:
      true if at least one header with this name is present.

    • content

      public RestRequest content(Object value)
      Sets the body of this request.
      Parameters:
      value - The input to be sent to the REST resource (only valid for PUT/POST/PATCH) requests.
      Can be of the following types:
      • Reader - Raw contents of Reader will be serialized to remote resource.
      • InputStream - Raw contents of InputStream will be serialized to remote resource.
      • HttpResource - Raw contents will be serialized to remote resource. Additional headers and media type will be set on request.
      • HttpEntity/BasicHttpEntity - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
      • Object - POJO to be converted to text using the Serializer registered with the RestClient.
      • PartList - Converted to a URL-encoded FORM post.
      • A Supplier of anything on this list.

      Can be null (no body will be sent).
      Returns:
      This object.

    • content

      public RestRequest content(Object input, HttpPartSchema schema)
      Sets the body of this request.
      Parameters:
      input - The input to be sent to the REST resource (only valid for PUT/POST/PATCH) requests.
      Can be of the following types:
      • Reader - Raw contents of Reader will be serialized to remote resource.
      • InputStream - Raw contents of InputStream will be serialized to remote resource.
      • HttpResource - Raw contents will be serialized to remote resource. Additional headers and media type will be set on request.
      • HttpEntity/BasicHttpEntity - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
      • Object - POJO to be converted to text using the Serializer registered with the RestClient.
      • PartList - Converted to a URL-encoded FORM post.
      • A Supplier of anything on this list.
      schema - The schema object that defines the format of the output.
      Returns:
      This object.

    • contentString

      public RestRequest contentString(Object input) throws RestCallException
      Sets the body of this request as straight text bypassing the serializer.

      client .put("/foo") .content(new StringReader("foo")) .contentType("text/foo") .run(); client .put("/foo") .bodyString("foo") .run();

      Note that this is different than the following which will serialize foo as a JSON string "foo".

      client .put("/foo") .json() .content("foo") .run();

      Parameters:
      input - The input to be sent to the REST resource (only valid for PUT/POST/PATCH) requests.
      Returns:
      This object.
      Throws:
      RestCallException - If a retry was attempted, but the entity was not repeatable.

    • contentType

      public RestRequest contentType(String value) throws RestCallException
      Sets the value for the Content-Type request header.

      This overrides the media type specified on the serializer, but is overridden by calling header("Content-Type", value);

      Parameters:
      value - The new header value.
      Can be null (header will not be set).
      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • context

      public RestRequest context(HttpContext context)
      Override the context to use for the execution.
      Parameters:
      context - The context to use for the execution, or null to use the default context.
      Returns:
      This object.

    • debug

      public RestRequest debug() throws RestCallException
      Sets Debug: value header on this request.
      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • errorCodes

      public RestRequest errorCodes(Predicate<Integer> value)
      Allows you to override what status codes are considered error codes that would result in a RestCallException.

      The default error code predicate is: x -> x >= 400.

      Parameters:
      value - The new predicate for calculating error codes.
      Cannot be null.
      Returns:
      This object.

    • formData

      public RestRequest formData(NameValuePair... parts)
      Appends multiple form-data parameters to the request.
      Example:

      // Appends two form-data parameters to the request. client .get(URI) .formData( BasicStringPart.of("foo", "bar"), BasicBooleanPart.of("baz", true) ) .run();

      Parameters:
      parts - The parameters to set. null values are ignored.
      Returns:
      This object.

    • formData

      public RestRequest formData(String name, Object value)
      Adds a form-data parameter to the request body.
      Example:

      // Adds form data parameter "foo=bar". client .formPost(URI) .formData("foo", "bar") .run();

      Parameters:
      name - The parameter name.
      Cannot be null or empty (parameter will not be created).
      value - The parameter value.
      Non-string values are converted to strings using the HttpPartSerializer defined on the client.
      Can be null.
      Returns:
      This object.

    • formDataBean

      public RestRequest formDataBean(Object value)
      Appends multiple form-data parameters to the request from properties defined on a Java bean.
      Example:

      public class MyFormData { public String getFooBar() { return "baz"; } public Integer getQux() { return 123; } } // Appends form data "fooBar=baz&qux=123". client .get(URI) .formDataBean(new MyFormData()) .run();

      Parameters:
      value - The bean containing the properties to set as form-data parameter values.
      Cannot be null.
      Returns:
      This object.

    • formDataCustom

      public RestRequest formDataCustom(Object value)
      Adds form-data parameters as the entire body of the request.
      Example:

      // Creates form data "foo=bar&baz=qux". client .formPost(URI) .formDataCustom("foo=bar&baz=qux") .run(); // Creates form data "foo=bar&baz=qux" using StringEntity. client .formPost(URI) .formDataCustom(new StringEntity("foo=bar&baz=qux","application/x-www-form-urlencoded")) .run(); // Creates form data "foo=bar&baz=qux" using StringEntity and body(). client .formPost(URI) .content(new StringEntity("foo=bar&baz=qux","application/x-www-form-urlencoded")) .run();

      Parameters:
      value - The parameter value.
      Can be any of the following types:
      • CharSequence
      • Reader - Raw contents of Reader will be serialized to remote resource.
      • InputStream - Raw contents of InputStream will be serialized to remote resource.
      • HttpResource - Raw contents will be serialized to remote resource. Additional headers and media type will be set on request.
      • HttpEntity/BasicHttpEntity - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
      • Object - POJO to be converted to text using the Serializer registered with the RestClient.
      • PartList - Converted to a URL-encoded FORM post.

      Can be null (no body will be sent).
      Returns:
      This object.

    • formDataPairs

      public RestRequest formDataPairs(String... pairs) throws RestCallException
      Adds form-data parameters to the request body using free-form key/value pairs.
      Example:

      // Creates form data "key1=val1&key2=val2". client .formPost(URI) .formDataPairs("key1","val1","key2","val2") .run();

      Parameters:
      pairs - The form-data key/value pairs.
      • Values can be any POJO.
      • Values converted to a string using the configured part serializer.

      Cannot be null.
      Must have an even number of elements (key/value pairs).
      Null keys are ignored (parameter will not be created).
      Null values are allowed.
      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • getAllHeaders

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

    • getConfig

      public RequestConfig getConfig()
      Returns the actual request configuration.
      Specified by:
      getConfig in interface Configurable
      Returns:
      The actual request configuration.

    • getFirstHeader

      public Header getFirstHeader(String name)
      Returns the first header with a specified name of this message. Header values are ignored.
      If there is more than one matching header in the message the first element of getHeaders(String) is returned.
      If there is no matching header in the message null is returned.
      Specified by:
      getFirstHeader in interface HttpMessage
      Parameters:
      name - The name of the header to return.
      Cannot be null.
      Returns:
      The first header whose name property equals name or null if no such header could be found.

    • getFormData

      public PartList getFormData()
      Returns the form data for the request.
      Returns:
      An immutable list of form data to send on the request.

    • getHeaders

      public HeaderList getHeaders()
      Returns the header data for the request.
      Returns:
      An immutable list of headers to send on the request.

    • getHeaders

      public Header[] 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 will be sent over a connection.
      Specified by:
      getHeaders in interface HttpMessage
      Parameters:
      name - The name of the headers to return.
      Cannot be null.
      Returns:
      The headers whose name property equals name.

    • getHttpEntity

      public HttpEntity getHttpEntity()
      Returns the body of this request.
      Returns:
      The body of this request, or null if it doesn't have a body.

    • getLastHeader

      public Header getLastHeader(String name)
      Returns the last header with a specified name of this message. Header values are ignored.
      If there is more than one matching header in the message the last element of getHeaders(String) is returned.
      If there is no matching header in the message null is returned.
      Specified by:
      getLastHeader in interface HttpMessage
      Parameters:
      name - The name of the header to return.
      Cannot be null.
      Returns:
      The last header whose name property equals name or null if no such header could be found.

    • getMethod

      public String getMethod()
      Returns the HTTP method this request uses, such as GET, PUT, POST, or other.
      Specified by:
      getMethod in interface HttpUriRequest
      Returns:
      The HTTP method this request uses, such as GET, PUT, POST, or other.

    • getParams

      @Deprecated public HttpParams getParams()
      Deprecated.
      Use constructor parameters of configuration API provided by HttpClient.
      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).

    • getPathData

      public PartList getPathData()
      Returns the path data for the request.
      Returns:
      An immutable list of path data to send on the request.

    • getProtocolVersion

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

    • getQueryData

      public PartList getQueryData()
      Returns the query data for the request.
      Returns:
      An immutable list of query data to send on the request.

    • getRequestLine

      public RequestLine getRequestLine()
      Returns the request line of this request.
      Specified by:
      getRequestLine in interface HttpRequest
      Returns:
      The request line.

    • getResponse

      public <T> T getResponse(Class<T> type) throws RestCallException
      A shortcut for calling run().getContent().as(type).
      Type Parameters:
      T - The object type to create.
      Parameters:
      type - The object type to create.
      Cannot be null.
      Returns:
      The response content as a simple string.
      Throws:
      RestCallException - If an exception or non-200 response code occurred during the connection attempt.
      See Also:

    • getResponse

      public <T> T getResponse(Type type, Type... args) throws RestCallException
      A shortcut for calling run().getContent().as(type,args).
      Type Parameters:
      T - The object type to create.
      Parameters:
      type - The object type to create.
      Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
      Cannot be null.
      args - The type arguments of the class if it's a collection or map.
      Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
      Ignored if the main type is not a map or collection.
      Can contain null values (ignored).
      Returns:
      The response content as a simple string.
      Throws:
      RestCallException - If an exception or non-200 response code occurred during the connection attempt.
      See Also:

    • getResponseAsString

      public String getResponseAsString() throws RestCallException
      A shortcut for calling run().getContent().asString().
      Returns:
      The response content as a simple string.
      Throws:
      RestCallException - If an exception or non-200 response code occurred during the connection attempt.

    • getURI

      public URI getURI()
      Returns the original request URI.
      Notes:
      • URI remains unchanged in the course of request execution and is not updated if the request is redirected to another location.
      Specified by:
      getURI in interface HttpUriRequest
      Returns:
      The original request URI.

    • hasHttpEntity

      public boolean hasHttpEntity()
      Returns true if this request has a body.
      Returns:
      true if this request has a body.

    • header

      public RestRequest header(Header part)
      Appends a header to the request.
      Example:

      // Adds header "Foo: bar". client .get(URI) .header(Accept.TEXT_XML) .run();

      Parameters:
      part - The parameter to set. null values are ignored.
      Returns:
      This object.

    • header

      public RestRequest header(String name, Object value)
      Appends a header to the request.
      Example:

      // Adds header "Foo: bar". client .get(URI) .header("Foo", "bar") .run();

      Parameters:
      name - The parameter name.
      value - The parameter value.
      Non-string values are converted to strings using the HttpPartSerializer defined on the client.
      Returns:
      This object.

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

    • headerPairs

      public RestRequest headerPairs(String... pairs)
      Appends multiple headers to the request using freeform key/value pairs.
      Example:

      // Adds headers "Foo: bar" and "Baz: qux". client .get(URI) .headerPairs("Foo","bar","Baz","qux") .run();

      Parameters:
      pairs - The header key/value pairs.
      Cannot be null.
      Must have an even number of elements (key/value pairs).
      Null keys are ignored (header will not be created).
      Null values are allowed.
      Returns:
      This object.

    • headers

      public RestRequest headers(Header... parts)
      Appends multiple headers to the request.
      Example:

      // Appends two headers to the request. client .get(URI) .headers( BasicHeader.of("Foo", "bar"), Accept.TEXT_XML ) .run();

      Parameters:
      parts - The parameters to set. null values are ignored.
      Returns:
      This object.

    • headersBean

      public RestRequest headersBean(Object value)
      Appends multiple headers to the request from properties defined on a Java bean.

      Uses PropertyNamerDUCS for resolving the header names from property names.

      Example:

      @Bean public class MyHeaders { public String getFooBar() { return "baz"; } public Integer getQux() { return 123; } } // Appends headers "Foo-Bar: baz" and "Qux: 123". client .get(URI) .headersBean(new MyHeaders()) .run();

      Parameters:
      value - The bean containing the properties to set as header values.
      Cannot be null.
      Returns:
      This object.

    • html

      public RestRequest html()
      Convenience method for specifying HTML as the marshalling transmission media type for this request only.

      POJOs are converted to HTML without any sort of doc wrappers.

      HtmlSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      HtmlParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "text/html" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "text/html" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(HtmlSerializer.class).parser(HtmlParser.class).

      Returns:
      This object.

    • htmlDoc

      public RestRequest htmlDoc()
      Convenience method for specifying HTML DOC as the marshalling transmission media type for this request only.

      POJOs are converted to fully renderable HTML pages.

      HtmlDocSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      HtmlParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "text/html" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "text/html" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(HtmlDocSerializer.class).parser(HtmlParser.class).

      Returns:
      This object.

    • htmlStrippedDoc

      public RestRequest htmlStrippedDoc()
      Convenience method for specifying Stripped HTML DOC as the marshalling transmission media type for this request only.

      Same as htmlDoc() but without the header and body tags and page title and description.

      HtmlStrippedDocSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      HtmlParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "text/html+stripped" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "text/html+stripped" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(HtmlStrippedDocSerializer.class).parser(HtmlParser.class).

      Returns:
      This object.

    • ignoreErrors

      public RestRequest ignoreErrors()
      Prevent RestCallExceptions from being thrown when HTTP status 400+ is encountered.

      This overrides the ignoreErrors property on the client.

      Returns:
      This object.

    • interceptors

      public RestRequest interceptors(RestCallInterceptor... interceptors) throws RestCallException
      Add one or more interceptors for this call only.
      Parameters:
      interceptors - The interceptors to add to this call.
      Cannot contain null values.
      Returns:
      This object.
      Throws:
      RestCallException - If init method on interceptor threw an exception.

    • isAborted

      public boolean isAborted()
      Specified by:
      isAborted in interface HttpUriRequest

    • isDebug

      public boolean isDebug()
      Returns true if debug mode is currently enabled.
      Overrides:
      isDebug in class ContextSession
      Returns:
      true if debug mode is enabled.
      See Also:

    • json

      public RestRequest json()
      Convenience method for specifying JSON as the marshalling transmission media type for this request only.

      JsonSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      JsonParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "application/json" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "application/json" unless overridden header(String,Object) or contentType(String).

      Identical to calling serializer(JsonSerializer.class).parser(JsonParser.class).

      Returns:
      This object.

    • json5

      public RestRequest json5()
      Convenience method for specifying Simplified JSON as the marshalling transmission media type for this request only.

      Simplified JSON is typically useful for automated tests because you can do simple string comparison of results without having to escape lots of quotes.

      Json5Serializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      Json5Parser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "application/json" unless overridden by header(String,Object) or accept(String), or per-request via header(String,Object) or accept(String).

      Content-Type request header will be set to "application/json+simple" unless overridden by header(String,Object) or contentType(String), or per-request via header(String,Object) or contentType(String).

      Can be combined with other marshaller setters such as xml() to provide support for multiple languages.

      • When multiple languages are supported, the Accept and Content-Type headers control which marshallers are used, or uses the last-enabled language if the headers are not set.

      Identical to calling serializer(Json5Serializer.class).parser(Json5Parser.class).

      Returns:
      This object.

    • log

      public RestRequest log(Level level, String msg, Object... args)
      Logs a message.
      Parameters:
      level - The log level.
      Cannot be null.
      msg - The message with MessageFormat-style arguments.
      Cannot be null.
      args - The arguments.
      Can contain null values.
      Returns:
      This object.

    • log

      public RestRequest log(Level level, Throwable t, String msg, Object... args)
      Logs a message.
      Parameters:
      level - The log level.
      Cannot be null.
      t - The throwable cause.
      Can be null.
      msg - The message with MessageFormat-style arguments.
      Cannot be null.
      args - The arguments.
      Can contain null values.
      Returns:
      This object.

    • mediaType

      public RestRequest mediaType(String value) throws RestCallException
      Shortcut for setting the Accept and Content-Type headers on a request.
      Parameters:
      value - The new header values.
      Can be null (headers will not be set).
      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • msgPack

      public RestRequest msgPack()
      Convenience method for specifying MessagePack as the marshalling transmission media type for this request only.

      MessagePack is a binary equivalent to JSON that takes up considerably less space than JSON.

      MsgPackSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      MsgPackParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "octal/msgpack" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "octal/msgpack" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(MsgPackSerializer.class).parser(MsgPackParser.class).

      Returns:
      This object.

    • noTrace

      public RestRequest noTrace() throws RestCallException
      When called, No-Trace: true is added to requests.

      This gives the opportunity for the servlet to not log errors on invalid requests. This is useful for testing purposes when you don't want your log file to show lots of errors that are simply the results of testing.

      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • openApi

      public RestRequest openApi()
      Convenience method for specifying OpenAPI as the marshalling transmission media type for this request only.

      OpenAPI is a language that allows serialization to formats that use HttpPartSchema objects to describe their structure.

      OpenApiSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      OpenApiParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "text/openapi" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "text/openapi" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(OpenApiSerializer.class).parser(OpenApiParser.class).

      Returns:
      This object.

    • parser

      public RestRequest parser(Class<? extends Parser> parser)
      Specifies the parser to use on the response body.

      Overrides the parsers specified on the RestClient.

      The parser can be configured using any of the parser property setters (e.g. RestClient.Builder.strict()) or bean context property setters (e.g. RestClient.Builder.swaps(Class...)) defined on this builder class.

      If the Accept header is not set on the request, it will be set to the media type of this parser.

      Parameters:
      parser - The parser used to parse POJOs from the body of the HTTP response.
      Cannot be null.
      Returns:
      This object.

    • parser

      public RestRequest parser(Parser parser)
      Specifies the parser to use on the response body.

      Overrides the parsers specified on the RestClient.

      The parser is not modified by any of the parser property setters (e.g. RestClient.Builder.strict()) or bean context property setters (e.g. RestClient.Builder.swaps(Class...)) defined on this builder class.

      If the Accept header is not set on the request, it will be set to the media type of this parser.

      Parameters:
      parser - The parser used to parse POJOs from the body of the HTTP response.
      Cannot be null.
      Returns:
      This object.

    • pathData

      public RestRequest pathData(NameValuePair... parts)
      Sets or replaces multiple path parameters on the request.
      Example:

      // Appends two path parameters to the request. client .get(URI) .pathData( BasicStringPart.of("foo", "bar"), BasicBooleanPart.of("baz", true) ) .run();

      Parameters:
      parts - The parameters to set. null values are ignored.
      Returns:
      This object.

    • pathData

      public RestRequest pathData(String name, Object value)
      Sets or replaces a path parameter of the form "{name}" in the URI.
      Example:

      // Sets path to "/bar". client .get("/{foo}") .pathData("foo", "bar") .run();

      Parameters:
      name - The parameter name.
      Cannot be null or empty (parameter will not be created).
      value - The parameter value.
      Non-string values are converted to strings using the HttpPartSerializer defined on the client.
      Can be null.
      Returns:
      This object.

    • pathDataBean

      public RestRequest pathDataBean(Object value)
      Sets multiple path parameters to the request from properties defined on a Java bean.
      Example:

      public class MyPathVars { public String getFooBar() { return "baz"; } public Integer getQux() { return 123; } } // Given path "/{fooBar}/{qux}/", gets converted to "/baz/123/". client .get(URI) .pathDataBean(new MyPathVars()) .run();

      Parameters:
      value - The bean containing the properties to set as path parameter values.
      Cannot be null.
      Returns:
      This object.

    • pathDataPairs

      public RestRequest pathDataPairs(String... pairs)
      Replaces path parameters of the form "{name}" in the URI using free-form key/value pairs.
      Example:

      // Sets path to "/baz/qux". client .get("/{foo}/{bar}") .pathDataPairs( "foo","baz", "bar","qux" ) .run();

      Parameters:
      pairs - The path key/value pairs.
      • Values can be any POJO.
      • Values converted to a string using the configured part serializer.

      Cannot be null.
      Must have an even number of elements (key/value pairs).
      Null keys are ignored (parameter will not be created).
      Null values are allowed.
      Returns:
      This object.

    • plainText

      public RestRequest plainText()
      Convenience method for specifying Plain Text as the marshalling transmission media type for this request only.

      Plain text marshalling typically only works on simple POJOs that can be converted to and from strings using swaps, swap methods, etc...

      PlainTextSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      PlainTextParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "text/plain" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "text/plain" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(PlainTextSerializer.class).parser(PlainTextParser.class).

      Returns:
      This object.

    • protocolVersion

      public RestRequest protocolVersion(ProtocolVersion version)
      Sets the protocol version for this request.
      Parameters:
      version - The protocol version for this request.
      Can be null (default protocol version will be used).
      Returns:
      This object.

    • queryCustom

      public RestRequest queryCustom(Object value)
      Adds a free-form custom query.
      Example:

      // Adds query parameter "foo=bar&baz=qux". client .get(URI) .queryCustom("foo=bar&baz=qux") .run();

      Parameters:
      value - The parameter value.
      Can be any of the following types:
      • CharSequence
      • Reader - Raw contents of Reader will be serialized to remote resource.
      • InputStream - Raw contents of InputStream will be serialized to remote resource.
      • PartList - Converted to a URL-encoded query.

      Can be null (no custom query will be set).
      Returns:
      This object.

    • queryData

      public RestRequest queryData(NameValuePair... parts)
      Appends multiple query parameters to the request.
      Example:

      // Appends two query parameters to the request. client .get(URI) .queryData( BasicStringPart.of("foo", "bar"), BasicBooleanPart.of("baz", true) ) .run();

      Parameters:
      parts - The parameters to set. null values are ignored.
      Returns:
      This object.

    • queryData

      public RestRequest queryData(String name, Object value)
      Appends a query parameter to the URI of the request.
      Example:

      // Adds query parameter "foo=bar". client .get(URI) .queryData("foo", "bar") .run();

      Parameters:
      name - The parameter name.
      Cannot be null or empty (parameter will not be created).
      value - The parameter value.
      Non-string values are converted to strings using the HttpPartSerializer defined on the client.
      Can be null.
      Returns:
      This object.

    • queryDataBean

      public RestRequest queryDataBean(Object value)
      Appends multiple query parameters to the request from properties defined on a Java bean.
      Example:

      public class MyQuery { public String getFooBar() { return "baz"; } public Integer getQux() { return 123; } } // Appends query "fooBar=baz&qux=123". client .get(URI) .queryDataBean(new MyQuery()) .run();

      Parameters:
      value - The bean containing the properties to set as query parameter values.
      Cannot be null.
      Returns:
      This object.

    • queryDataPairs

      public RestRequest queryDataPairs(String... pairs) throws RestCallException
      Adds query parameters to the URI query using free-form key/value pairs..
      Example:

      // Adds query parameters "foo=bar&baz=qux". client .get(URI) .queryDataPairs("foo","bar","baz","qux") .run();

      Parameters:
      pairs - The query key/value pairs.
      • Values can be any POJO.
      • Values converted to a string using the configured part serializer.

      Cannot be null.
      Must have an even number of elements (key/value pairs).
      Null keys are ignored (parameter will not be created).
      Null values are allowed.
      Returns:
      This object.
      Throws:
      RestCallException - Invalid input.

    • removeHeader

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

    • 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.
      Cannot be null.

    • rethrow

      public RestRequest rethrow(Class<?>... values)
      Rethrow any of the specified exception types if a matching Exception-Name header is found.

      Rethrown exceptions will be set on the caused-by exception of RestCallException when thrown from the run() method.

      Can be called multiple times to append multiple rethrows.

      Parameters:
      values - The classes to rethrow.
      Cannot be null.
      Null elements are ignored (only non-null classes that extend Throwable are added).
      Returns:
      This object.

    • run

      public RestResponse run() throws RestCallException
      Runs this request and returns the resulting response object.
      Example:

      try { int rc = client.get(URI).execute().getResponseStatus(); // Succeeded! } catch (RestCallException e) { // Failed! }

      Notes:
      • Calling this method multiple times will return the same original response object.
      • You must close the returned object if you do not consume the response or execute a method that consumes the response.
      • If you are only interested in the response code, use the complete() method which will automatically consume the response so that you don't need to call InputStream.close() on the response body.
      Returns:
      The response object.
      Throws:
      RestCallException - If an exception or non-200 response code occurred during the connection attempt.

    • runFuture

      public Future<RestResponse> runFuture() throws RestCallException
      Same as run() but allows you to run the call asynchronously.
      Example:

      Future<RestResponse> future = client.get(URI).runFuture(); // Do some other stuff try { String body = future.get().getContent().asString(); // Succeeded! } catch (RestCallException e) { // Failed! }

      Notes:
      Returns:
      The HTTP status code.
      Throws:
      RestCallException - If the executor service was not defined.

    • serializer

      public RestRequest serializer(Class<? extends Serializer> serializer)
      Specifies the serializer to use on the request body.

      Overrides the serializers specified on the RestClient.

      The serializer can be configured using any of the serializer property setters (e.g. RestClient.Builder.sortCollections()) or bean context property setters (e.g. RestClient.Builder.swaps(Class...)) defined on this builder class.

      If the Content-Type header is not set on the request, it will be set to the media type of this serializer.

      Parameters:
      serializer - The serializer used to serialize POJOs to the body of the HTTP request.
      Can be null (will use default serializer matching Content-Type).
      Returns:
      This object.

    • serializer

      public RestRequest serializer(Serializer serializer)
      Specifies the serializer to use on the request body.

      Overrides the serializers specified on the RestClient.

      The serializer is not modified by an of the serializer property setters (e.g. RestClient.Builder.sortCollections()) or bean context property setters (e.g. RestClient.Builder.swaps(Class...)) defined on this builder class.

      If the Content-Type header is not set on the request, it will be set to the media type of this serializer.

      Parameters:
      serializer - The serializer used to serialize POJOs to the body of the HTTP request.
      Can be null (will use default serializer matching Content-Type).
      Returns:
      This object.

    • 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.
      Can be null (ignored).

    • 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.
      Cannot be null or empty (header will not be created).
      value - The value of the header.
      Can be null.

    • 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.
      Can be null (all headers will be cleared).
      Can contain null values (ignored).

    • setParams

      @Deprecated public void setParams(HttpParams params)
      Deprecated.
      Use constructor parameters of configuration API provided by HttpClient.
      Provides parameters to be used for the processing of this message.
      Specified by:
      setParams in interface HttpMessage
      Parameters:
      params - The parameters.
      Can be null (default parameters will be used).

    • suppressLogging

      public RestRequest suppressLogging()
      Causes logging to be suppressed for the duration of this request.

      Overrides the debug() setting on this request or client.

      Returns:
      This object.

    • target

      public RestRequest target(HttpHost target)
      Specifies the target host for the request.
      Parameters:
      target - The target host for the request. Implementations may accept null if they can still determine a route, for example to a default target or by inspecting the request.
      Returns:
      This object.

    • uon

      public RestRequest uon()
      Convenience method for specifying UON as the marshalling transmission media type for this request only.

      UON is Url-Encoding Object notation that is equivalent to JSON but suitable for transmission as URL-encoded query and form post values.

      UonSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      UonParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "text/uon" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "text/uon" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(UonSerializer.class).parser(UonParser.class).

      Returns:
      This object.

    • uri

      public RestRequest uri(Object uri) throws RestCallException
      Sets the URI for this request.

      Can be any of the following types:

      Relative URI strings will be interpreted as relative to the root URI defined on the client.

      Parameters:
      uri - The URI of the remote REST resource.
      This overrides the URI passed in from the client.
      Can be any of the following types:
      Cannot be null.
      Returns:
      This object.
      Throws:
      RestCallException - Invalid URI syntax detected.

    • uriFragment

      public RestRequest uriFragment(String fragment)
      Sets the URI fragment.
      Parameters:
      fragment - The URI fragment. The value is expected to be unescaped and may contain non ASCII characters.
      Can be null (fragment will be cleared).
      Returns:
      This object.

    • uriHost

      public RestRequest uriHost(String host)
      Sets the URI host.
      Parameters:
      host - The new URI host.
      Can be null (host will be cleared).
      Returns:
      This object.

    • uriPort

      public RestRequest uriPort(int port)
      Sets the URI port.
      Parameters:
      port - The new URI port.
      Returns:
      This object.

    • uriScheme

      public RestRequest uriScheme(String scheme)
      Sets the URI scheme.
      Parameters:
      scheme - The new URI scheme.
      Can be null (scheme will be cleared).
      Returns:
      This object.

    • uriUserInfo

      public RestRequest uriUserInfo(String userInfo)
      Sets the URI user info.
      Parameters:
      userInfo - The new URI user info.
      Can be null (user info will be cleared).
      Returns:
      This object.

    • uriUserInfo

      public RestRequest uriUserInfo(String username, String password)
      Sets the URI user info.
      Parameters:
      username - The new URI username.
      Can be null.
      password - The new URI password.
      Can be null.
      Returns:
      This object.

    • urlEnc

      public RestRequest urlEnc()
      Convenience method for specifying URL-Encoding as the marshalling transmission media type for this request only.

      UrlEncodingSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      UrlEncodingParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "application/x-www-form-urlencoded" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "application/x-www-form-urlencoded" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(UrlEncodingSerializer.class).parser(UrlEncodingParser.class).

      Returns:
      This object.

    • xml

      public RestRequest xml()
      Convenience method for specifying XML as the marshalling transmission media type for this request only.

      XmlSerializer will be used to serialize POJOs to request bodies unless overridden per request via serializer(Serializer).

      XmlParser will be used to parse POJOs from response bodies unless overridden per request via parser(Parser).

      Accept request header will be set to "text/xml" unless overridden by header(String,Object) or accept(String).

      Content-Type request header will be set to "text/xml" unless overridden by header(String,Object) or contentType(String).

      Identical to calling serializer(XmlSerializer.class).parser(XmlParser.class).

      Returns:
      This object.

    • createHeader

      protected Header createHeader(String name, Object value, HttpPartSerializer serializer, HttpPartSchema schema, Boolean skipIfEmpty)
      Creates a new header.
      Parameters:
      name - The header name.
      value - The header value.
      serializer - The part serializer to use, or null to use the part serializer defined on the client.
      schema - Optional HTTP part schema to provide to the part serializer.
      skipIfEmpty - If true, empty string values will be ignored on the request.
      Returns:
      A new header.

    • createInnerRequest

      protected HttpRequestBase createInnerRequest(String method, URI uri, boolean hasBody)
      Constructs the HttpRequestBase object that ends up being passed to the client execute method.

      Subclasses can override this method to create their own request base objects.

      Parameters:
      method - The HTTP method.
      uri - The HTTP URI.
      hasBody - Whether the HTTP request has a body.
      Returns:
      A new HttpRequestBase object.

    • createPart

      protected NameValuePair createPart(String name, Object value, HttpPartType type, HttpPartSerializer serializer, HttpPartSchema schema, Boolean skipIfEmpty)
      Creates a new query/form-data/path part.
      Parameters:
      name - The part name.
      value - The part value.
      type - The HTTP part type.
      serializer - The part serializer to use, or null to use the part serializer defined on the client.
      schema - Optional HTTP part schema to provide to the part serializer.
      skipIfEmpty - If true, empty string values will be ignored on the request.
      Returns:
      A new part.

    • properties

      protected FluentMap<String,Object> properties()
      Description copied from class: ContextSession
      Returns the properties on this bean as a map for debugging.
      Overrides:
      properties in class BeanSession
      Returns:
      The properties on this bean as a map for debugging.