Index: redirects.xml =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/redirects.xml,v retrieving revision 1.2 diff -u -u -r1.2 redirects.xml --- redirects.xml 11 Mar 2003 08:03:12 -0000 1.2 +++ redirects.xml 2 Jun 2003 12:40:41 -0000 @@ -17,12 +17,19 @@ However due to technical constraints and the desire to stabilise the API for a 2.0 release sooner rather than later, this ability is yet to be implemented. Redirects to a different URL on the same host, port and protocol is supported.
+ +There are also a few types of redirect that HttpClient can't handle + automatically either because they require user interaction or are + outside of the scope of HttpClient. These status codes are listed below.
When a server returns a redirect instruction to HttpClient that requires connecting to a different host, HttpClient will simply return - the redirect status code as the response status. This will be one of:
+ the redirect status code as the response status. All response codes + between 300 and 399 inclusive are redirect resonses of + some form. The most common redirect response codes are:HttpStatus.SC_TEMPORARY_REDIRECTWhen your application receives one of these codes, 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 the redirects point to each other.
+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.
@@ -60,6 +75,35 @@Once you have determined the new location, you can reattempt the connection as normal. See the Tutorial for more information on this.
+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:
+ +HttpStatus.SC_MULTIPLE_CHOICESThere 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.
+HttpStatus.SC_NOT_MODIFIEDThe 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.
+HttpStatus.SC_USE_PROXYThe resource must be accessed through the specified proxy. The + proxy is specified in the Location header.
+