Module java.base
Package java.net

Class HttpCookie

java.lang.Object
java.net.HttpCookie
所有实现的接口:
Cloneable
public final class HttpCookie extends Object implements Cloneable
HttpCookie对象表示一个HTTP cookie，用于在服务器和用户代理之间传递状态信息。 Cookie被广泛采用以创建有状态的会话。

有3种HTTP cookie规范：

Netscape草案
RFC 2109 - http://www.ietf.org/rfc/rfc2109.txt
RFC 2965 - http://www.ietf.org/rfc/rfc2965.txt

HttpCookie类可以接受这3种形式的语法。

自从:
1.6
外部规范

  • Constructor Summary

    Constructors
    Constructor
    Description
    HttpCookie(String name, String value)
    构造具有指定名称和值的cookie。

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    clone()
    创建并返回此对象的副本。
    static boolean
    domainMatches(String domain, String host)
    检查主机名是否在域中的实用方法。
    boolean
    equals(Object obj)
    测试两个HTTP cookie的相等性。
    String
    getComment()
    返回描述此cookie目的的注释，如果cookie没有注释则返回null。
    String
    getCommentURL()
    返回描述此cookie目的的注释URL，如果cookie没有注释URL则返回null。
    boolean
    getDiscard()
    返回cookie的丢弃属性。
    String
    getDomain()
    返回为此cookie设置的域名。
    long
    getMaxAge()
    返回cookie的最大年龄，以秒为单位指定。
    String
    getName()
    返回cookie的名称。
    String
    getPath()
    返回浏览器返回此cookie的服务器上的路径。
    String
    getPortlist()
    返回cookie的端口列表属性。
    boolean
    getSecure()
    如果应限制发送此cookie到安全协议，则返回true，否则返回false。
    String
    getValue()
    返回cookie的值。
    int
    getVersion()
    返回此cookie遵循的协议版本。
    boolean
    hasExpired()
    报告此HTTP cookie是否已过期。
    int
    hashCode()
    返回此HTTP cookie的哈希码。
    boolean
    isHttpOnly()
    如果此cookie包含HttpOnly属性，则返回true。
    static List<HttpCookie>
    parse(String header)
    从set-cookie或set-cookie2头字符串构造cookie。
    void
    setComment(String purpose)
    指定描述cookie目的的注释。
    void
    setCommentURL(String purpose)
    指定描述cookie目的的注释URL。
    void
    setDiscard(boolean discard)
    指定用户代理是否应无条件丢弃cookie。
    void
    setDomain(String pattern)
    指定应呈现此cookie的域。
    void
    setHttpOnly(boolean httpOnly)
    指示cookie是否应被视为仅HTTP。
    void
    setMaxAge(long expiry)
    设置cookie的最大年龄（以秒为单位）。
    void
    setPath(String uri)
    为客户端应返回cookie的路径指定路径。
    void
    setPortlist(String ports)
    指定cookie的端口列表，限制可以在Cookie头中发送回的端口。
    void
    setSecure(boolean flag)
    指示cookie是否只能使用安全协议发送，如HTTPS或SSL。
    void
    setValue(String newValue)
    在创建cookie后为cookie分配新值。
    void
    setVersion(int v)
    设置此cookie遵循的cookie协议版本。
    String
    toString()
    构造此cookie的cookie头字符串表示形式，格式由相应的cookie规范定义，但不包括前导的"Cookie:"标记。

    Methods declared in class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • HttpCookie

      public HttpCookie(String name, String value)
      构造具有指定名称和值的cookie。

      名称必须符合RFC 2965。这意味着它只能包含ASCII字母数字字符，不能包含逗号、分号或空格，也不能以$字符开头。创建后无法更改cookie的名称。

      值可以是服务器选择发送的任何内容。其值可能只对服务器感兴趣。可以使用setValue方法在创建后更改cookie的值。

      默认情况下，cookie根据RFC 2965 cookie规范创建。版本可以使用setVersion方法更改。

      参数:
      name - 指定cookie的名称的String
      value - 指定cookie的值的String
      抛出:
      IllegalArgumentException - 如果cookie名称包含非法字符
      NullPointerException - 如果name为null
      参见:

  • Method Details

    • parse

      public static List<HttpCookie> parse(String header)
      从set-cookie或set-cookie2头字符串构造cookie。RFC 2965第3.2.2节set-cookie2语法指示一行头可能包含多个cookie定义，因此这是一个静态实用方法，而不是另一个构造函数。
      参数:
      header - 指定set-cookie头的String。头应以"set-cookie"或"set-cookie2"标记开头；或者根本没有前导标记。
      返回:
      从头行字符串解析的cookie列表
      抛出:
      IllegalArgumentException - 如果头字符串违反cookie规范的语法或cookie名称包含非法字符。
      NullPointerException - 如果头字符串为null

    • hasExpired

      public boolean hasExpired()
      报告此HTTP cookie是否已过期。
      返回:
      true表示此HTTP cookie已过期；否则，返回false

    • setComment

      public void setComment(String purpose)
      指定描述cookie目的的注释。如果浏览器向用户呈现cookie，则注释很有用。 Netscape版本0 cookie不支持注释。
      参数:
      purpose - 指定要显示给用户的注释的String
      参见:

    • getComment

      public String getComment()
      返回描述此cookie目的的注释，如果cookie没有注释则返回null。
      返回:
      包含注释的String，如果没有则返回null
      参见:

    • setCommentURL

      public void setCommentURL(String purpose)
      指定描述cookie目的的注释URL。如果浏览器向用户呈现cookie，则注释URL很有用。仅适用于RFC 2965。
      参数:
      purpose - 指定要显示给用户的注释URL的String
      参见:

    • getCommentURL

      public String getCommentURL()
      返回描述此cookie目的的注释URL，如果cookie没有注释URL则返回null。
      返回:
      包含注释URL的String，如果没有则返回null
      参见:

    • setDiscard

      public void setDiscard(boolean discard)
      指定用户代理是否应无条件丢弃cookie。仅适用于RFC 2965。
      参数:
      discard - true表示无条件丢弃cookie
      参见:

    • getDiscard

      public boolean getDiscard()
      返回cookie的丢弃属性。
      返回:
      一个boolean表示此cookie的丢弃属性
      参见:

    • setPortlist

      public void setPortlist(String ports)
      指定cookie的端口列表，限制可以在Cookie头中发送回的端口。
      参数:
      ports - 指定端口列表的String，逗号分隔的数字系列
      参见:

    • getPortlist

      public String getPortlist()
      返回cookie的端口列表属性。
      返回:
      包含端口列表的String，如果没有则返回null
      参见:

    • setDomain

      public void setDomain(String pattern)
      指定应呈现此cookie的域。

      域名的形式由RFC 2965指定。域名以点号（.foo.com）开头，表示cookie对指定域名系统（DNS）区域中的服务器可见（例如，www.foo.com，但不包括a.b.foo.com）。默认情况下，cookie仅返回给发送它们的服务器。

      参数:
      pattern - 包含此cookie可见的域名的String；形式根据RFC 2965规定
      参见:

    • getDomain

      public String getDomain()
      返回为此cookie设置的域名。域名的形式由RFC 2965设置。
      返回:
      包含域名的String
      参见:

    • setMaxAge

      public void setMaxAge(long expiry)
      设置cookie的最大存活时间，单位为秒。

      正值表示cookie将在指定秒数后过期。请注意，该值是cookie将过期的最大年龄，而不是cookie的当前年龄。

      负值表示cookie不会被持久存储，并且将在Web浏览器退出时被删除。零值会导致cookie被删除。

      参数:
      expiry - 一个整数，指定cookie的最大存活时间（秒）；如果为零，则应立即丢弃cookie；否则，cookie的最大年龄未指定。
      参见:

    • getMaxAge

      public long getMaxAge()
      返回cookie的最大存活时间，以秒为单位。默认情况下，返回-1表示cookie将持久存在直到浏览器关闭。
      返回:
      一个整数，指定cookie的最大存活时间（秒）
      参见:

    • setPath

      public void setPath(String uri)
      指定客户端应返回cookie的路径。

      cookie对您指定目录中的所有页面可见，以及该目录的子目录中的所有页面。cookie的路径必须包括设置cookie的servlet，例如，/catalog，这将使cookie对/catalog下服务器上的所有目录可见。

      请参阅RFC 2965（可在互联网上找到）以获取有关为cookie设置路径名称的更多信息。

      参数:
      uri - 指定路径的String
      参见:

    • getPath

      public String getPath()
      返回浏览器返回此cookie的服务器路径。cookie对服务器上的所有子路径可见。
      返回:
      包含servlet名称的路径的String，例如，/catalog
      参见:

    • setSecure

      public void setSecure(boolean flag)
      指示是否仅使用安全协议（如HTTPS或SSL）发送cookie。

      默认值为false。

      参数:
      flag - 如果为true，则cookie只能通过安全协议（如HTTPS）发送。如果为false，则可以通过任何协议发送。
      参见:

    • getSecure

      public boolean getSecure()
      如果发送此cookie应限制为安全协议，则返回true；如果可以使用任何协议发送，则返回false。
      返回:
      如果cookie可以通过任何标准协议发送，则返回false；否则返回true
      参见:

    • getName

      public String getName()
      返回cookie的名称。创建后名称不可更改。
      返回:
      指定cookie名称的String

    • setValue

      public void setValue(String newValue)
      在创建cookie后为其分配新值。如果使用二进制值，可能需要使用BASE64编码。

      对于版本0的cookie，值不应包含空格、括号、等号、逗号、双引号、斜杠、问号、at符号、冒号和分号。空值在所有浏览器上的行为可能不同。

      参数:
      newValue - 指定新值的String
      参见:

    • getValue

      public String getValue()
      返回cookie的值。
      返回:
      包含cookie当前值的String
      参见:

    • getVersion

      public int getVersion()
      返回此cookie遵循的协议版本。版本1遵循RFC 2965/2109，版本0遵循Netscape起草的原始cookie规范。由浏览器提供的cookie使用并标识浏览器的cookie版本。
      返回:
      如果cookie遵循原始Netscape规范，则返回0；如果cookie遵循RFC 2965/2109，则返回1
      参见:

    • setVersion

      public void setVersion(int v)
      设置此cookie遵循的协议版本。版本0遵循原始Netscape cookie规范。版本1遵循RFC 2965/2109。
      参数:
      v - 如果cookie应遵循原始Netscape规范，则为0；如果cookie应遵循RFC 2965/2109，则为1
      抛出:
      IllegalArgumentException - 如果v既不是0也不是1
      参见:

    • isHttpOnly

      public boolean isHttpOnly()
      如果此cookie包含HttpOnly属性，则返回true。这意味着cookie不应该对脚本引擎（如JavaScript）可见。
      返回:
      如果此cookie应被视为HTTPOnly，则返回true
      参见:

    • setHttpOnly

      public void setHttpOnly(boolean httpOnly)
      指示是否应将cookie视为HTTP Only。如果设置为true，这意味着cookie不应该对脚本引擎（如JavaScript）可见。
      参数:
      httpOnly - 如果为true，则使cookie成为HTTP Only，即仅作为HTTP请求的一部分可见。
      参见:

    • domainMatches

      public static boolean domainMatches(String domain, String host)
      检查主机名是否属于域名的实用方法。

      此概念在cookie规范中有描述。要理解该概念，首先需要定义一些术语：

      有效主机名 = 如果主机名包含点，则为主机名
                        否则为主机名.local

      如果主机A的名称与主机B的名称匹配，则主机A的名称与主机B的名称匹配：

      • 它们的主机名字符串相等；或
      • A是HDN字符串，并且具有形式NB的形式，其中N是非空名称字符串，B具有形式.B'，B'是HDN字符串。（因此，x.y.com与.Y.com匹配，但与Y.com不匹配。）

      如果主机不在域中（RFC 2965第3.3.2节）：

      • 域属性的值不包含嵌入的点，并且该值不是.local。
      • 从请求主机派生的有效主机名与域属性不匹配。
      • 请求主机是HDN（不是IP地址），并且具有HD形式，其中D是域属性的值，H是包含一个或多个点的字符串。

      示例：

      • 来自请求主机y.x.foo.com的Set-Cookie2，域为.foo.com，将被拒绝，因为H为y.x，包含一个点。
      • 来自请求主机x.foo.com的Set-Cookie2，域为.foo.com，将被接受。
      • 具有域为.com或域为.com.的Set-Cookie2将始终被拒绝，因为没有嵌入的点。
      • 具有域为.local的Set-Cookie2，来自请求主机example，将被接受，因为请求主机的有效主机名为example.local，example.local与.local匹配。
      参数:
      domain - 用于检查主机名的域名
      host - 待检查的主机名
      返回:
      如果它们匹配域名，则返回true；否则返回false

    • toString

      public String toString()
      构造此cookie的cookie头字符串表示形式，格式符合相应cookie规范，但不包含前导的"Cookie:"标记。
      覆盖:
      toString 在类 Object
      返回:
      cookie的字符串形式。字符串具有定义的格式

    • equals

      public boolean equals(Object obj)
      测试两个HTTP cookie是否相等。

      仅当两个cookie来自相同域（不区分大小写）、具有相同名称（不区分大小写）和相同路径（区分大小写）时，结果为true。

      覆盖:
      equals 在类 Object
      参数:
      obj - 要比较的参考对象。
      返回:
      如果两个HTTP cookie相等，则返回true；否则返回false
      参见:

    • hashCode

      public int hashCode()
      返回此HTTP cookie的哈希码。结果是此cookie的三个重要组件的哈希码值之和：名称、域和路径。即，哈希码是以下表达式的值：
      getName().toLowerCase().hashCode()
      + getDomain().toLowerCase().hashCode()
      + getPath().hashCode()
      覆盖:
      hashCode 在类 Object
      返回:
      此HTTP cookie的哈希码
      参见:

    • clone

      public Object clone()
      创建并返回此对象的副本。
      覆盖:
      clone 在类 Object
      返回:
      此HTTP cookie的克隆
      参见: