Introduction

In a typical visit to a web site, a user sends multiple requests for resources to a web server. If a web page contains many images (and most do!), then requesting the single web page involves one HTTP request for the HTML code and other template text (such as headlines and phrases), followed by separate requests for each image the web page contains. Future requests for the same page often return versions of these text and images that are cached on the client's computer for the sake of efficiency, depending on whether the fetched resources permit caching. At any rate, the server views each HTTP request for these web resources as separate and discrete from the other requests. Without the use of additional protocols, the server does not have a mechanism for managing client state, such as the progress of a web user through a questionnaire or storefront. Being able to logically relate one or more web requests as a single user session is where cookies come in.

A cookie is a small piece of information on a user's computer that a web server can use to identify that user the next time he visits the site. When a user initially visits the cookie-enabled site, the server responds with an extra response header that looks like:

Set-Cookie: mycookie=1051565332678; Domain=.myorg.com;
Expires=Tue, 29-Apr-2003 07:42:12 GMT

Consequently, when the user visits the same site, his browser sends an extra request header that contains the cookie associated with that web location. Here is what the request headers look like when the client returns to the site that previously set the cookie; since the servlet container is Tomcat 4.1.12, the Cookie request header also includes a name/value pair for the session-related cookie (JSESSIONID):

GET /home/cookie HTTP/1.1
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/msword, 
application/vnd.ms-powerpoint, application/vnd.ms-excel, application/pdf, */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 4.0)
Host: localhost:9000
Connection: Keep-Alive
Cookie: JSESSIONID=F80F0F571FDE4873CFF3FF0B842D4938; mycookie=1051610231064

A cookie contains a name and a value; the cookie can also have several other optional attribute/value pairs, which are separated by semicolons:

Domain

Specifies the domain to which this cookie will be sent in future requests, as in Domain=.jspservletcookbook.com. The default value of this optional attribute is the hostname of the domain that has sent the Set-Cookie header.

Path

Further delineates the part of the web site that, when requested, is sent the cookie by the client. Most cookies give this attribute a value of /. For example, if only the customer context path should receive the cookie, then the Set-Cookie header would include the path=/customer attribute/value pair. The client would not send the cookie value when making any requests to the domain that do not include the /customer context path.

Expires

Specifies the maximum amount of time the user's browser should keep the cookie. This attribute is a date string representing a future date. If Expires specifies a past date, then the cookie is deleted. The Java Cookie API manages this attribute by calling the Cookie object's setMaxAge( ) method (see Recipe 10.1).

Version

An optional value of 0 for Netscape's preliminary specification and 1 for the RFC 2109 document.

Secure

True if the cookie can be sent only over a secure connection such as HTTPS.

Comment

May have as a value a description of the cookie's purpose.

A browser is expected to support 20 cookies for each web server, 300 cookies total, and may limit cookie size to 4 KB each, according to the javax.servlet.http.Cookie API documentation. The cookie name and value combine to represent the 4-KB limit, according to the Netscape preliminary specification. A typical cookie is far less than 4 KB in size.

The user can also disable cookies, so that his browser does not save any of the cookies in a web-server response. For example, in Netscape 7.1, the menu combination Edit Preferences Privacy & Security Cookies allows you to prevent the acceptance of cookies by choosing the "Disable cookies" radio button. In this case, the web developer uses "URL rewriting" for any clients that have disabled cookies (see Recipe 11.7 and Recipe 11.8).

The Java servlet API abstracts a cookie as an object of type javax.servlet.http.Cookie. The recipes in this chapter show how to create new cookies, as well as read or alter existing cookies, with both servlets and JSPs.