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 cookies.xml navigation.xml troubleshooting.xml
Date Sun, 01 Jun 2003 18:51:24 GMT
mbecke      2003/06/01 11:51:23

  Modified:    httpclient/xdocs navigation.xml troubleshooting.xml
  Added:       httpclient/xdocs cookies.xml
  Log:
  Added cookie documentation and modified troubleshooting guide.
  
  PR: 10809
  Submitted by: Adrian Sutton
  Reviewed by: Michael Becke
  
  Revision  Changes    Path
  1.7       +2 -1      jakarta-commons/httpclient/xdocs/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/navigation.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- navigation.xml	26 May 2003 15:13:43 -0000	1.6
  +++ navigation.xml	1 Jun 2003 18:51:23 -0000	1.7
  @@ -19,6 +19,7 @@
         <item name="User Guide" href="/userguide.html">
           <item name="Authentication Guide" href="/authentication.html"/>
           <item name="Character Encodings" href="/charencodings.html"/>
  +        <item name="Cookies" href="/cookies.html"/>
           <item name="Cross Host Redirects" href="/redirects.html"/>
           <item name="Logging Guide" href="/logging.html"/>
           <item name="Methods" href="/methods.html"/>
  
  
  
  1.3       +8 -10     jakarta-commons/httpclient/xdocs/troubleshooting.xml
  
  Index: troubleshooting.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/troubleshooting.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- troubleshooting.xml	11 Mar 2003 08:03:12 -0000	1.2
  +++ troubleshooting.xml	1 Jun 2003 18:51:23 -0000	1.3
  @@ -56,17 +56,15 @@
       <section name="Asking For Help">
         <p>If you've tried the things above and still can't work out how to fix
         the problem, it might be time to contact the <a
  -      href="mail-lists.html">mailing lists</a> for support.  Which list to
  -      contact depends on exactly where you think the problem lies.  If you
  -      think you've just got an error in your code somewhere, probably the
  -      commons-user list is the best place, but if you think that <em>HttpClient</em>
is
  -      at fault, the commons-httpclient-dev list is probably a better choice.</p>
  -
  -      <p style="color: red">Please do not cross-post to both lists.</p>
  +      href="mail-lists.html">mailing list</a> for support.  All questions, bug
  +      reports etc should be directed to the HttpClient development list as all
  +      the really knowledgeable people for HttpClient are there and most are not
  +      also on the commons-user list.</p>
   
         <p>When you do send off the email, please include as much detail as you
  -      can, including attaching wire trace logs if you think they'll help (they
  -      often do).  If you are seeing exceptions being thrown the full stack
  +      can, particularly including attaching wire trace logs as there is almost
  +      nothing we can do to help without them.
  +      If you are seeing exceptions being thrown the full stack
         trace is essential to tracking down the problem.  Any of the information
         you gained from the "things to try" section above are probably worth
         mentioning.</p>
  
  
  
  1.1                  jakarta-commons/httpclient/xdocs/cookies.xml
  
  Index: cookies.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  
  <document>
  
    <properties>
      <title>HttpClient Cookie Guide</title>
      <author email="adrian@intencha.com">Adrian Sutton</author>
      <revision>$Id: cookies.xml,v 1.1 2003/06/01 18:51:23 mbecke Exp $</revision>
    </properties>
  
    <body>
  
      <section name="Introduction">
        <p>HttpClient supports automatic management of cookies, including
        allowing the server to set cookies and automatically return them to the
        server when required.  It is also possible to manually set cookies to be
        sent to the server.</p>
  
        <p>Unfortunately, there are two major standards for handling Cookies,
        RFC2109 and the Netscape Cookie draft, and a large number of
        implementations are completely non-standard.  To deal with this,
        HttpClient provides configurable cookie specifications. This guide will
        explain how to use the different cookie specifications and identify some
        of the common problems people have when using Cookies and HttpClient.</p>
      </section>
  
      <section name="Available Specifications">
        <p>The following cookie specifications are supported by HttpClient.</p>
  
        <subsection name="RFC2109">
          <p>RFC2109 is the final published specification released by the W3C.
          Theoretically, all servers that handle cookies should use this
          specification and as such this specification is used by default within
          HttpClient.</p>
  
          <p>Unfortunately, many servers either incorrectly implement this
          standard or are still using the Netscape draft so occasionally this
          specification is too strict.  If this is the case, you should switch to
          the compatibility specification as described below.</p>
  
          <p>RFC2109 is available at
          <a href="http://www.w3.org/Protocols/rfc2109/rfc2109.txt">http://www.w3.org/Protocols/rfc2109/rfc2109.txt</a>
          </p>
        </subsection>
  
        <subsection name="Netscape Draft">
          <p>The Netscape draft is the original cookie specification which formed
          the basis for RFC2109.  Despite this it has some significant
          differences with RFC2109 and thus may be required for compatibility
          with some servers.</p>
  
          <p>The Netscape cookie draft is available at <a
          href="http://wp.netscape.com/newsref/std/cookie_spec.html">http://wp.netscape.com/newsref/std/cookie_spec.html</a>
          </p>
        </subsection>
  
        <subsection name="Compatibility">
          <p>The compatibility specification is designed to be compatible with as
          many different servers as possible even if they are not completely
          standards compliant.  If you are encountering problems with parsing
          cookies, you should probably try using this specification.</p>
        </subsection>
      </section>
  
      <section name="Specifying the Specification">
        <p>There is two ways to specify which cookie specification should be
        used, either for each HttpState instance, or by setting the default for
        newly created HttpState instances.</p>
  
        <subsection name="Per HttpState">
          <p>In most cases, the best way to set which cookie specification to use
          is using the <code>setCookiePolicy(int policy)</code> method on
          <code>HttpState</code>.  Any HttpClient using that HttpState will then
          use the specified cookie policy.  The value of <code>policy</code>
          should be one of:</p>
          <ul>
            <li><code>CookiePolicy.COMPATIBILITY</code></li>
            <li><code>CookiePolicy.NETSCAPE_DRAFT</code></li>
            <li><code>CookiePolicy.RFC2109</code></li>
          </ul>
  
          <source>
          HttpClient client = new HttpClient();
          client.getState().setCookiePolicy(CookiePolicy.COMPATIBILITY);
          </source>
        </subsection>
  
        <subsection name="Default">
          <p>The default cookie specification can be set by setting the system
          property <code>apache.commons.httpclient.cookiespec</code> to one
          of:</p>
  
          <ul>
            <li><code>String.valueOf(CookiePolicy.COMPATIBILITY)</code></li>
            <li><code>String.valueOf(CookiePolicy.NETSCAPE_DRAFT)</code></li>
            <li><code>String.valueOf(CookiePolicy.RFC2109)</code></li>
          </ul>
  
          <p>This setting will be used by any newly created HttpState objects,
          however existing HttpState instances will not be affected.</p>
  
          <source>
          System.setProperty("apache.commons.httpclient.cookiespec",
          String.valueOf(CookiePolicy.COMPATIBILITY));
          </source>
        </subsection>
      </section>
  
      <section name="Common Problems">
        <p>The most common problems encountered with parsing cookies is due to
        non-compliant servers.  In these cases, switching to the compatibility
        cookie specification usually solves the problem.</p>
      </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