1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - Cross Host Redirects</title><style type="text/css" media="all">
@import url("./style/maven-base.css");
@import url("./style/maven-theme.css");@import url("./style/project.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta><meta name="author" content="Adrian Sutton"></meta><meta name="email" content="adrian@ephox.com"></meta></head><body class="composite"><div id="banner"><a href="http://jakarta.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://jakarta.apache.org/images/jakarta-logo.gif"></img></a><a href="http://jakarta.apache.org/httpcomponents/httpclient-3.x/" id="projectLogo"><img alt="HttpClient" src="./images/httpclient_logo.png"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 18 August 2007
<span class="separator">|</span>Doc for 3.1
</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuOverview"><h5>Overview</h5><ul><li class="none"><a href="features.html">Features</a></li><li class="none"><a href="news.html">News</a></li><li class="none"><a href="status.html">Status</a></li><li class="none"><a href="downloads.html">Download</a></li><li class="none"><a href="http://wiki.apache.org/jakarta-httpclient/" class="externalLink" title="External Link">Wiki</a></li><li class="expanded"><a href="userguide.html">User Guide</a><ul><li class="none"><a href="authentication.html">Authentication Guide</a></li><li class="none"><a href="charencodings.html">Character Encodings</a></li><li class="none"><a href="cookies.html">Cookies</a></li><li class="none"><a href="exception-handling.html">Exception Handling</a></li><li class="none"><a href="logging.html">Logging Guide</a></li><li class="none"><a href="methods.html">Methods</a></li><li class="none"><a href="performance.html">Optimization Guide</a></li><li class="none"><a href="preference-api.html">Preference Architecture</a></li><li class="none"><strong><a href="redirects.html">Redirects Handling</a></strong></li><li class="none"><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/" class="externalLink" title="External Link">Sample Code</a></li><li class="none"><a href="sslguide.html">SSL Guide</a></li><li class="none"><a href="threading.html">Threading</a></li><li class="none"><a href="troubleshooting.html">Trouble Shooting</a></li><li class="none"><a href="tutorial.html">Tutorial</a></li></ul></li><li class="none"><a href="developerguide.html">Developer Guide</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="index.html">About</a></li><li class="collapsed"><a href="project-info.html">Project Info</a></li><li class="collapsed"><a href="maven-reports.html">Project Reports</a></li><li class="none"><a href="development-process.html">Development Process</a></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/mavenlogo_builtby_w.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Introduction"></a><h2>Introduction</h2>
<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>
</div><div class="section"><a name="Handling_redirects_manually"></a><h2>Handling redirects manually</h2>
<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>
<div class="source"><pre>
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.
}
</pre></div>
<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>
</div><div class="section"><a name="Special_Redirect_Codes"></a><h2>Special Redirect Codes</h2>
<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></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></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></br>
<p>The resource must be accessed through the specified proxy. The
proxy is specified in the Location header.</p>
</li>
</ul>
</div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright"> 2001-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
|
