rwsf::Cookie
Package: Servlet
Base Class
- Local Index
- Header File
- Description
- Public Constructors
- Public Destructor
- Public Member Operators
- Public Member Functions
- See Also
Local Index
Members
Header File
#include <rwsf/servlet/http/Cookie.h>
Description
rwsf::Cookie represents an HTTP cookie. A cookie is a small piece of data sent from the server to the client. The client stores the cookie and returns it to the server with later requests. Cookies are typically used to store a small amount of state on the client. If the application requires little state, cookies can maintain the complete state of the application. Otherwise, the application will save the application state on the server and send the client a cookie with a unique token. On later requests, the client returns the token. The application uses the token to associate the saved state with the request. This class provides a simple API for working with cookies.
Each cookie consists of a name, a value, and a set of optional attributes. To add a cookie to a response, use the addCookie function of rwsf::HttpServletResponse. To access cookies in a request, use either the getCookie function or the getCookies function of rwsf::HttpServletRequest.
rwsf::Cookie provides support for both Version 0 (Netscape) and Version 1 (RFC 2109) cookies. However, due to portability concerns we recommend that you use Version 0 cookies (the default).
Note that HydraExpress includes classes that encapsulate the details of associating saved state with a client. For some applications, these classes can eliminate the need for working with cookies directly. See rwsf::HttpSession and related classes for details.
Table 1 lists methods that are either non-standard or not supported in this release.
Table 1: rwsf::Cookie Deviation from Servlet Specification
| Member | Description of Difference from Servlet Specification |
constructors and assignment operator | added constructors and assignment operator |
getExpires() setExpires() | added methods for getting and setting expiration on version 0 cookies |
clone() | not included in this implementation (functionality replaced by assignment operator and copy constructor). |
Public Constructors
Cookie();
Creates an unnamed, empty cookie. Use the copy constructor or assignment operator to create a valid cookie instance.
Cookie(const std::string& name);
Creates a new cookie with the given name. Use the setValue() method to set the value of a cookie.
Cookie(const std::string& name, const std::string& value);
Creates a new cookie with the provided name and value.
Cookie(const Cookie& second);
Copy constructor. Constructs a new cookie as a deep copy of second.
Public Destructor
~Cookie();
Destructor.
Public Member Operators
Cookie& operator=(const Cookie& second);
Makes self a deep copy of second.
Public Member Functions
std::string getComment() const;
Returns the comment for this cookie. If this cookie has no comment, returns the empty string.
std::string getDomain() const;
Returns the domain name for this cookie. The domain name is defined by RFC 2109. If this cookie has no domain set, returns the empty string.
std::string getExpires() const;
Returns a string containing the date and time that this cookie expires. Returns the empty string if the client should not save this cookie. Note that this method is only applicable to version 0 cookies.
int getMaxAge() const;
Returns the maximum age of this cookie in seconds. The default is -1, which means that the client will delete the cookie when the client exits. Note that this method is only applicable to version 1 cookies.
std::string getName() const;
Returns the name that this cookie contains. The name of the cookie is set when the object is constructed, and cannot be changed.
std::string getPath() const;
Returns the path associated with this cookie. A client will return the cookie with any request to the server that begins with this path. For example if the path is /examples then the browser will send the cookie to URIs under /examples. See RFC 2109 for more information on the format of paths for cookies.
bool getSecure() const;
Returns true if the browser is using a secure mechanism for sending cookies, false otherwise. The default is FALSE.
std::string getValue() const;
Returns the value contained within this cookie.
int getVersion() const;
Returns the version of this cookie. There are two possible versions, version 0 and version 1.
A version 0 cookie corresponds to the original Netscape proposal. A version 1 cookie complies with RFC 2109. Since RFC 2109 is still fairly new, using only version 0 cookies may facilitate portability between browsers.
void setComment(const std::string& comment);
Sets the comment contained within the cookie. The comment describes the purpose of the cookie. Version 0 of the cookie specification does not include comments. A client that only understands version 0 cookies will discard comments.
void setDomain(const std::string& pattern);
Sets the domain to which this cookie belongs. The form of the domain is specified by RFC 2109. By default, a client will return cookies to only the server that originally created the cookie.
void setExpires(const std::string& expiry);
Sets the date/time expiration string for version 0 cookies. This string takes the format Wdy, DD-Mon-YYYY HH:MM:SS GMT, for example, "Sat, 21-Jun-2003 19:10:00 GMT". An empty string indicates that the client should not save the cookie. This method is only applicable to version 0 cookies. For version 1 cookies, the Agent uses the value set with setMaxAge().
void setMaxAge(int expiry);
Sets the length of time the client should retain the cookie, in seconds. A negative value indicates that the client should delete the cookie when the client exits. A value of 0 indicates that the client should delete the cookie immediately. The default is -- 1. This method is only applicable to version 1 cookies. For version 0 cookies, the Agent uses the value set with setExpires().
void setPath(const std::string& uri);
Sets the path for which this cookie is valid. A client will return the cookie with any request to this server that begins with this path. For example if the path is /examples then the browser will send the cookie to URIs under /examples. See RFC 2109 for more information on the format of paths for cookies.
void setSecure(bool flag);
Sets whether the browser will return the cookies on a secure connection, or on any connection. If set to true the browser will only return the cookie with requests that use a secure connection such as HTTPS. The default is false.
void setValue(const std::string& value);
Sets the value of this cookie. If binary data needs to be stored, use an encoding such as BASE64.
void setVersion(int v);
Sets the version of this cookie. Possible values are 0 and 1. A version 1 cookie corresponds to RFC 2109. Version 0 cookies follow the original Netscape specification. Newly-constructed cookies default to 0.
See Also
©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.