Interface ClientRequest<T extends ClientRequest<T>>

Type Parameters:
T - type of the implementation, to support fluent API
All Known Subinterfaces:
FullClientRequest<T>, Http1ClientRequest, Http2ClientRequest, JsonRpcClientRequest
All Known Implementing Classes:
ClientRequestBase, HttpClientRequest

public interface ClientRequest<T extends ClientRequest<T>>
Request can be reused within a single thread, but it remembers all explicitly configured headers and URI. Implementation is not expected to be thread safe!
  • Method Details

    • uri

      default T uri(String uri)
      Configure URI. The string is encoded before it is resolved. To forward a server request target, use requestTarget(io.helidon.http.HttpPrologue).
      Parameters:
      uri - uri to resolve against base URI, or to use if absolute
      Returns:
      updated request
    • path

      default T path(String uri)
      Configure path to call.
      Parameters:
      uri - path
      Returns:
      updated request
    • tls

      T tls(Tls tls)
      TLS configuration for this specific request.
      Parameters:
      tls - tls configuration
      Returns:
      updated request
    • sni

      default T sni(SniConfig sni)
      Configure client-side TLS SNI for this request.

      Request-level SNI overrides client-level SNI. A configured SNI host is also used as the TLS peer host for endpoint identification.

      Parameters:
      sni - SNI configuration
      Returns:
      updated request
    • sni

      default T sni(Consumer<SniConfig.Builder> sni)
      Configure client-side TLS SNI for this request.

      Request-level SNI overrides client-level SNI. A configured SNI host is also used as the TLS peer host for endpoint identification.

      Parameters:
      sni - SNI configuration builder
      Returns:
      updated request
    • proxy

      T proxy(Proxy proxy)
      Proxy configuration for this specific request.
      Parameters:
      proxy - proxy configuration
      Returns:
      updated request
    • uri

      T uri(URI uri)
      Configure an existing URI.
      Parameters:
      uri - uri to resolve against base URI, or to use if absolute
      Returns:
      updated request
    • requestTarget

      default T requestTarget(HttpPrologue prologue)
      Replace the request path and query with the target from an HTTP prologue. This can be used to forward a server request using its prologue() while retaining this client's destination scheme, host, and port. The configured base path, query, fragment, and URI template are replaced; the method, headers, and URI encoding setting are unchanged.

      With URI encoding enabled (the default), the raw path and query are preserved, including percent-escape spelling, matrix parameters, query ordering, repeated parameters, and an empty query delimiter. Reading query parameters does not change the target. Explicit query parameter mutations rebuild the query; changing the path leaves an unmodified query intact. The prologue's fragment is not copied.

      Origin-form targets must start with /. For absolute-form HTTP or HTTPS targets, only the raw path and query are copied; an empty path is sent as /. Asterisk-form and authority-form targets are not supported.

      The default implementation throws UnsupportedOperationException. Implementations that support forwarding must override this method.

      Parameters:
      prologue - prologue containing the request target to forward
      Returns:
      updated request
      Throws:
      IllegalArgumentException - if the target form is unsupported or the raw path or query is invalid
      UnsupportedOperationException - if this request implementation does not support request-target forwarding
    • address

      default T address(SocketAddress socketAddress)
      Socket address to use. This can be used to connect to a UNIX domain socket. Note that if UNIX domain socket address is configured, all other address configuration is ignored. This includes if it is configured as a base address on the client.

      An InetSocketAddress updates the logical URI host and port. A UnixDomainSocketAddress overrides the physical transport only, so the request URI, resolved against the client base URI, still provides the logical HTTP authority. For TLS over a UNIX domain socket, the resolved URI host and port are used for SNI and endpoint identification, while the UNIX domain socket path is used only for transport.

      Parameters:
      socketAddress - socket address to use, this will override any other address configuration
      Returns:
      updated request
    • uri

      T uri(ClientUri uri)
      Configure request URI. This always replaces the existing URI (even if base URI is configured).
      Parameters:
      uri - uri to resolve against base URI, or to use if absolute
      Returns:
      updated request
    • header

      T header(Header header)
      Set an HTTP header.
      Parameters:
      header - header to set
      Returns:
      updated request
    • header

      default T header(HeaderName name, String... values)
      Set an HTTP header.
      Parameters:
      name - header name
      values - header values
      Returns:
      updated request
    • header

      default T header(HeaderName name, List<String> values)
      Set an HTTP header with multiple values.
      Parameters:
      name - header name
      values - header values
      Returns:
      updated request
    • headers

      T headers(Headers headers)
      Configure headers. Copy all headers from supplied Headers instance.
      Parameters:
      headers - to copy
      Returns:
      updated request
    • headers

      T headers(Consumer<ClientRequestHeaders> headersConsumer)
      Update headers.
      Parameters:
      headersConsumer - consumer of client request headers
      Returns:
      updated request
    • accept

      default T accept(HttpMediaType... accepted)
      Accepted media types. Supports quality factor and wildcards.
      Parameters:
      accepted - media types to accept
      Returns:
      updated request
    • accept

      default T accept(MediaType... acceptedTypes)
      Accepted media types. Supports quality factor and wildcards.
      Parameters:
      acceptedTypes - media types to accept
      Returns:
      updated request
    • contentType

      default T contentType(MediaType contentType)
      Sets the content type of the request.
      Parameters:
      contentType - content type of the request.
      Returns:
      updated request
    • pathParam

      T pathParam(String name, String value)
      Replace a placeholder in URI with an actual value.
      Parameters:
      name - name of parameter
      value - value of parameter
      Returns:
      updated request
    • queryParam

      T queryParam(String name, String... values)
      Add query parameter.
      Parameters:
      name - name of parameter
      values - value(s) of parameter
      Returns:
      updated request
    • fragment

      default T fragment(String fragment)
      Set fragment of the URI.
      Parameters:
      fragment - fragment
      Returns:
      updated request
    • fragment

      T fragment(UriFragment fragment)
      Set fragment of the URI.
      Parameters:
      fragment - fragment
      Returns:
      updated request
    • followRedirects

      T followRedirects(boolean followRedirects)
      Whether to follow redirects.
      Parameters:
      followRedirects - follow redirects
      Returns:
      updated request
    • maxRedirects

      T maxRedirects(int maxRedirects)
      Max number of the followed redirects.
      Parameters:
      maxRedirects - max followed redirects
      Returns:
      updated request
    • followRedirects

      boolean followRedirects()
      Whether to follow redirects.
      Returns:
      follow redirects
    • maxRedirects

      int maxRedirects()
      Maximal number of redirects to follow. This is to prevent infinite redirects.
      Returns:
      max number of redirects
    • request

      default HttpClientResponse request()
      Request without an entity.
      Returns:
      response
    • headers

      Get a (mutable) instance of outgoing headers.
      Returns:
      client request headers
    • request

      default <E> ClientResponseTyped<E> request(Class<E> type)
      Request without sending an entity.
      Type Parameters:
      E - type of entity
      Parameters:
      type - type of entity
      Returns:
      correctly typed response
      See Also:
    • request

      default <E> ClientResponseTyped<E> request(GenericType<E> type)
      Request without sending an entity.
      Type Parameters:
      E - type of entity
      Parameters:
      type - generic type of entity
      Returns:
      correctly typed response
      See Also:
    • requestEntity

      default <E> E requestEntity(Class<E> type) throws HttpException
      Request entity without sending a request entity, asking for entity only. This method will fail if the status is not in successful family.
      Type Parameters:
      E - type of the entity to read from the response
      Parameters:
      type - type of requested entity
      Returns:
      correctly typed entity
      Throws:
      HttpException - in case the response status is not success
    • requestEntity

      default <E> E requestEntity(GenericType<E> type) throws HttpException
      Request entity without sending a request entity, asking for entity only. This method will fail if the status is not in successful family.
      Type Parameters:
      E - type of the entity to read from the response
      Parameters:
      type - generic type of requested entity
      Returns:
      correctly typed entity
      Throws:
      HttpException - in case the response status is not success
    • submit

      HttpClientResponse submit(Object entity)
      Submit an entity. For HTTP/1.1 streamed entities, entity writing can run on a helper virtual thread using the current Helidon context. This includes InstanceWriter.write(java.io.OutputStream) and EntityWriter implementations without instance-writer support. The writer can prepare request headers before its first output, and this method waits for the writer to terminate, including when an early response cancels the upload. Writers must release owned resources when output fails. Custom writers must not assume caller-thread affinity or propagation of arbitrary thread-local state.
      Parameters:
      entity - request entity
      Returns:
      response
    • submit

      default <E> ClientResponseTyped<E> submit(Object entity, Class<E> requestedType)
      Submit an entity and request a specific type. The entity-writing behavior described by submit(Object) also applies.
      Type Parameters:
      E - type of response entity
      Parameters:
      entity - request entity
      requestedType - type of response entity
      Returns:
      correctly typed response
    • submit

      default <E> ClientResponseTyped<E> submit(Object entity, GenericType<E> requestedType)
      Submit an entity and request a specific type. The entity-writing behavior described by submit(Object) also applies.
      Type Parameters:
      E - type of response entity
      Parameters:
      entity - request entity
      requestedType - generic type of response entity
      Returns:
      correctly typed response
    • outputStream

      HttpClientResponse outputStream(ClientRequest.OutputStreamHandler outputStreamConsumer)
      Handle output stream and submit the request. For HTTP/1.1, request headers are sent before invoking the handler when negotiating Expect: 100-continue. An early final response or a redirect that discards the request entity can therefore bypass the handler entirely. Configure request headers before calling this method, rather than inside the handler.

      A handler that writes no bytes can still trigger the HTTP/1.1 handshake when the content length is unknown. An explicit content length of zero bypasses the handshake. A method-preserving redirect received after an upload can invoke the handler again to replay the entity. Account for both bypass and replay when the handler has side effects or consumes a one-shot source.

      Parameters:
      outputStreamConsumer - handler that writes and closes the request output stream
      Returns:
      response
    • outputStream

      default <T> ClientResponseTyped<T> outputStream(ClientRequest.OutputStreamHandler outputStreamConsumer, Class<T> requestedType)
      Handle output stream and request a specific type. The handler behavior described by outputStream(OutputStreamHandler) also applies.
      Type Parameters:
      T - type of response entity
      Parameters:
      outputStreamConsumer - output stream consumer to write request entity
      requestedType - type of response entity
      Returns:
      correctly typed response
    • resolvedUri

      UriInfo resolvedUri()
      Resolved URI that will be used to invoke this request.
      Returns:
      URI to invoke
    • connection

      T connection(ClientConnection connection)
      This method is for explicit connection use by this request.
      Parameters:
      connection - connection to use for this request
      Returns:
      updated client request
    • skipUriEncoding

      T skipUriEncoding(boolean skip)
      Disable uri encoding.
      Parameters:
      skip - set to true to disable URI encoding (false by default)
      Returns:
      updated client request
    • property

      T property(String propertyName, String propertyValue)
      Add a property to be used by this request.
      Parameters:
      propertyName - property name
      propertyValue - property value
      Returns:
      updated builder instance
    • keepAlive

      T keepAlive(boolean keepAlive)
      Whether to use keep alive with this request.
      Parameters:
      keepAlive - use keep alive
      Returns:
      updated client request
    • readTimeout

      T readTimeout(Duration readTimeout)
      Read timeout for this request.
      Parameters:
      readTimeout - response read timeout
      Returns:
      updated client request
    • readContinueTimeout

      T readContinueTimeout(Duration readContinueTimeout)
      Read 100-Continue timeout for this request. This read timeout is used when 100-Continue is sent by the client, before it sends an entity.
      Parameters:
      readContinueTimeout - read 100-Continue timeout duration
      Returns:
      updated client request
      See Also:
    • sendExpectContinue

      T sendExpectContinue(boolean sendExpectContinue)
      Whether Expect 100-Continue header is sent to verify server availability before sending an entity. Can be used to override the setting inherited from HttpClientConfig.sendExpectContinue() on a per-request basis.
      Parameters:
      sendExpectContinue - value to override behavior for a single request
      Returns:
      updated client request