Class Cookie


  • public class Cookie
    extends java.lang.Object
    This class is used to represent a generic cookie. This exposes the fields that a cookie can have. By default the version of the Cookie is set to 1. The version can be configured using the setVersion method. The domain, path, security, and expiry of the cookie can also be set using their respective set methods.

    The toString method allows the Cookie to be converted back into text form. This text form converts the cookie according to the Set-Cookie header form. This is done so that a created Cookie instance can be converted to a string which can be used as a a HTTP header.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Cookie.CookieDate
      The CookieDate complies with the date format used by older browsers such as Internet Explorer and Netscape Navigator.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean created
      This is used to determine the the cookie is new.
      private Cookie.CookieDate date
      This is used to set the expiry date for the cookie.
      private java.lang.String domain
      Represents the value of the domain attribute.
      private int expiry
      Represents the duration in seconds of the cookie.
      private java.lang.String name
      The name attribute of this cookie instance.
      private java.lang.String path
      Represents the value of the path for this cookie.
      private boolean protect
      Determines whether the cookie should be protected.
      private boolean secure
      Determines whether the cookie should be secure.
      private java.lang.String value
      The value attribute of this cookie instance.
      private int version
      Represents the value of the version attribute.
    • Constructor Summary

      Constructors 
      Constructor Description
      Cookie​(java.lang.String name, java.lang.String value)
      Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109.
      Cookie​(java.lang.String name, java.lang.String value, boolean created)
      Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109.
      Cookie​(java.lang.String name, java.lang.String value, java.lang.String path)
      Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109.
      Cookie​(java.lang.String name, java.lang.String value, java.lang.String path, boolean created)
      Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getDomain()
      This returns the domain for this cookie.
      int getExpiry()
      This returns the number of seconds a cookie lives for.
      java.lang.String getName()
      This returns the name for this cookie.
      java.lang.String getPath()
      This returns the path for this cookie.
      java.lang.String getValue()
      This returns the value for this cookie.
      int getVersion()
      This returns the version for this cookie.
      boolean isNew()
      This is used to determine if the cookie is new.
      boolean isProtected()
      This is used to determine if the cookie is protected against cross site scripting.
      boolean isSecure()
      This determines whether the cookie is secure.
      void setDomain​(java.lang.String domain)
      This enables the domain for this Cookie to be set.
      void setExpiry​(int expiry)
      This allows a lifetime to be specified for the cookie.
      void setPath​(java.lang.String path)
      This is used to set the cookie path for this cookie.
      void setProtected​(boolean protect)
      This is used to protect the cookie from cross site scripting vulnerabilities.
      void setSecure​(boolean secure)
      This is used to determine if the client browser should send this cookie over a secure protocol.
      void setValue​(java.lang.String value)
      This enables the value of the cookie to be changed.
      void setVersion​(int version)
      This enables the version of the Cookie to be set.
      java.lang.String toClientString()
      This will give the correct string value of this cookie.
      java.lang.String toString()
      The toString method converts the cookie to the Set-Cookie value.
      • Methods inherited from class java.lang.Object

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

      • date

        private Cookie.CookieDate date
        This is used to set the expiry date for the cookie.
      • name

        private java.lang.String name
        The name attribute of this cookie instance.
      • value

        private java.lang.String value
        The value attribute of this cookie instance.
      • path

        private java.lang.String path
        Represents the value of the path for this cookie.
      • domain

        private java.lang.String domain
        Represents the value of the domain attribute.
      • secure

        private boolean secure
        Determines whether the cookie should be secure.
      • protect

        private boolean protect
        Determines whether the cookie should be protected.
      • created

        private boolean created
        This is used to determine the the cookie is new.
      • version

        private int version
        Represents the value of the version attribute.
      • expiry

        private int expiry
        Represents the duration in seconds of the cookie.
    • Constructor Detail

      • Cookie

        public Cookie​(java.lang.String name,
                      java.lang.String value)
        Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109. This contains none of the optional attributes, such as domain and path. These optional attributes can be set using the set methods.

        The name must conform to RFC 2109, which means that it can contain only ASCII alphanumeric characters and cannot have commas, white space, or semicolon characters.

        Parameters:
        name - this is the name of this cookie instance
        value - this is the value of this cookie instance
      • Cookie

        public Cookie​(java.lang.String name,
                      java.lang.String value,
                      boolean created)
        Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109. This contains none of the optional attributes, such as domain and path. These optional attributes can be set using the set methods.

        The name must conform to RFC 2109, which means that it can contain only ASCII alphanumeric characters and cannot have commas, white space, or semicolon characters.

        Parameters:
        name - this is the name of this cookie instance
        value - this is the value of this cookie instance
        created - this determines if the cookie is new
      • Cookie

        public Cookie​(java.lang.String name,
                      java.lang.String value,
                      java.lang.String path)
        Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109. This allows the path attribute to be specified for on construction. Other attributes can be set using the set methods provided.

        The name must conform to RFC 2109, which means that it can contain only ASCII alphanumeric characters and cannot have commas, white space, or semicolon characters.

        Parameters:
        name - this is the name of this cookie instance
        value - this is the value of this cookie instance
        path - the path attribute of this cookie instance
      • Cookie

        public Cookie​(java.lang.String name,
                      java.lang.String value,
                      java.lang.String path,
                      boolean created)
        Constructor of the Cookie that uses a default version of 1, which is used by RFC 2109. This allows the path attribute to be specified for on construction. Other attributes can be set using the set methods provided.

        The name must conform to RFC 2109, which means that it can contain only ASCII alphanumeric characters and cannot have commas, white space, or semicolon characters.

        Parameters:
        name - this is the name of this cookie instance
        value - this is the value of this cookie instance
        path - the path attribute of this cookie instance
        created - this determines if the cookie is new
    • Method Detail

      • isNew

        public boolean isNew()
        This is used to determine if the cookie is new. A cookie is considered new if it has just been created on the server. A cookie is considered not new if it has been received by the client in a request. This allows the server to determine if the cookie needs to be delivered to the client.
        Returns:
        this returns true if the cookie was just created
      • getVersion

        public int getVersion()
        This returns the version for this cookie. The version is not optional and so will always return the version this cookie uses. If no version number is specified this will return a version of 1, to comply with RFC 2109.
        Returns:
        the version value from this cookie instance
      • setVersion

        public void setVersion​(int version)
        This enables the version of the Cookie to be set. By default the version of the Cookie is set to 1. It is not advisable to set the version higher than 1, unless it is known that the client will accept it.

        Some old browsers can only handle cookie version 0. This can be used to comply with the original Netscape cookie specification. Version 1 complies with RFC 2109.

        Parameters:
        version - this is the version number for the cookie
      • getName

        public java.lang.String getName()
        This returns the name for this cookie. The name and value attributes of a cookie define what the Cookie is for, these values will always be present. These are mandatory for both the Cookie and Set-Cookie headers.

        Because the cookie may be stored by name, the cookie name cannot be modified after the creation of the cookie object.

        Returns:
        the name from this cookie instance object
      • getValue

        public java.lang.String getValue()
        This returns the value for this cookie. The name and value attributes of a cookie define what the Cookie is for, these values will always be present. These are mandatory for both the Cookie and Set-Cookie headers.
        Returns:
        the value from this cookie instance object
      • setValue

        public void setValue​(java.lang.String value)
        This enables the value of the cookie to be changed. This can be set to any value the server wishes to send. Cookie values can contain space characters as they are transmitted in quotes. For example a value of some value is perfectly legal. However for maximum compatibility across the different plaforms such as PHP, JavaScript and others, quotations should be avoided. If quotations are required they must be added to the string. For example a quoted value could be created as "some value".
        Parameters:
        value - this is the new value of this cookie object
      • isSecure

        public boolean isSecure()
        This determines whether the cookie is secure. The cookie is secure if it has the "secure" token set, as defined by RFC 2109. If this token is set then the cookie is only sent over secure channels such as SSL and TLS and ensures that a third party cannot intercept and spoof the cookie.
        Returns:
        this returns true if the "secure" token is set
      • setSecure

        public void setSecure​(boolean secure)
        This is used to determine if the client browser should send this cookie over a secure protocol. If this is true then the client browser should only send the cookie over secure channels such as SSL and TLS. This ensures that the value of the cookie cannot be intercepted by a third party.
        Parameters:
        secure - if true then the cookie should be secure
      • isProtected

        public boolean isProtected()
        This is used to determine if the cookie is protected against cross site scripting. It sets the HttpOnly value for the cookie. Setting this value ensures that the cookie is not available to some scripting attacks.
        Returns:
        this returns true if the cookie is protected
      • setProtected

        public void setProtected​(boolean protect)
        This is used to protect the cookie from cross site scripting vulnerabilities. If this is set to true the cookie will be protected by setting the HttpOnly value for the cookie. See RFC 6265 for more details on this value.
        Parameters:
        protect - this determines if the cookie is protected
      • getExpiry

        public int getExpiry()
        This returns the number of seconds a cookie lives for. This determines how long the cookie will live on the client side. If the expiry is less than zero the cookie lifetime is the duration of the client browser session, if it is zero then the cookie will be deleted from the client browser.
        Returns:
        returns the duration in seconds the cookie lives
      • setExpiry

        public void setExpiry​(int expiry)
        This allows a lifetime to be specified for the cookie. This will make use of the "max-age" token specified by RFC 2109 the specifies the number of seconds a browser should keep a cookie for. This is useful if the cookie is to be kept beyond the lifetime of the client session. If the value of this is zero then this will remove the client cookie, if it is less than zero then the "max-age" field is ignored.
        Parameters:
        expiry - the duration in seconds the cookie lives
      • getPath

        public java.lang.String getPath()
        This returns the path for this cookie. The path is in both the Cookie and Set-Cookie headers and so may return null if there is no domain value. If the toString or toClientString is invoked the path will not be present if the path attribute is null.
        Returns:
        this returns the path value from this cookie
      • setPath

        public void setPath​(java.lang.String path)
        This is used to set the cookie path for this cookie. This is set so that the cookie can specify the directories that the cookie is sent with. For example if the path attribute is set to /pub/bin, then requests for the resource http://hostname:port/pub/bin/README will be issued with this cookie. The cookie is issued for all resources in the path and all subdirectories.
        Parameters:
        path - this is the path value for this cookie object
      • getDomain

        public java.lang.String getDomain()
        This returns the domain for this cookie. The domain is in both the Cookie and Set-Cookie headers and so may return null if there is no domain value. If either the toString or toClientString is invoked the domain will not be present if this is null.
        Returns:
        this returns the domain value from this cookie
      • setDomain

        public void setDomain​(java.lang.String domain)
        This enables the domain for this Cookie to be set. The form of the domain is specified by RFC 2109. The value can begin with a dot, like .host.com. This means that the cookie is visible within a specific DNS zone like www.host.com. By default this value is null which means it is sent back to its origin.
        Parameters:
        domain - this is the domain value for this cookie
      • toClientString

        public java.lang.String toClientString()
        This will give the correct string value of this cookie. This will generate the cookie text with only the values that were given with this cookie. If there are no optional attributes like $Path or $Domain these are left blank. This returns the encoding as it would be for the HTTP Cookie header.
        Returns:
        this returns the Cookie header encoding of this
      • toString

        public java.lang.String toString()
        The toString method converts the cookie to the Set-Cookie value. This can be used to send the HTTP header to a client browser. This uses a format that has been tested with various browsers. This is required as some browsers do not perform flexible parsing of the Set-Cookie value.

        Netscape and IE-5.0 can't or wont handle Path it must be path also Netscape can not handle the path in quotations such as "/path" it must be /path. This value is never in quotations.

        For maximum compatibility cookie values are not transmitted in quotations. This is done to ensure that platforms like PHP, JavaScript and various others that don't comply with RFC 2109 can transparently access the sent cookies.

        When setting the expiry time for the cookie it is important to set the max-age and expires attributes so that IE-5.0 and up can understand them. Old versions of IE do not understand max-age.

        Overrides:
        toString in class java.lang.Object
        Returns:
        this returns a Set-Cookie encoding of the cookie