1. Overview

Apache HttpClient provides support for retrying requests.

In this tutorial, we’ll look at how we can configure the request retry behavior for Apache HttpClient 4.

2. Default Retry Behavior

By default, HttpClient retries the failed requests 3 additional times. So the same request can be executed at most 4 times including the initial request execution.

Additionally, there are some conditions for HttpClient to retry a request. For example, HttpClient doesn’t retry a request that is getting 400 as the status code. It is also the case for 404 and 500 status codes. So, in essence, there must be a network level failure or IO error for the retry mechanism to kick in:

public void executeRetryingThreeTimesImplicitly() throws Exception {
    try (CloseableHttpClient httpClient = HttpClients.custom()
      .addInterceptorLast(new HttpRequestInterceptor() {
          @Override
          public void process(HttpRequest request, HttpContext context) throws HttpException, IOException {
              throw new IOException("Planned");
          }
      }).build()) {
        executeGetRequest(httpClient);
    }
}

Here, we’re creating an instance of CloseableHttpClient. To trigger the retry mechanism, we’re adding an interceptor. So when the interceptor throws IOException, HttpClient will retry the request. As a result, the request will be executed 4 times in total.

3. Configuring Retry Behavior

HttpClient uses the DefaultHttpRequestRetryHandler class to manage the retry behavior. We can also create an instance of DefaultHttpRequestRetryHandler and configure its properties. Then we must pass this configured instance to our HttpClient:

public void executeRetryingTenTimesExplicitly() throws Exception {
    try (CloseableHttpClient httpClient = HttpClients.custom()
      .addInterceptorLast(new HttpRequestInterceptor() {
          @Override
          public void process(HttpRequest request, HttpContext context) throws HttpException, IOException {
              throw new IOException("Planned");
          }
      })
      .setRetryHandler(new DefaultHttpRequestRetryHandler(10, false))
      .build()) {
        executeGetRequest(httpClient);
    }
}

This example is very similar to the previous one. Here we’re additionally creating an instance of DefaultHttpRequestRetryHandler. Notice that we’re also setting the retry count as 10. As a result, HttpClient will retry the same request 10 times. If we count the initial request execution, the same request will be executed 11 times.

4. Implementing Custom Retry Behavior

We can also provide a custom retry behavior by implementing the HttpRequestRetryHandler interface.

HttpRequestRetryHandler requestRetryHandler = new HttpRequestRetryHandler() {
    @Override
    public boolean retryRequest(IOException exception, int executionCount, HttpContext context) {
        return executionCount < 5;
    }
};

Here we’re providing a very basic implementation. It will retry a request at most 5 times. However, we can also introduce a more involved logic according to our needs.

Then we must register our HttpRequestRetryHandler:

CloseableHttpClient httpClient = HttpClients.custom()
  .setRetryHandler(requestRetryHandler)
  .build();

5.  Disabling Retry Behavior

Lastly, we can disable request retry mechanism:

CloseableHttpClient httpClient = HttpClients.custom()
  .disableAutomaticRetries()
  .build();

Here, we’re calling disableAutomaticRetries() on HttpClientBuilderAs a result, HttpClient will execute each request only once even if the request fails – because of some IO exception.

6. Summary

In this tutorial, we’ve looked at how we can configure the request retry mechanism for Apache HttpClient 4.

Firstly, we looked at the default retry behavior. Then we investigated how we can configure the retry properties. We also implemented our custom retry handler. Lastly, we looked at disabling automatic retries.

As always the source code for all examples is available on Github.

Leave a Reply

Close Menu