82
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
90
HttpClient Cookie Guide
94
<style type="text/css">
95
@import url("http://jakarta.apache.org/commons/style/tigris.css");
96
@import url("http://jakarta.apache.org/commons/style/maven.css");
97
@import url("http://jakarta.apache.org/commons/style/project.css");
104
<link rel="stylesheet" href="http://jakarta.apache.org/commons/style/print.css" type="text/css" media="print"></link>
105
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta>
107
<meta name="author" content="Adrian Sutton"></meta>
108
<meta name="email" content="adrian@intencha.com"></meta>
110
<meta name="author" content="Oleg Kalnichevski"></meta>
111
<meta name="email" content="oleg@ural.ru"></meta>
118
<body class="composite">
121
<table border="0" width="100%" cellpadding="8" cellspacing="0">
136
<a href="http://jakarta.apache.org/">
137
<img border="0" alt="Apache Software Foundation" src="http://jakarta.apache.org/images/jakarta-logo.gif" align="left"></img>
144
<div id="login" align="right">
153
<a href="http://jakarta.apache.org/commons/httpclient/">
154
<img border="0" alt="HttpClient" src="./images/httpclient_logo.png" align="right"></img>
162
<div id="breadcrumbs">
163
<table border="0" width="100%" cellpadding="4" cellspacing="0">
167
<td>Last published: 10 October 2004
185
<table border="0" width="100%" cellpadding="8" cellspacing="0">
187
<td width="20%" id="leftcol">
193
<strong>About Us</strong>
210
<a href="http://jakarta.apache.org/commons/" class="externalLink" title="External Link">Home</a>
233
<a href="http://jakarta.apache.org/commons/contributors.html" class="externalLink" title="External Link">Contributors</a>
256
<a href="http://jakarta.apache.org/commons/license.html" class="externalLink" title="External Link">License</a>
284
<a href="http://jakarta.apache.org/commons/components.html" class="externalLink" title="External Link">Components</a>
310
<a href="http://jakarta.apache.org/commons/sandbox/index.html" class="externalLink" title="External Link">Sandbox</a>
320
<strong>Overview</strong>
337
<a href="3.0/index.html">HttpClient 3.0</a>
360
<a href="features.html">Features</a>
383
<a href="news.html">News</a>
406
<a href="status.html">Status</a>
429
<a href="downloads.html">Download</a>
452
<a href="applications.html">Applications</a>
480
<a href="userguide.html">User Guide</a>
500
<a href="authentication.html">Authentication Guide</a>
523
<a href="charencodings.html">Character Encodings</a>
545
<b><a href="cookies.html">Cookies</a></b>
569
<a href="redirects.html">Cross Host Redirects</a>
592
<a href="logging.html">Logging Guide</a>
615
<a href="methods.html">Methods</a>
638
<a href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/?only_with_tag=HTTPCLIENT_2_0_BRANCH" class="externalLink" title="External Link">Sample Code</a>
661
<a href="sslguide.html">SSL Guide</a>
684
<a href="threading.html">Threading</a>
707
<a href="troubleshooting.html">Trouble Shooting</a>
730
<a href="tutorial.html">Tutorial</a>
761
<a href="developerguide.html">Developer Guide</a>
781
<a href="releases.html">Release Process</a>
804
<a href="testwebapp.html">Webapp Test Guide</a>
819
<strong>Project Documentation</strong>
836
<a href="index.html">About HttpClient</a>
864
<a href="project-info.html">Project Info</a>
890
<a href="maven-reports.html">Project Reports</a>
911
<a href="http://maven.apache.org/development-process.html" class="externalLink" title="External Link">Development Process</a>
923
<strong>General Information</strong>
940
<a href="http://jakarta.apache.org/commons/charter.html" class="externalLink" title="External Link">Charter</a>
963
<a href="http://jakarta.apache.org/commons/volunteering.html" class="externalLink" title="External Link">Volunteering</a>
986
<a href="http://jakarta.apache.org/commons/patches.html" class="externalLink" title="External Link">Contributing Patches</a>
1009
<a href="http://jakarta.apache.org/commons/releases/index.html" class="externalLink" title="External Link">Releasing Components</a>
1020
<strong>Jakarta Community</strong>
1037
<a href="http://jakarta.apache.org/site/getinvolved.html" class="externalLink" title="External Link">Get Involved</a>
1060
<a href="http://jakarta.apache.org/site/mail.html" class="externalLink" title="External Link">Mailing Lists</a>
1083
<a href="http://jakarta.apache.org/site/cvsindex.html" class="externalLink" title="External Link">Access�CVS�Repositories</a>
1094
<strong>Commons�Resources�(Unofficial)</strong>
1111
<a href="http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaCommonsProjectPages" class="externalLink" title="External Link">Wiki</a>
1134
<a href="http://jakarta.terra-intl.com/commons/" class="externalLink" title="External Link">Japanese�Translation</a>
1157
<a href="http://jakarta.apache-korea.org/commons/" class="externalLink" title="External Link">Korean�Translation</a>
1168
<strong>Related</strong>
1185
<a href="http://commons.apache.org/" class="externalLink" title="External Link">Apache Commons</a>
1208
<a href="http://db.apache.org/commons/" class="externalLink" title="External Link">DB Commons</a>
1231
<a href="http://xml.apache.org/commons/" class="externalLink" title="External Link">XML Commons</a>
1249
<div style="margin-top: 20px; width: 100%; text-align: center;">
1250
<a href="http://maven.apache.org/" title="Built by Maven"><img style="border: 1px solid black" alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a>
1267
<a name="Introduction">Introduction</a>
1270
<p>HttpClient supports automatic management of cookies, including
1271
allowing the server to set cookies and automatically return them to the
1272
server when required. It is also possible to manually set cookies to be
1273
sent to the server.</p><p>Unfortunately, there are several at times conflicting standards for
1274
handling Cookies: the Netscape Cookie draft, RFC2109, RFC2965 and a large
1275
number of vendor specific implementations that are compliant with neither
1276
specification. To deal with this, HttpClient provides policy driven cookie
1277
management. This guide will explain how to use the different cookie
1278
specifications and identify some of the common problems people have when
1279
using Cookies and HttpClient.</p>
1286
<a name="Available Specifications">Available Specifications</a>
1289
<p>The following cookie specifications are supported by HttpClient.</p>
1294
<a name="Netscape Draft">Netscape Draft</a>
1297
<p>The Netscape draft is the original cookie specification which formed
1298
the basis for RFC2109. Despite this it has some significant
1299
differences with RFC2109 and thus may be required for compatibility
1300
with some servers.</p><p>The Netscape cookie draft is available at
1301
<a href="http://wp.netscape.com/newsref/std/cookie_spec.html">http://wp.netscape.com/newsref/std/cookie_spec.html</a>
1310
<a name="RFC2109">RFC2109</a>
1313
<p>RFC2109 is the first official cookie specification released by the W3C.
1314
Theoretically, all servers that handle version 1 cookies should use this
1315
specification and as such this specification is used by default within
1316
HttpClient.</p><p>Unfortunately, many servers either incorrectly implement this
1317
standard or are still using the Netscape draft so occasionally this
1318
specification is too strict. If this is the case, you should switch to
1319
the compatibility specification as described below.</p><p>RFC2109 is available at
1321
<a href="http://www.w3.org/Protocols/rfc2109/rfc2109.txt">http://www.w3.org/Protocols/rfc2109/rfc2109.txt</a>
1330
<a name="Compatibility">Compatibility</a>
1333
<p>The compatibility specification is designed to be compatible with as
1334
many different servers as possible even if they are not completely
1335
standards compliant. If you are encountering problems with parsing
1336
cookies, you should probably try using this specification.</p>
1345
<a name="Unsupported Specifications">Unsupported Specifications</a>
1348
<p>The following cookie specifications are not presently supported by HttpClient.</p>
1353
<a name="RFC2965">RFC2965</a>
1356
<p>RFC2965 defines cookie version 2 and attempts to address the shortcomings
1357
of the RFC2109 regarding cookie version 1. RFC2965 is intended to eventually
1358
supersede RFC2109.</p><p>Currently HttpClient does not implement this specification. Support for
1359
version 2 cookies will be added in the future</p><p>RFC2965 is available at
1361
<a href="http://www.zvon.org/tmRFC/RFC2965/Output/">http://www.zvon.org/tmRFC/RFC2965/Output/</a>
1372
<a name="Specifying the Specification">Specifying the Specification</a>
1375
<p>There is two ways to specify which cookie specification should be
1376
used, either for each HttpState instance, or by setting the default for
1377
newly created HttpState instances.</p>
1382
<a name="Per HttpState">Per HttpState</a>
1385
<p>In most cases, the best way to set which cookie specification to use
1386
is using the <code>setCookiePolicy(int policy)</code> method on
1387
<code>HttpState</code>. Any HttpClient using that HttpState will then
1388
use the specified cookie policy. The value of <code>policy</code>
1389
should be one of:</p><ul>
1390
<li><code>CookiePolicy.COMPATIBILITY</code></li>
1391
<li><code>CookiePolicy.NETSCAPE_DRAFT</code></li>
1392
<li><code>CookiePolicy.RFC2109</code></li>
1396
HttpClient client = new HttpClient();
1397
client.getState().setCookiePolicy(CookiePolicy.COMPATIBILITY);
1407
<a name="Default">Default</a>
1410
<p>The default cookie specification can be set by setting the system
1411
property <code>apache.commons.httpclient.cookiespec</code> to one
1413
<li><code>"COMPATIBILITY"</code></li>
1414
<li><code>"NETSCAPE_DRAFT"</code></li>
1415
<li><code>"RFC2109"</code></li>
1416
</ul><p>This setting will be used by any newly created HttpState objects,
1417
however existing HttpState instances will not be affected.</p>
1420
System.setProperty("apache.commons.httpclient.cookiespec", "COMPATIBILITY");
1432
<a name="Common Problems">Common Problems</a>
1435
<p>The most common problems encountered with parsing cookies is due to
1436
non-compliant servers. In these cases, switching to the compatibility
1437
cookie specification usually solves the problem.</p>
1444
<a name="Encoding Issues">Encoding Issues</a>
1447
<p>Since cookies are transfered as HTTP Headers they are confined to
1448
the <tt>US-ASCII</tt> character set. Other characters will be lost or
1449
mangeled. Cookies are typically set and read by the same server, so
1450
a custom scheme for escaping non-ASCII characters can be used, for
1451
instance the well-established URL encoding scheme. If cookies are
1452
used to transfer data between server and client both parties must
1453
agree on the escaping scheme used in a custom way. The HttpClient
1454
cookie implementation provides no special means to handle non-ASCII
1455
characters nor does it issue warnings.</p>
1469
<table border="0" style="width:100%" cellpadding="4" cellspacing="0">
1477
� 2001-2004, Apache Software Foundation
added
removed
docs/cookies.html
