<?xml version="1.0" encoding="ISO-8859-1"?>

<document>
  
  <properties>
    <title>Cross Host Redirects</title>
    <author email="adrian@ephox.com">Adrian Sutton</author>
    <revision>$Id$</revision>
  </properties>

  <body>

    <section name="Introduction">
      <p>This document provides a brief guide to custom handling of redirects
        with <em>HttpClient</em>.</p>

        <p>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 <a
        href="#Special%20Redirect%20Codes">below</a>), or due to internal 
        limitations. Currently HttpClient is unable to automatically handle 
        redirects of entity enclosing methods such as <tt>POST</tt> and 
        <tt>PUT</tt>. There can also be situations when manual processing
        of redirects is desired due to specific application requirements.
        </p>
    </section>

    <section name="Handling redirects manually">
      <p>All response codes between 300 and 399 inclusive are redirect responses
       of some form. The most common redirect response codes are:</p>

      <ul>
        <li>301 Moved Permanently.
        <code>HttpStatus.SC_MOVED_PERMANENTLY</code></li>

        <li>302 Moved Temporarily.
        <code>HttpStatus.SC_MOVED_TEMPORARILY</code></li>

        <li>303 See Other. <code>HttpStatus.SC_SEE_OTHER</code></li>

        <li>307 Temporary Redirect.
        <code>HttpStatus.SC_TEMPORARY_REDIRECT</code></li>
      </ul>

      <p><b>Note:</b> 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 <a
      href="#Special%20Redirect%20Codes">below</a> and the manner they are
      handled will be application specific.</p>

      <p>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.</p>

      <p>The URL to connect to can be extracted from the <tt>Location</tt>
      header.</p>

      <source><![CDATA[
        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.
        }
      ]]></source>

      <p>Once you have determined the new location, you can reattempt the
      connection as normal.  See the <a href="tutorial.html">Tutorial</a> for
      more information on this.</p>
    </section>

    <section name="Special Redirect Codes">
      <p>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:</p>

      <ul>
        <li>300 Multiple Choices.
        <code>HttpStatus.SC_MULTIPLE_CHOICES</code><br />
        <p>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.</p>
        </li>
        <li>304 Not Modified.
        <code>HttpStatus.SC_NOT_MODIFIED</code><br />
        <p>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.</p>
        </li>
        <li>305 Use Proxy.
        <code>HttpStatus.SC_USE_PROXY</code><br />
        <p>The resource must be accessed through the specified proxy.  The
        proxy is specified in the Location header.</p>
        </li>
      </ul>
    </section>
  </body>
</document>
