You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by mb...@apache.org on 2003/06/04 04:28:14 UTC
cvs commit: jakarta-commons/httpclient/xdocs authentication.xml redirects.xml
mbecke 2003/06/03 19:28:14
Modified: httpclient/xdocs authentication.xml redirects.xml
Log:
Updates to authentication and redirection xdocs.
PR: 10816
Submitted by: Adrian Sutton
Reviewed by: Michael Becke
Revision Changes Path
1.4 +12 -7 jakarta-commons/httpclient/xdocs/authentication.xml
Index: authentication.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/authentication.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- authentication.xml 10 Mar 2003 04:49:22 -0000 1.3
+++ authentication.xml 4 Jun 2003 02:28:14 -0000 1.4
@@ -39,9 +39,14 @@
the server gives an unauthorized response in certain situations, thus reducing the overhead
of making the connection. To enable this use the following:</p>
+ <source>client.getState().setAuthenticationPreemptive(true);</source>
+
+ <p>To enable preemptive authentication by default for all newly created
+ <tt>HttpState</tt>'s, a system property can be set, as shown below.</p>
+
<source>setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY, "true");</source>
- <p>The preemptive authentication conforms to rfc2617:</p>
+ <p>The preemptive authentication in HttpClient conforms to rfc2617:</p>
<blockquote>A client SHOULD assume that all paths at or deeper than the depth
of the last symbolic element in the path field of the Request-URI also
@@ -137,11 +142,11 @@
</subsection>
</section>
- <section name="Examples">
- <p>There is an <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/jakarta-commons/httpclient/src/examples/BasicAuthenticatonExample.java?rev=HEAD&content-type=text/plain">example</a>
- of basic authentication available in the
- <a href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/">example directory</a> in CVS.
- </p>
+ <section name="Examples">
+ <p>There is an <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/jakarta-commons/httpclient/src/examples/BasicAuthenticatonExample.java?rev=HEAD&content-type=text/plain">example</a>
+ of basic authentication available in the
+ <a href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/examples/">example directory</a> in CVS.
+ </p>
</section>
</body>
1.3 +50 -6 jakarta-commons/httpclient/xdocs/redirects.xml
Index: redirects.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/redirects.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- redirects.xml 11 Mar 2003 08:03:12 -0000 1.2
+++ redirects.xml 4 Jun 2003 02:28:14 -0000 1.3
@@ -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.</p>
+
+ <p>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 <a
+ href="#Special%20Redirect%20Codes">below</a>.</p>
</section>
<section name="Handling Redirects">
<p>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:</p>
+ 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:</p>
<ul>
<li>301 Moved Permanently.
@@ -37,10 +44,18 @@
<code>HttpStatus.SC_TEMPORARY_REDIRECT</code></li>
</ul>
- <p>When 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.</p>
+ <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>
@@ -60,6 +75,35 @@
<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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org