Interface HttpClient

All Known Implementing Classes:
ApacheHttpClient, JdkHttpClient, LoggingHttpClient, OkHttpClient
public interface HttpClient
A client for executing HTTP requests both synchronously and asynchronously. This interface is currently experimental and subject to change.

  • Method Details

    • execute

      SuccessfulHttpResponse execute(HttpRequest request) throws HttpException, RuntimeException
      Executes a given HTTP request synchronously and returns the response. This method blocks until the entire response is received.
      Parameters:
      request - the HTTP request to be executed.
      Returns:
      a SuccessfulHttpResponse containing the response data for successful HTTP requests (2XX status codes)
      Throws:
      HttpException - if the server returns a client (4XX) or server (5XX) error response
      RuntimeException - if an unexpected error occurs during request execution (e.g., network issues, timeouts)

    • executeAsync

      @Experimental default CompletableFuture<SuccessfulHttpResponse> executeAsync(HttpRequest request)
      Non-blocking counterpart of execute(HttpRequest). Returns immediately with a CompletableFuture that completes with the SuccessfulHttpResponse once the full response has been received, without blocking the calling thread. The future completes exceptionally with an HttpException for non-2XX responses, or with the underlying error (e.g. a timeout or network failure) otherwise.
      Parameters:
      request - the HTTP request to be executed.
      Returns:
      a CompletableFuture of the SuccessfulHttpResponse.
      Since:
      1.20.0

    • execute

      default void execute(HttpRequest request, ServerSentEventListener listener)
      Executes a given HTTP request asynchronously with server-sent events (SSE) handling. This method returns immediately while processing continues on a separate thread. Events are processed through the provided ServerSentEventListener.

      The execution flow is as follows:

      1. The request is initiated asynchronously
      2. Received SSE data is parsed using the DefaultServerSentEventParser
      3. Parsed events are delivered to the listener's appropriate methods
      4. If an error occurs, ServerSentEventListener.onError(Throwable) is called

      If any exception is thrown from the listener's methods, the stream processing will be terminated and no further events will be processed.

      Parameters:
      request - the HTTP request to be executed.
      listener - the listener to receive parsed events and error notifications.

    • execute

      void execute(HttpRequest request, ServerSentEventParser parser, ServerSentEventListener listener)
      Executes a given HTTP request asynchronously with server-sent events (SSE) handling. This method returns immediately while processing continues on a separate thread. Events are processed through the provided ServerSentEventListener.

      The execution flow is as follows:

      1. The request is initiated asynchronously
      2. Received SSE data is parsed using the provided parser
      3. Parsed events are delivered to the listener's appropriate methods
      4. If an error occurs, ServerSentEventListener.onError(Throwable) is called

      If any exception is thrown from the listener's methods, the stream processing will be terminated and no further events will be processed.

      Parameters:
      request - the HTTP request to be executed.
      parser - the parser to process incoming server-sent events.
      listener - the listener to receive parsed events and error notifications.

    • stream

      @Experimental default Flow.Publisher<HttpStreamingEvent> stream(HttpRequest request)
      Executes a streaming HTTP request and exposes the parsed events as a cold Flow.Publisher of HttpStreamingEvents. Nothing happens until you subscribe: each subscribe() initiates a new request.

      This interface gives no guarantee about thread-pinning or whether events are delivered incrementally; such guarantees depend on the implementation. Consult the chosen implementation's javadoc.

      If the server answers with an error status (not 2xx), the publisher fails with an HttpException that contains the status code and the response body. Some implementations first emit an HttpErrorResponseReceived as soon as the response headers arrive, so that the subscriber can react to the status code without waiting for the body.

      Uses DefaultServerSentEventParser for SSE parsing.

      Since:
      1.20.0

    • stream

      @Experimental default Flow.Publisher<HttpStreamingEvent> stream(HttpRequest request, ServerSentEventParser parser)
      Like stream(HttpRequest), but with a caller-supplied ServerSentEventParser.
      Since:
      1.20.0