Creating a New Cookie

When you create a new cookie, you must give the cookie a name and provide an initial value. After the cookie has been created, the value can change, but the name must remain the same. The constructor for the Cookie class takes the name and value as arguments:

public Cookie(String name, String value)

The getName and getValue methods return the name and value of an existing cookie:

public String getName()
public String getValue()

You can also change the cookie's value by calling setValue:

public void setValue(String newValue)

Setting the Domain and Path

A browser doesn't send all its cookies to a server whenever it makes a request. Instead, each cookie is tagged with a domain and path. The browser sends only those cookies that match the server's domain and path. For example, if the browser is accessing http://examples.wutka.com/examples/DemoServlet and it has a cookie with a domain of .wutka.com and a path of /examples, it sends that cookie to the server. If it has a cookie with a domain of .wutka.com and a path of /other, it does not send the cookie because the paths don't match. If it has a cookie with a domain of hackingjava.wutka.com and a path of /examples, it does not send the cookie because the domains don't match. Even alternate host names for the same host are different when it comes to processing cookies. For example, if I access a URL with http://localhost and then later hit the same server with http://flamingo.wutka.com, any cookies stored by localhost are unavailable from the flamingo URL even though they are the same host.

By default, a cookie's domain is the server that sent the cookie to begin with. If you have a large environment with multiple servers handling requests, make sure you set only the domain on your cookies so that the client will return cookies to all the servers that can process a request.

You can query and set the domain with getDomain and setDomain:

public String getDomain()
public void setDomain(String newDomain)

You can query and set the path with getPath and setPath:

public String getPath()
public void setPath(String newPath)

If you want a cookie to match any possible path, use / for the path.

Cookie Aging

Nobody likes to eat stale cookies, not even a browser. When you send a cookie to the browser, you can give it an expire time. After the expire time has elapsed, the browser gets rid of the cookie. The getMaxAge and setMaxAge methods enable you to query and set the expire time for a cookie:

public int getMaxAge()
public void setMaxAge(int maxAge)

When you set the maximum age of a cookie, you are telling the browser how many seconds it should keep the cookie. If the browser should hold on to the cookie for an hour, you need to set the maximum age to 3600 seconds. If the age is a positive number, the browser saves the cookie so it will be available even if the user shuts the browser down and starts it up again. If the age is a negative number, the browser holds on to the cookie only as long as the browser is running. When the user shuts the browser down, all cookies with a negative age value disappear. If you set the maximum age to 0, the cookie is immediately removed. If you have stored a cookie on the browser in the past and you want to delete it, the proper way to delete it is to set the age to 0.

Secure Cookies

Sometimes a cookie holds sensitive data. When you need to store sensitive data in a cookie and want to ensure that the cookie is sent to the browser only when the connection is secure, you can mark the cookie as secure by calling setSecure:

public void setSecure(secureFlag)

If a cookie's secureFlag is true, the browser sends the cookie to the server only if it's using a secure protocol such as HTTPS (SSL). You can query the secure flag by calling getSecure:

public boolean getSecure()

Cookie Protocol Versions

The cookie protocol was originally developed by Netscape and then copied by other browser vendors as the use of cookies became more widespread. Since that time, the IETF (the Internet standards body) has created a standard cookie protocol. You can find the standard cookie protocol online at www.ietf.org/rfc/rfc2109.txt.

One of the problems with standards that are developed by a committee is that it takes some time for them to be adopted, if they are adopted at all. The officially blessed RFC 2109 cookie protocol adds some additional features that are not yet supported on many browsers. You can get and set the protocol version that your cookie requires by calling getVersion and setVersion:

public int getVersion()
public void setVersion(int version)

The original Netscape cookie protocol has a version number of 0, whereas RFC 2109 has a version number of 1. Unless you have special circumstances in which you know that all the browsers using your system will support RFC 2109, you should stick to version 0 until most of the browser population supports RFC 2109.

Cookie Comments

One of the features added in RFC 2109 is a comment describing the purpose of the cookie. Many browsers have the capability to prompt the user when a server tries to save a cookie. You can use the comment to give the user a clue as to what is being saved in the cookie so the user can decide whether to accept it. Obviously, this is on the honor system. You could easily tell the user that the cookie contains a simple session ID although it actually contains his or her name, address, and credit card number.

Because the comment field was added in RFC 2109, it is not available in version 0 cookies and is probably not supported by a large number of browsers yet.

Use the getComment and setComment methods to query and change the cookie's comment:

public String getComment()
public void setComment(String comment)