Cookie (HttpClient Library (Version 3.1))
Date: 2019-09-02

org.apache.commons.httpclient

## Class Cookie

- java.lang.Object
- - org.apache.commons.httpclient.NameValuePair
  - - org.apache.commons.httpclient.Cookie

- All Implemented Interfaces:
    java.io.Serializable, java.util.Comparator
  Direct Known Subclasses:
    Cookie2

      public class Cookie
      extends NameValuePair
      implements java.io.Serializable, java.util.Comparator

  HTTP "magic-cookie" represents a piece of state information that the HTTP agent and the target server can exchange to maintain a session.

  Version:
    $Revision: 531354 $ $Date: 2007-04-23 08:53:20 +0200 (Mon, 23 Apr 2007) $
  Author:
    B.C. Holmes, Park, Sung-Gu, Doug Sale, Rod Waldhoff, dIon Gillard, Sean C. Sullivan, John Evans, Marc A. Saegesser, Oleg Kalnichevski, Mike Bowler
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Cookie()` Default constructor.
    `Cookie(java.lang.String domain, java.lang.String name, java.lang.String value)` Creates a cookie with the given name, value and domain attribute.
    `Cookie(java.lang.String domain, java.lang.String name, java.lang.String value, java.lang.String path, java.util.Date expires, boolean secure)` Creates a cookie with the given name, value, domain attribute, path attribute, expiration attribute, and secure attribute
    `Cookie(java.lang.String domain, java.lang.String name, java.lang.String value, java.lang.String path, int maxAge, boolean secure)` Creates a cookie with the given name, value, domain attribute, path attribute, maximum age attribute, and secure attribute

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compare(java.lang.Object o1, java.lang.Object o2)` Compares two cookies to determine order for cookie header.
    `boolean` | `equals(java.lang.Object obj)` Two cookies are equal if the name, path and domain match.
    `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 domain attribute of the cookie.
    `java.util.Date` | `getExpiryDate()` Returns the expiration `Date` of the cookie, or `null` if none exists.
    `java.lang.String` | `getPath()` Returns the path attribute of the cookie
    `boolean` | `getSecure()`
    `int` | `getVersion()` Returns the version of the cookie specification to which this cookie conforms.
    `int` | `hashCode()` Returns a hash code in keeping with the `Object.hashCode()` general hashCode contract.
    `boolean` | `isDomainAttributeSpecified()` Returns `true` if cookie's domain was set via a domain attribute in the `Set-Cookie` header.
    `boolean` | `isExpired()` Returns true if this cookie has expired.
    `boolean` | `isExpired(java.util.Date now)` Returns true if this cookie has expired according to the time passed in.
    `boolean` | `isPathAttributeSpecified()` Returns `true` if cookie's path was set via a path attribute in the `Set-Cookie` header.
    `boolean` | `isPersistent()` Returns `false` if the cookie should be discarded at the end of the "session"; `true` otherwise.
    `void` | `setComment(java.lang.String comment)` 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 domain)` Sets the domain attribute.
    `void` | `setDomainAttributeSpecified(boolean value)` Indicates whether the cookie had a domain specified in a domain attribute of the `Set-Cookie` header.
    `void` | `setExpiryDate(java.util.Date expiryDate)` Sets expiration date.
    `void` | `setPath(java.lang.String path)` Sets the path attribute.
    `void` | `setPathAttributeSpecified(boolean value)` Indicates whether the cookie had a path specified in a path attribute of the `Set-Cookie` header.
    `void` | `setSecure(boolean secure)` Sets the secure attribute of the cookie.
    `void` | `setVersion(int version)` Sets the version of the cookie specification to which this cookie conforms.
    `java.lang.String` | `toExternalForm()` Return a textual representation of the cookie.
    `java.lang.String` | `toString()` Return a textual representation of the cookie.

    - ### Methods inherited from class org.apache.commons.httpclient.NameValuePair

      `getName, getValue, setName, setValue`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.Comparator

      `comparing, comparing, comparingDouble, comparingInt, comparingLong, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong`

- - ### Constructor Detail

    - #### Cookie

          public Cookie()

      Default constructor. Creates a blank cookie

    - #### Cookie

          public Cookie(java.lang.String domain,
                        java.lang.String name,
                        java.lang.String value)

      Creates a cookie with the given name, value and domain attribute.
      Parameters:
        `name` - the cookie name
        `value` - the cookie value
        `domain` - the domain this cookie can be sent to

    - #### Cookie

          public Cookie(java.lang.String domain,
                        java.lang.String name,
                        java.lang.String value,
                        java.lang.String path,
                        java.util.Date expires,
                        boolean secure)

      Creates a cookie with the given name, value, domain attribute, path attribute, expiration attribute, and secure attribute
      Parameters:
        `name` - the cookie name
        `value` - the cookie value
        `domain` - the domain this cookie can be sent to
        `path` - the path prefix for which this cookie can be sent
        `expires` - the `Date` at which this cookie expires, or `null` if the cookie expires at the end of the session
        `secure` - if true this cookie can only be sent over secure connections
      Throws:
        `java.lang.IllegalArgumentException` - If cookie name is null or blank, cookie name contains a blank, or cookie name starts with character $

    - #### Cookie

          public Cookie(java.lang.String domain,
                        java.lang.String name,
                        java.lang.String value,
                        java.lang.String path,
                        int maxAge,
                        boolean secure)

      Creates a cookie with the given name, value, domain attribute, path attribute, maximum age attribute, and secure attribute
      Parameters:
        `name` - the cookie name
        `value` - the cookie value
        `domain` - the domain this cookie can be sent to
        `path` - the path prefix for which this cookie can be sent
        `maxAge` - the number of seconds for which this cookie is valid. maxAge is expected to be a non-negative number. `-1` signifies that the cookie should never expire.
        `secure` - if `true` this cookie can only be sent over secure connections

  - ### Method Detail

    - #### 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:
        comment
      See Also:
        `setComment(String)`

    - #### setComment

          public void setComment(java.lang.String comment)

      If a user agent (web browser) presents this cookie to a user, the cookie's purpose will be described using this comment.
      Parameters:
        `comment` -
      See Also:
        `getComment()`

    - #### getExpiryDate

          public java.util.Date getExpiryDate()

      Returns the expiration `Date` of the cookie, or `null` if none exists.

      Note: the object returned by this method is considered immutable. Changing it (e.g. using setTime()) could result in undefined behaviour. Do so at your peril.

      Returns:
        Expiration `Date`, or `null`.
      See Also:
        `setExpiryDate(java.util.Date)`

    - #### setExpiryDate

          public void setExpiryDate(java.util.Date expiryDate)

      Sets expiration date.

      Note: the object returned by this method is considered immutable. Changing it (e.g. using setTime()) could result in undefined behaviour. Do so at your peril.

      Parameters:
        `expiryDate` - the `Date` after which this cookie is no longer valid.
      See Also:
        `getExpiryDate()`

    - #### isPersistent

          public boolean isPersistent()

      Returns `false` if the cookie should be discarded at the end of the "session"; `true` otherwise.
      Returns:
        `false` if the cookie should be discarded at the end of the "session"; `true` otherwise

    - #### getDomain

          public java.lang.String getDomain()

      Returns domain attribute of the cookie.
      Returns:
        the value of the domain attribute
      See Also:
        `setDomain(java.lang.String)`

    - #### setDomain

          public void setDomain(java.lang.String domain)

      Sets the domain attribute.
      Parameters:
        `domain` - The value of the domain attribute
      See Also:
        `getDomain()`

    - #### getPath

          public java.lang.String getPath()

      Returns the path attribute of the cookie
      Returns:
        The value of the path attribute.
      See Also:
        `setPath(java.lang.String)`

    - #### setPath

          public void setPath(java.lang.String path)

      Sets the path attribute.
      Parameters:
        `path` - The value of the path attribute
      See Also:
        `getPath()`

    - #### getSecure

          public boolean getSecure()

      Returns:
        `true` if this cookie should only be sent over secure connections.
      See Also:
        `setSecure(boolean)`

    - #### setSecure

          public void setSecure(boolean secure)

      Sets the secure attribute of the cookie.

      When `true` 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:
        `secure` - The value of the secure attribute
      See Also:
        `getSecure()`

    - #### getVersion

          public int getVersion()

      Returns the version of the cookie specification to which this cookie conforms.
      Returns:
        the version of the cookie.
      See Also:
        `setVersion(int)`

    - #### setVersion

          public void setVersion(int version)

      Sets the version of the cookie specification to which this cookie conforms.
      Parameters:
        `version` - the version of the cookie.
      See Also:
        `getVersion()`

    - #### isExpired

          public boolean isExpired()

      Returns true if this cookie has expired.
      Returns:
        `true` if the cookie has expired.

    - #### isExpired

          public boolean isExpired(java.util.Date now)

      Returns true if this cookie has expired according to the time passed in.
      Parameters:
        `now` - The current time.
      Returns:
        `true` if the cookie expired.

    - #### setPathAttributeSpecified

          public void setPathAttributeSpecified(boolean value)

      Indicates whether the cookie had a path specified in a path attribute of the `Set-Cookie` header. This value is important for generating the `Cookie` header because some cookie specifications require that the `Cookie` header should only include a path attribute if the cookie's path was specified in the `Set-Cookie` header.
      Parameters:
        `value` - `true` if the cookie's path was explicitly set, `false` otherwise.
      See Also:
        `isPathAttributeSpecified()`

    - #### isPathAttributeSpecified

          public boolean isPathAttributeSpecified()

      Returns `true` if cookie's path was set via a path attribute in the `Set-Cookie` header.
      Returns:
        value `true` if the cookie's path was explicitly set, `false` otherwise.
      See Also:
        `setPathAttributeSpecified(boolean)`

    - #### setDomainAttributeSpecified

          public void setDomainAttributeSpecified(boolean value)

      Indicates whether the cookie had a domain specified in a domain attribute of the `Set-Cookie` header. This value is important for generating the `Cookie` header because some cookie specifications require that the `Cookie` header should only include a domain attribute if the cookie's domain was specified in the `Set-Cookie` header.
      Parameters:
        `value` - `true` if the cookie's domain was explicitly set, `false` otherwise.
      See Also:
        `isDomainAttributeSpecified()`

    - #### isDomainAttributeSpecified

          public boolean isDomainAttributeSpecified()

      Returns `true` if cookie's domain was set via a domain attribute in the `Set-Cookie` header.
      Returns:
        value `true` if the cookie's domain was explicitly set, `false` otherwise.
      See Also:
        `setDomainAttributeSpecified(boolean)`

    - #### hashCode

          public int hashCode()

      Returns a hash code in keeping with the `Object.hashCode()` general hashCode contract.
      Overrides:
        `hashCode` in class `NameValuePair`
      Returns:
        A hash code

    - #### equals

          public boolean equals(java.lang.Object obj)

      Two cookies are equal if the name, path and domain match.
      Specified by:
        `equals` in interface `java.util.Comparator`
      Overrides:
        `equals` in class `NameValuePair`
      Parameters:
        `obj` - The object to compare against.
      Returns:
        true if the two objects are equal.

    - #### toExternalForm

          public java.lang.String toExternalForm()

      Return a textual representation of the cookie.
      Returns:
        string.

    - #### compare

          public int compare(java.lang.Object o1,
                             java.lang.Object o2)

      Compares two cookies to determine order for cookie header.

      Most specific should be first.

      This method is implemented so a cookie can be used as a comparator for a SortedSet of cookies. Specifically it's used above in the createCookieHeader method.

      Specified by:
        `compare` in interface `java.util.Comparator`
      Parameters:
        `o1` - The first object to be compared
        `o2` - The second object to be compared
      Returns:
        See `Comparator.compare(Object,Object)`

    - #### toString

          public java.lang.String toString()

      Return a textual representation of the cookie.
      Overrides:
        `toString` in class `NameValuePair`
      Returns:
        string.
      See Also:
        `toExternalForm()`

Copyright (c) 1999-2005 - Apache Software Foundation