Introduction

This document provides a brief guide to custom handling of redirects with HttpClient.

There are a few types of redirect that HttpClient can't handle automatically either because they require user interaction, or they are outside of the scope of HttpClient (these status codes are listed below), or due to internal limitations. Currently HttpClient is unable to automatically handle redirects of entity enclosing methods such as POST and PUT. There can also be situations when manual processing of redirects is desired due to specific application requirements.

Handling redirects manually

All response codes between 300 and 399 inclusive are redirect responses of some form. The most common redirect response codes are:

  • 301 Moved Permanently. HttpStatus.SC_MOVED_PERMANENTLY
  • 302 Moved Temporarily. HttpStatus.SC_MOVED_TEMPORARILY
  • 303 See Other. HttpStatus.SC_SEE_OTHER
  • 307 Temporary Redirect. HttpStatus.SC_TEMPORARY_REDIRECT

Note: there are a number of response codes in the 3xx range which do not simply indicate a different URI to send the request to. These response codes are listed below and the manner they are handled will be application specific.

When your application receives one of the "simple" redirect responses, it should extract the new URL from the HttpMethod object and retry downloading from that URL. Additionally, it is usually a good idea to limit the number of redirects that will be followed in case the redirects form a recursive loop.

The URL to connect to can be extracted from the Location header.

        String redirectLocation;
        Header locationHeader = method.getResponseHeader("location");
        if (locationHeader != null) {
            redirectLocation = locationHeader.getValue();
        } else {
            // The response is invalid and did not provide the new location for
            // the resource.  Report an error or possibly handle the response
            // like a 404 Not Found error.
        }

Once you have determined the new location, you can reattempt the connection as normal. See the Tutorial for more information on this.

Special Redirect Codes

The HTTP specification defines a number of somewhat unusual redirect response codes that will likely need to be handled in a different manner to the codes above. In particular these are:

  • 300 Multiple Choices. HttpStatus.SC_MULTIPLE_CHOICES

    There are multiple choices available for the redirection. A preferred redirect URI may be specified in the location header, however generally it is expected that the user will be given the choice of which URI to be redirected to. It is however permissible to simply select one of the available choices arbitrarily.

  • 304 Not Modified. HttpStatus.SC_NOT_MODIFIED

    The resource has not been modified since it was last requested. You should retrieve the resource from cache instead. If the resource is no longer available in the cache the request should be retried without the conditional headers.

  • 305 Use Proxy. HttpStatus.SC_USE_PROXY

    The resource must be accessed through the specified proxy. The proxy is specified in the Location header.