Servlet Development Guide : PART III Programming : Chapter 7 Working With Requests : Managing State on the Client with Cookies
Managing State on the Client with Cookies
An HTTP cookie is a small piece of data stored on the client. The client returns the data to the server on subsequent requests. Cookies provide a mechanism for integrating application state into the HTTP protocol. Note that a client may not necessarily support or accept cookies, clients generally limit the size and number of cookies, and a client is free to delete any cookie at any time. Because of these limitations, the cookie specification (RFC 2109) states that applications should use as few cookies as possible, that the cookies should contain the smallest amount of data possible, and that an application should recover gracefully when a client fails to return the data in a cookie.
Therefore, although cookies are an important mechanism for managing state, cookies rarely include the full state of the application. Instead, cookies typically contain a simple tag that the server uses to associate a client request with application state stored on the server. The servlet container offers built-in support for this style of state management, as described in “Recovering Session State.” However, sessions are best suited for relatively large amounts of data that persist for a relatively short time, such as an online shopping cart. Cookies are preferable for small amounts of data that persist unchanged for a relatively long time, such as a session tag or user ID.
Class rwsf::Cookie encapsulates a cookie. Each cookie consists of a name, a value, and a set of optional attributes. To create a cookie, construct an instance of rwsf::Cookie with the cookie name and cookie value. For example, the line of code below creates a cookie with the name "username" and the value "anonymous".
 
rwsf::Cookie username("username", "anonymous");
To change the value of a cookie, use the setValue() function. For example, the code below sets the value of the "username" cookie to "User1".
 
std::list<rwsf::Cookie> cookies = request.getCookies();
std::list<rwsf::Cookie>::iterator iter = cookies.begin();
std::list<rwsf::Cookie>::iterator endIter = cookies.end();
 
for( ;iter != endIter; ++iter) {
rwsf::Cookie cookie = *iter;
if(cookie.getName().compares("username") == 0){
cookie.setValue("User1");
}
}
To inspect the value of a cookie, use the getValue() function. For example, the code below returns the value of the "username" cookie to the client:
 
std::string output("Username: ");
 
output += username.getValue();
 
request.println(output);
A cookie may contain an intended lifetime. Although the client is free to delete the cookie before the lifetime expires, the client should always delete expired cookies. The setMaxAge() function sets the lifetime of the cookie in seconds. The sample below sets the intended lifetime of the cookie to be 2 hours:
 
username.setMaxAge(7200);
To add a cookie to a response, use the addCookie() function. The sample below adds the username cookie to the response:
 
response.addCookie(username);
For a working example on cookies, see <installdir>\examples\servlet\CookieExample.cpp.