Module io.avaje.http.client
Package io.avaje.http.client

Interface HttpClientRequest

public interface HttpClientRequest
Http request that is built and sent to the server.

Largely wraps the standard JDK HttpRequest with additional support for converting beans to body content and converting beans from response content. 



  HelloDto dto = client.request()
       .path("hello").queryParam("name", "Rob").queryParam("say", "Whats up")
       .GET()
       .bean(HelloDto.class);
See Also:

  • Method Details

    • skipAuthToken

      HttpClientRequest skipAuthToken()
      For this request skip using an Authorization token.

      This is automatically set on the request passed to AuthTokenProvider.obtainToken(HttpClientRequest).

    • suppressLogging

      HttpClientRequest suppressLogging()
      For this request suppress payload logging.

      The payload contains sensitive content and the request and response content should be suppressed and not included in request logging.

    • label

      HttpClientRequest label(String label)
      Set a label for the request. The label is intended to be used to group and identify metrics for the request.
      Parameters:
      label - The label that can be used to identify metrics for the request

    • label

      String label()
      Return the label that has been set on this request.

      Typically the label would be read in RequestIntercept.afterResponse(HttpResponse, HttpClientRequest) to assign request execution metrics.

    • setAttribute

      HttpClientRequest setAttribute(String key, Object value)
      Used to pass custom attribute between RequestIntercept methods.

      Allows us to pass something between beforeRequest and afterResponse methods of a RequestIntercept or between multiple RequestIntercept.

      Parameters:
      key - The unique key used to store the attribute
      value - The attribute to store

    • getAttribute

      <E> E getAttribute(String key)
      Return a custom attribute typically set by a RequestIntercept.beforeRequest(HttpClientRequest).
      Type Parameters:
      E - The inferred type of the attribute
      Parameters:
      key - The key for the custom attribute
      Returns:
      The custom attribute

    • requestTimeout

      HttpClientRequest requestTimeout(Duration requestTimeout)
      Set the request timeout to use for this request. When not set the default request timeout will be used.
      Parameters:
      requestTimeout - The request timeout to use for this request.
      Returns:
      The request being built

    • headerAddIfAbsent

      HttpClientRequest headerAddIfAbsent(String name, Object value)
      Add the header to the request but only if there is no existing value for the given header.
      Parameters:
      name - The header name
      value - The header value
      Returns:
      The request being built

    • header

      HttpClientRequest header(String name, String value)
      Add the header to the request.
      Parameters:
      name - The header name
      value - The header value
      Returns:
      The request being built

    • header

      HttpClientRequest header(String name, Object value)
      Add the header to the request implicitly converting the value to a String. If the value is a collection then it's values are appended with the same key
      Parameters:
      name - The header name
      value - The header value
      Returns:
      The request being built

    • header

      HttpClientRequest header(Map<String,?> headers)
      Add the headers to the request via map.
      Parameters:
      headers - The headers as name value map to add
      Returns:
      The request being built

    • header

      HttpClientRequest header(String name, Collection<String> value)
      Add the headers to the request via Collection.
      Parameters:
      name - The header name
      value - The header values
      Returns:
      The request being built

    • header

      List<String> header(String name)
      Return the header values that have been set for the given header name.
      Returns:
      The headers values or an empty collection if the header has not been specified yet.

    • headers

      Map<String,List<String>> headers()
      Return the header values that have been set for this request.
      Returns:
      The headers values or an empty map if no headers have been specified yet.

    • gzip

      HttpClientRequest gzip(boolean gzip)
      Set if body content should be gzip encoded.
      Parameters:
      gzip - Set true to gzip encode the body content.
      Returns:
      The request being built

    • url

      HttpClientRequest url(String url)
      Set the URL to use replacing the base URL. 
      {code

  HttpResponse res = client.request()
       .url("http://127.0.0.1:8889")
       .path("hello")
       .GET()
       .asString();

 }
      Parameters:
      url - The url effectively replacing the base url.
      Returns:
      The request being built
      See Also:

    • method

      String method()
      The Http Verb (GET, POST, PUT etc) of this request.
      Returns:
      The Http Verb of this request.

    • url

      String url()
      The URL for this request including the query parameters.
      Returns:
      The url for this request

    • path

      HttpClientRequest path(String path)
      Add a path segment to the URL.
      Parameters:
      path - The path segment to add to the URL path.
      Returns:
      The request being built

    • path

      HttpClientRequest path(int val)
      Add a path segment to the URL.
      Parameters:
      val - The value to add to the URL path.
      Returns:
      The request being built

    • path

      HttpClientRequest path(long val)
      Add a path segment to the URL.
      Parameters:
      val - The value to add to the URL path.
      Returns:
      The request being built

    • path

      HttpClientRequest path(Object val)
      Add a path segment to the URL.
      Parameters:
      val - The value to add to the URL path.
      Returns:
      The request being built

    • matrixParam

      HttpClientRequest matrixParam(String name, String value)
      Add a matrix parameter to the current path segment.
      Parameters:
      name - The matrix parameter name
      value - The matrix parameter value which can be null
      Returns:
      The request being built

    • matrixParam

      HttpClientRequest matrixParam(String name, Object value)
      Add a matrix parameter to the current path segment.
      Parameters:
      name - The matrix parameter name
      value - The matrix parameter value which can be null
      Returns:
      The request being built

    • queryParam

      HttpClientRequest queryParam(String name, String value)
      Add a query parameter
      Parameters:
      name - The name of the query parameter
      value - The value of the query parameter which can be null
      Returns:
      The request being built

    • queryParam

      HttpClientRequest queryParam(String name, Object value)
      Add a query parameter, if value is a collection then it's values are appended with the same key
      Parameters:
      name - The name of the query parameter
      value - The value of the query parameter which can be null
      Returns:
      The request being built

    • queryParam

      HttpClientRequest queryParam(Map<String,?> params)
      Add a multiple query parameters as name value map.
      Parameters:
      params - The query parameters
      Returns:
      The request being built

    • queryParam

      default HttpClientRequest queryParam(String name, Collection<String> values)
      Add a query parameter with multiple values
      Parameters:
      name - The name of the query parameter
      values - The values of the query parameter which can be null
      Returns:
      The request being built

    • formParam

      HttpClientRequest formParam(String name, String value)
      Add a form parameter.
      Parameters:
      name - The form parameter name
      value - The form parameter value which can be null
      Returns:
      The request being built

    • formParam

      HttpClientRequest formParam(String name, Object value)
      Add a form parameter.
      Parameters:
      name - The form parameter name
      value - The form parameter value which can be null
      Returns:
      The request being built

    • formParam

      HttpClientRequest formParam(Map<String,?> params)
      Add the form parameters via a map.
      Parameters:
      params - The form parameters as name value map
      Returns:
      The request being built

    • body

      HttpClientRequest body(BodyContent bodyContent)
      Set encoded body content.

    • body

      HttpClientRequest body(Object bean, String contentType)
      Set the body as a bean with the given content type using a BodyWriter.

    • body

      HttpClientRequest body(Object bean)
      Set the body as a bean using the default content type.

      The default content type will often be application/json; charset=utf8.

    • body

      HttpClientRequest body(Object bean, Class<?> type)
      Set the body as a bean additionally specifying the type that will be used to serialise the content (e.g. JsonbAdapter).

      Specifying the type allows the bean instance to be a type that extends a type that is known to JsonbAdapter / the body content adapter used.

      Parameters:
      bean - The body content as an instance
      type - The type used by the body content adapter to write the body content
      Returns:
      The request being built

    • body

      HttpClientRequest body(Object bean, Type type)
      Set the body as a bean additionally specifying the type that will be used to serialise the content (e.g. JsonbAdapter).

      Specifying the type allows the bean instance to be a type that extends a type that is known to JsonbAdapter / the body content adapter used.

      Parameters:
      bean - The body content as an instance
      type - The type used by the body content adapter to write the body content
      Returns:
      The request being built

    • body

      HttpClientRequest body(Object bean, Class<?> type, String contentType)
      Set the body as a bean with the given content type and additionally specifying the type that will be used to serialise the content (e.g. JsonbAdapter).

      Specifying the type allows the bean instance to be a type that extends a type that is known to JsonbAdapter / the body content adapter used.

      Parameters:
      bean - The body content as an instance
      type - The type used by the body content adapter to write the body content
      contentType - The content type of the body
      Returns:
      The request being built

    • body

      HttpClientRequest body(String body)
      Set the body content as a string using the default content type.
      Parameters:
      body - The body content
      Returns:
      The request being built

    • body

      HttpClientRequest body(byte[] body)
      Set the body content as a bytes.
      Parameters:
      body - The body content
      Returns:
      The request being built

    • body

      HttpClientRequest body(Supplier<? extends InputStream> supplier)
      Set the body content with supplied InputStream.
      Parameters:
      supplier - The supplier of InputStream content to send as body content
      Returns:
      The request being built

    • body

      HttpClientRequest body(InputStream stream)
      Set the body content with supplied InputStream.
      Parameters:
      stream - The InputStream content to send as body content
      Returns:
      The request being built

    • body

      HttpClientRequest body(Path file)
      Set the body content with supplied InputStream.
      Parameters:
      file - The file to send as body content
      Returns:
      The request being built

    • body

      HttpClientRequest body(HttpRequest.BodyPublisher body)
      Set the body content using http BodyPublisher.
      Parameters:
      body - The body content
      Returns:
      The request being built

    • bodyContent

      Optional<BodyContent> bodyContent()
      Get the body content for this request if available. Will return an empty optional for streaming calls
      Returns:
      The request body

    • errorMapper

      HttpClientRequest errorMapper(Function<HttpException,RuntimeException> errorMapper)
      Set the mapper used to transform HttpException into a different kind of exception.

      When set, all HttpException that are thrown by this request will be caught and transformed into more specific exception with the given function by default.

      Parameters:
      errorMapper - function to map the httpException
      Returns:
      The request being built

    • GET

      HttpClientResponse GET()
      Execute the request as a GET.

    • POST

      HttpClientResponse POST()
      Execute the request as a POST.

    • PUT

      HttpClientResponse PUT()
      Execute the request as a PUT.

    • PATCH

      HttpClientResponse PATCH()
      Execute the request as a PATCH.

    • DELETE

      HttpClientResponse DELETE()
      Execute the request as a DELETE.

    • TRACE

      HttpClientResponse TRACE()
      Execute the request as a TRACE.

    • HEAD

      HttpClientResponse HEAD()
      Execute the request as a HEAD.

    • responseTimeMicros

      long responseTimeMicros()
      After the response is returned this method returns the response time in microseconds.

      This is useful for use in RequestIntercept.afterResponse(HttpResponse, HttpClientRequest)