commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mbe...@apache.org
Subject cvs commit: jakarta-commons/httpclient/xdocs authentication.xml redirects.xml
Date Wed, 04 Jun 2003 02:28:14 GMT
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&amp;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&amp;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


Mime
View raw message