Interface HttpRequest<R extends HttpRequest>

All Known Subinterfaces:
GetRequest, HttpRequestWithBody, JsonPatchRequest, MultipartBody, RequestBodyEntity
All Known Implementing Classes:
BaseRequest, HttpRequestBody, HttpRequestJsonPatch, HttpRequestMultiPart, HttpRequestNoBody, HttpRequestUniBody
public interface HttpRequest<R extends HttpRequest>
The primary request builder used to create a request. This will be completed after calling one of the "as**" methods like asString()

  • Method Details

    • routeParam

      R routeParam(String name, String value)
      add a route param that replaces the matching {name} For example routeParam("name", "fred") will replace {name} in https://localhost/users/{name} to https://localhost/users/fred
      Parameters:
      name - the name of the param (do not include curly braces {}
      value - the value to replace the placeholder with
      Returns:
      this request builder

    • routeParam

      R routeParam(Map<String,Object> params)
      add a route param map that replaces the matching {name} For example routeParam(Map.of("name", "fred")) will replace {name} in https://localhost/users/{name} to https://localhost/users/fred
      Parameters:
      params - a map of path params
      Returns:
      this request builder

    • basicAuth

      R basicAuth(String username, String password)
      Basic auth credentials
      Parameters:
      username - the username
      password - the password
      Returns:
      this request builder

    • accept

      default R accept(ContentType value)
      The Accept header to send (e.g. application/json)
      Parameters:
      value - a valid mime type for the Accept header
      Returns:
      this request builder

    • accept

      R accept(String value)
      The Accept header to send (e.g. application/json)
      Parameters:
      value - a valid mime type for the Accept header
      Returns:
      this request builder

    • responseEncoding

      R responseEncoding(String encoding)
      The encoding to expect the response to be for cases where the server fails to respond with the proper encoding
      Parameters:
      encoding - a valid mime type for the Accept header
      Returns:
      this request builder

    • header

      R header(String name, String value)
      Add a http header, HTTP supports multiple of the same header. This will continue to append new values
      Parameters:
      name - name of the header
      value - value for the header
      Returns:
      this request builder

    • headerReplace

      R headerReplace(String name, String value)
      Replace a header value or add it if it doesn't exist
      Parameters:
      name - name of the header
      value - value for the header
      Returns:
      this request builder

    • headers

      R headers(Map<String,String> headerMap)
      Add headers as a map
      Parameters:
      headerMap - a map of headers
      Returns:
      this request builder

    • headersReplace

      R headersReplace(Map<String,String> headerMap)
      Replace headers as a map
      Parameters:
      headerMap - a map of headers
      Returns:
      this request builder

    • cookie

      R cookie(String name, String value)
      Add a simple cookie header
      Parameters:
      name - the name of the cookie
      value - the value of the cookie
      Returns:
      this request builder

    • cookie

      R cookie(Cookie cookie)
      Add a simple cookie header
      Parameters:
      cookie - a cookie
      Returns:
      this request builder

    • cookie

      R cookie(Collection<Cookie> cookies)
      Add a collection of cookie headers
      Parameters:
      cookies - a cookie
      Returns:
      this request builder

    • queryString

      R queryString(String name, Object value)
      add a query param to the url. The value will be URL-Encoded
      Parameters:
      name - the name of the param
      value - the value of the param
      Returns:
      this request builder

    • queryString

      R queryString(String name, Collection<?> value)
      Add multiple param with the same param name. queryString("name", Arrays.asList("bob", "linda")) will result in ?name=bob&name=linda
      Parameters:
      name - the name of the param
      value - a collection of values
      Returns:
      this request builder

    • queryString

      R queryString(Map<String,Object> parameters)
      Add query params as a map of name value pairs
      Parameters:
      parameters - a map of params
      Returns:
      this request builder

    • withObjectMapper

      R withObjectMapper(ObjectMapper mapper)
      Pass a ObjectMapper for the request. This will override any globally configured ObjectMapper
      Parameters:
      mapper - the ObjectMapper
      Returns:
      this request builder

    • requestTimeout

      R requestTimeout(int millies)
      Set a timeout for this request
      Parameters:
      millies - the time in millies
      Returns:
      this request builder

    • downloadMonitor

      R downloadMonitor(ProgressMonitor monitor)
      sets a download monitor for monitoring the response. this could be used for drawing a progress bar
      Parameters:
      monitor - a ProgressMonitor
      Returns:
      this request builder

    • version

      R version(HttpClient.Version version)
      sets the HTTP version for the request. This will override any global config
      Parameters:
      version - the version
      Returns:
      this request builder

    • asString

      HttpResponse<String> asString()
      Executes the request and returns the response with the body mapped into a String
      Returns:
      response

    • asStringAsync

      CompletableFuture<HttpResponse<String>> asStringAsync()
      Executes the request asynchronously and returns the response with the body mapped into a String
      Returns:
      a CompletableFuture of a response

    • asStringAsync

      CompletableFuture<HttpResponse<String>> asStringAsync(Callback<String> callback)
      Executes the request asynchronously and returns the response with the body mapped into a String
      Parameters:
      callback - a callback handler
      Returns:
      a CompletableFuture of a response

    • asBytes

      HttpResponse<byte[]> asBytes()
      Executes the request and returns the response with the body mapped into a byte[]
      Returns:
      response

    • asBytesAsync

      CompletableFuture<HttpResponse<byte[]>> asBytesAsync()
      Executes the request asynchronously and returns the response with the body mapped into a byte[]
      Returns:
      a CompletableFuture of a response

    • asBytesAsync

      CompletableFuture<HttpResponse<byte[]>> asBytesAsync(Callback<byte[]> callback)
      Executes the request asynchronously and returns the response with the body mapped into a byte[]
      Parameters:
      callback - a callback handler
      Returns:
      a CompletableFuture of a response

    • asJson

      HttpResponse<JsonNode> asJson()
      Executes the request and returns the response with the body mapped into a JsonNode
      Returns:
      response

    • asJsonAsync

      CompletableFuture<HttpResponse<JsonNode>> asJsonAsync()
      Executes the request asynchronously and returns the response with the body mapped into a JsonNode
      Returns:
      a CompletableFuture of a response

    • asJsonAsync

      CompletableFuture<HttpResponse<JsonNode>> asJsonAsync(Callback<JsonNode> callback)
      Executes the request asynchronously and returns the response with the body mapped into a JsonNode
      Parameters:
      callback - a callback handler
      Returns:
      a CompletableFuture of a response

    • asObject

      <T> HttpResponse<T> asObject(Class<? extends T> responseClass)
      Executes the request and returns the response with the body mapped into T by a configured ObjectMapper
      Type Parameters:
      T - the return type
      Parameters:
      responseClass - the class to return. This will be passed to the ObjectMapper
      Returns:
      a response

    • asObject

      <T> HttpResponse<T> asObject(GenericType<T> genericType)
      Executes the request and returns the response with the body mapped into T by a configured ObjectMapper
      Type Parameters:
      T - the return type
      Parameters:
      genericType - the genertic type to return. This will be passed to the ObjectMapper
      Returns:
      a response

    • asObject

      <T> HttpResponse<T> asObject(Function<RawResponse, T> function)
      Execute the request and pass the raw response to a function for mapping. This raw response contains the original InputStream and is suitable for reading large responses.
      Type Parameters:
      T - The type of the response mapping
      Parameters:
      function - the function to map the response into a object of T
      Returns:
      A HttpResponse containing T as the body

    • asObjectAsync

      <T> CompletableFuture<HttpResponse<T>> asObjectAsync(Class<? extends T> responseClass)
      Executes the request asynchronously and returns response with the body mapped into T by a configured ObjectMapper
      Type Parameters:
      T - the return type
      Parameters:
      responseClass - the class type to map to
      Returns:
      a CompletableFuture of a response

    • asObjectAsync

      <T> CompletableFuture<HttpResponse<T>> asObjectAsync(Class<? extends T> responseClass, Callback<T> callback)
      Executes the request asynchronously, mapping to a type via the configured object mapper and then passed to a callback handler.
      Type Parameters:
      T - the return type
      Parameters:
      responseClass - the type for the ObjectMapper to map to
      callback - a callback for handling the body post mapping
      Returns:
      a CompletableFuture of a HttpResponse containing the body of T

    • asObjectAsync

      <T> CompletableFuture<HttpResponse<T>> asObjectAsync(GenericType<T> genericType)
      Executes the request asynchronously, and use a GenericType with the ObjectMapper
      Type Parameters:
      T - the type of the response
      Parameters:
      genericType - the generic type containing the type
      Returns:
      a CompletableFuture of a HttpResponse containing the body of T

    • asObjectAsync

      <T> CompletableFuture<HttpResponse<T>> asObjectAsync(GenericType<T> genericType, Callback<T> callback)
      Executes the request asynchronously, and use a GenericType with the ObjectMapper
      Type Parameters:
      T - the type of the response
      Parameters:
      genericType - the generic type containing the type
      callback - a callback for handling the body post mapping
      Returns:
      a CompletableFuture of a HttpResponse containing the body of T

    • asObjectAsync

      <T> CompletableFuture<HttpResponse<T>> asObjectAsync(Function<RawResponse, T> function)
      Executes the request asynchronously, and pass the raw response to a function for mapping. This raw response contains the original InputStream and is suitable for reading large responses
      Type Parameters:
      T - the type of the response
      Parameters:
      function - a function to map the raw request into a object
      Returns:
      a CompletableFuture of a HttpResponse containing the body of T

    • asFile

      HttpResponse<File> asFile(String path, CopyOption... copyOptions)
      Executes the request and writes the contents into a file
      Parameters:
      path - The path to the file.
      copyOptions - options specifying how the copy should be done
      Returns:
      a HttpResponse with the file containing the results

    • asFileAsync

      CompletableFuture<HttpResponse<File>> asFileAsync(String path, CopyOption... copyOptions)
      asynchronously executes the request and writes the contents into a file
      Parameters:
      path - The path to the file.
      copyOptions - options specifying how the copy should be done
      Returns:
      a file containing the results

    • asFileAsync

      CompletableFuture<HttpResponse<File>> asFileAsync(String path, Callback<File> callback, CopyOption... copyOptions)
      asynchronously executes the request and writes the contents into a file
      Parameters:
      path - The path to the file.
      callback - a callback for handling the body post mapping
      copyOptions - options specifying how the copy should be done
      Returns:
      a file containing the results

    • asPaged

      <T> PagedList<T> asPaged(Function<HttpRequest, HttpResponse> mappingFunction, Function<HttpResponse<T>, String> linkExtractor)
      Allows for following paging links common in many APIs. Each request will result in the same request (headers, etc) but will use the "next" link provided by the extract function.
      Type Parameters:
      T - the type of response.
      Parameters:
      mappingFunction - a function to return the desired return type leveraging one of the as* methods (asString, asObject, etc).
      linkExtractor - a function to extract a "next" link to follow. Retuning a null or empty string ends the paging
      Returns:
      a PagedList of your type

    • asEmpty

      HttpResponse<Empty> asEmpty()
      Executes the request and returns the response without parsing the body
      Returns:
      the basic HttpResponse

    • asEmptyAsync

      CompletableFuture<HttpResponse<Empty>> asEmptyAsync()
      Executes the request asynchronously and returns the response without parsing the body
      Returns:
      a CompletableFuture of a HttpResponse

    • asEmptyAsync

      CompletableFuture<HttpResponse<Empty>> asEmptyAsync(Callback<Empty> callback)
      Executes the request asynchronously and returns a empty response which is passed to a callback
      Parameters:
      callback - the callback* Executes the request asynchronously and returns the response without parsing the body
      Returns:
      a CompletableFuture of a HttpResponse

    • thenConsume

      void thenConsume(Consumer<RawResponse> consumer)
      Execute the request and pass the raw response to a consumer. This raw response contains the original InputStream and is suitable for reading large responses
      Parameters:
      consumer - a consumer function

    • thenConsumeAsync

      void thenConsumeAsync(Consumer<RawResponse> consumer)
      Execute the request asynchronously and pass the raw response to a consumer. This raw response contains the original InputStream and is suitable for reading large responses
      Parameters:
      consumer - a consumer function

    • getHttpMethod

      HttpMethod getHttpMethod()
      Returns:
      The HTTP method of the request

    • getUrl

      String getUrl()
      Returns:
      The current URL string for the request

    • getHeaders

      Headers getHeaders()
      Returns:
      the current headers for the request

    • getBody

      default Optional<Body> getBody()
      Returns:
      if the request has a body it will be here.

    • getRequestTimeout

      Integer getRequestTimeout()
      Returns:
      the connect timeout for this request

    • toSummary

      HttpRequestSummary toSummary()
      Returns:
      a summary for the response, used in metrics

    • getCreationTime

      Instant getCreationTime()
      Returns:
      the instant the request object was created in UTC (not when it was sent).

    • getVersion

      HttpClient.Version getVersion()
      gets the version for the request, or null if not set.
      Returns:
      the version