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/01 20:51:24 UTC
cvs commit: jakarta-commons/httpclient/xdocs cookies.xml navigation.xml troubleshooting.xml
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