Class Cookie

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

    public class Cookie
    extends java.lang.Object
    implements java.lang.Cloneable, java.io.Serializable
    A HTTP cookie. This class represents a "Cookie", as used for session management with HTTP and HTTPS protocols. Cookies are used to get user agents (web browsers etc) to hold small amounts of state associated with a user's web browsing. Common applications for cookies include storing user preferences, automating low security user signon facilities, and helping collect data used for "shopping cart" style applications.

    Cookies are named, and have a single value. They may have optional attributes, including a comment presented to the user, path and domain qualifiers for which hosts see the cookie, a maximum age, and a version. Current web browsers often have bugs in how they treat those attributes, so interoperability can be improved by not relying on them heavily.

    Cookies are assigned by servers, using fields added to HTTP response headers. Cookies are passed back to those servers using fields added to HTTP request headers. Several cookies with the same name can be returned; they have different path attributes, but those attributes will not be visible when using "old format" cookies.

    Cookies affect the caching of the web pages used to set their values. At this time, none of the sophisticated HTTP/1.1 cache control models are supported. Standard HTTP/1.0 caches will not cache pages which contain cookies created by this class.

    Cookies are being standardized by the IETF. This class supports the original Cookie specification (from Netscape Communications Corp.) as well as the updated RFC 2109 specification.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String mComment
      Describes the cookie's use.
      protected java.lang.String mDomain
      Domain that sees cookie.
      protected java.util.Date mExpiry
      Cookie expires after this date.
      protected java.lang.String mName
      The name of the cookie.
      protected java.lang.String mPath
      URLs that see the cookie.
      protected boolean mSecure
      Use SSL.
      protected java.lang.String mValue
      The cookie value.
      protected int mVersion
      If Version=1 it means RFC 2109++ style cookies.
    • Constructor Summary

      Constructors 
      Constructor Description
      Cookie​(java.lang.String name, java.lang.String value)
      Defines a cookie with an initial name/value pair.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object clone()
      Returns a copy of this object.
      java.lang.String getComment()
      Returns the comment describing the purpose of this cookie, or null if no such comment has been defined.
      java.lang.String getDomain()
      Returns the domain of this cookie.
      java.util.Date getExpiryDate()
      Returns the expiry date of the cookie.
      java.lang.String getName()
      Returns the name of the cookie.
      java.lang.String getPath()
      Returns the prefix of all URLs for which this cookie is targetted.
      boolean getSecure()
      Returns the value of the 'secure' flag.
      java.lang.String getValue()
      Returns the value of the cookie.
      int getVersion()
      Returns the version of the cookie.
      void setComment​(java.lang.String purpose)
      If a user agent (web browser) presents this cookie to a user, the cookie's purpose will be described using this comment.
      void setDomain​(java.lang.String pattern)
      This cookie should be presented only to hosts satisfying this domain name pattern.
      void setExpiryDate​(java.util.Date expiry)
      Sets the expiry date of the cookie.
      void setPath​(java.lang.String uri)
      This cookie should be presented only with requests beginning with this URL.
      void setSecure​(boolean flag)
      Indicates to the user agent that the cookie should only be sent using a secure protocol (https).
      void setValue​(java.lang.String newValue)
      Sets the value of the cookie.
      void setVersion​(int version)
      Sets the version of the cookie protocol used when this cookie saves itself.
      java.lang.String toString()
      Convert this cookie into a user friendly string.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • mName

        protected java.lang.String mName
        The name of the cookie.
      • mValue

        protected java.lang.String mValue
        The cookie value.
      • mComment

        protected java.lang.String mComment
        Describes the cookie's use.
      • mDomain

        protected java.lang.String mDomain
        Domain that sees cookie.
      • mExpiry

        protected java.util.Date mExpiry
        Cookie expires after this date.
      • mPath

        protected java.lang.String mPath
        URLs that see the cookie.
      • mSecure

        protected boolean mSecure
        Use SSL.
      • mVersion

        protected int mVersion
        If Version=1 it means RFC 2109++ style cookies.
    • Constructor Detail

      • Cookie

        public Cookie​(java.lang.String name,
                      java.lang.String value)
               throws java.lang.IllegalArgumentException
        Defines a cookie with an initial name/value pair. The name must be an HTTP/1.1 "token" value; alphanumeric ASCII strings work. Names starting with a "$" character are reserved by RFC 2109. The path for the cookie is set to the root ("/") and there is no expiry time set.
        Parameters:
        name - The name of the cookie.
        value - The value of the cookie.
        Throws:
        java.lang.IllegalArgumentException - if the cookie name is not an HTTP/1.1 "token", or if it is one of the tokens reserved for use by the cookie protocol
    • Method Detail

      • setComment

        public void setComment​(java.lang.String purpose)
        If a user agent (web browser) presents this cookie to a user, the cookie's purpose will be described using this comment. This is not supported by version zero cookies.
        Parameters:
        purpose - The cookie comment.
        See Also:
        getComment()
      • getComment

        public java.lang.String getComment()
        Returns the comment describing the purpose of this cookie, or null if no such comment has been defined.
        Returns:
        The cookie comment, or null if none.
        See Also:
        setComment(java.lang.String)
      • setDomain

        public void setDomain​(java.lang.String pattern)
        This cookie should be presented only to hosts satisfying this domain name pattern. Read RFC 2109 for specific details of the syntax. Briefly, a domain name name begins with a dot (".foo.com") and means that hosts in that DNS zone ("www.foo.com", but not "a.b.foo.com") should see the cookie. By default, cookies are only returned to the host which saved them.
        Parameters:
        pattern - The domain name pattern. The pattern is converted to lower case to accommodate less capable browsers.
        See Also:
        getDomain()
      • getDomain

        public java.lang.String getDomain()
        Returns the domain of this cookie.
        Returns:
        The cookie domain (the base URL name it applies to).
        See Also:
        setDomain(java.lang.String)
      • setExpiryDate

        public void setExpiryDate​(java.util.Date expiry)
        Sets the expiry date of the cookie. The cookie will expire after the date specified. A null value indicates the default behaviour: the cookie is not stored persistently, and will be deleted when the user agent (web browser) exits.
        Parameters:
        expiry - The expiry date for this cookie, or null if the cookie is persistent.
        See Also:
        getExpiryDate()
      • getExpiryDate

        public java.util.Date getExpiryDate()
        Returns the expiry date of the cookie. If none was specified, null is returned, indicating the default behaviour described with setExpiryDate.
        Returns:
        The cookie expiry date, or null if it is persistent.
        See Also:
        setExpiryDate(java.util.Date)
      • setPath

        public void setPath​(java.lang.String uri)
        This cookie should be presented only with requests beginning with this URL. Read RFC 2109 for a specification of the default behaviour. Basically, URLs in the same "directory" as the one which set the cookie, and in subdirectories, can all see the cookie unless a different path is set.
        Parameters:
        uri - The exclusion prefix for the cookie.
        See Also:
        getPath()
      • getPath

        public java.lang.String getPath()
        Returns the prefix of all URLs for which this cookie is targetted.
        Returns:
        The cookie path (or "/" if no specific path is specified).
        See Also:
        setPath(java.lang.String)
      • setSecure

        public void setSecure​(boolean flag)
        Indicates to the user agent that the cookie should only be sent using a secure protocol (https). This should only be set when the cookie's originating server used a secure protocol to set the cookie's value.
        Parameters:
        flag - Use true if the cookie is to be sent using secure protocols, false otherwise.
        See Also:
        getSecure()
      • getSecure

        public boolean getSecure()
        Returns the value of the 'secure' flag.
        Returns:
        The true if this cookie should only be sent using a secure protocol, false otherwise.
        See Also:
        setSecure(boolean)
      • getName

        public java.lang.String getName()
        Returns the name of the cookie. This name may not be changed after the cookie is created.
        Returns:
        The name of the cookie.
      • setValue

        public void setValue​(java.lang.String newValue)
        Sets the value of the cookie. BASE64 encoding is suggested for use with binary values.

        With version zero cookies, you need to be careful about the kinds of values you use. Values with various special characters (whitespace, brackets and parentheses, the equals sign, comma, double quote, slashes, question marks, the "at" sign, colon, and semicolon) should be avoided. Empty values may not behave the same way on all browsers.

        Parameters:
        newValue - The new value for the cookie.
        See Also:
        getValue()
      • getValue

        public java.lang.String getValue()
        Returns the value of the cookie.
        Returns:
        The cookie value.
        See Also:
        setValue(java.lang.String)
      • getVersion

        public int getVersion()
        Returns the version of the cookie. Version 1 complies with RFC 2109, version 0 indicates the original version, as specified by Netscape. Newly constructed cookies use version 0 by default, to maximize interoperability. Cookies provided by a user agent will identify the cookie version used by the browser.
        Returns:
        The cookie version.
        See Also:
        setVersion(int)
      • setVersion

        public void setVersion​(int version)
        Sets the version of the cookie protocol used when this cookie saves itself. Since the IETF standards are still being finalized, consider version 1 as experimental; do not use it (yet) on production sites.
        Parameters:
        version - The version of the cookie, either 0 or 1.
        See Also:
        getVersion()
      • clone

        public java.lang.Object clone()
        Returns a copy of this object.
        Overrides:
        clone in class java.lang.Object
        Returns:
        The clone of this cookie.
      • toString

        public java.lang.String toString()
        Convert this cookie into a user friendly string.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A short form string representing this cookie.