java.net
类 HttpCookie

java.lang.Object
  java.net.HttpCookie

所有已实现的接口：

Cloneable

public final class HttpCookie
extends Object
implements Cloneable

HttpCookie 对象表示一个 http cookie，该 cookie 带有服务器和用户代理之间的状态信息。广泛采用 Cookie 来创建有状态 (stateful) 会话。

有 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

构造方法摘要

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

方法摘要

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；如果浏览器可以使用任何协议发送 cookie，则返回 false。
String	getValue() 返回 cookie 的值。
int	getVersion() 返回此 cookie 遵守的协议版本。
boolean	hasExpired() 报告此 http cookie 是否已过期。
int	hashCode() 返回此 http cookie 的哈希码。
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	setMaxAge(long expiry) 设置 cookie 的最大生存时间，以秒为单位。
void	setPath(String uri) 指定客户机应该返回 cookie 的路径。
void	setPortlist(String ports) 指定 cookie 的端口列表，该列表在 Cookie 头中限制可能将 cookie 发送回的端口。
void	setSecure(boolean flag) 指示浏览器是否只能使用安全协议（如 HTTPS 或 SSL）发送 cookie。
void	setValue(String newValue) 在创建 cookie 之后将新值分配给 cookie。
void	setVersion(int v) 设置此 cookie 遵守的 cookie 协议版本。
String	toString() 构造此 cookie 的一个 cookie 头字符串表示形式，其格式为对应的 cookie 规范定义的格式，但没有前导 "Cookie:" 标记。

从类 java.lang.Object 继承的方法

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

构造方法详细信息

HttpCookie

public HttpCookie(String name,
                  String value)

构造带有指定名称和值的 cookie。

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

该值可以是服务器选择发送的任何值。可能只有该服务器需要其值。cookie 的值在使用 setValue 方法创建后可以更改。

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

参数：

name - 指定 cookie 名称的 String

value - 指定 cookie 值的 String

抛出：

IllegalArgumentException - 如果 cookie 名称包含非法字符，或者它是保留给 cookie 协议使用的标记之一

NullPointerException - 如果 name 为 null

另请参见：

setValue(java.lang.String), setVersion(int)

方法详细信息

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 名称包含非法字符；或者 cookie 名称是保留给 cookie 协议使用的标记之一

NullPointerException - 如果头字符串为 null

hasExpired

public boolean hasExpired()

报告此 http cookie 是否已过期。

返回：

如果此 http cookie 已过期，则返回 true；否则返回 false

setComment

public void setComment(String purpose)

指定一个描述 cookie 用途的注释。如果浏览器向用户显示 cookie，则注释很有用。Netscape Version 0 cookie 不支持注释。

参数：

purpose - 一个 String，指定要显示给用户的注释

另请参见：

getComment()

getComment

public String getComment()

返回描述此 cookie 用途的注释；如果该 cookie 没有注释，则返回 null。

返回：

包含注释的 String；如果没有注释，则返回 null

另请参见：

setComment(java.lang.String)

setCommentURL

public void setCommentURL(String purpose)

指定一个描述 cookie 用途的注释 URL。如果浏览器向用户显示 cookie，则注释 URL 很有用。只有 RFC 2965 支持注释 URL。

参数：

purpose - 一个 String，指定要显示给用户的注释 URL

另请参见：

getCommentURL()

getCommentURL

public String getCommentURL()

返回描述此 cookie 用途的注释 URL；如果 cookie 没有注释 URL，则返回 null。

返回：

包含注释 URL 的 String；如果没有，则返回 null

另请参见：

setCommentURL(java.lang.String)

setDiscard

public void setDiscard(boolean discard)

指定用户代理是否应该无条件丢弃 cookie。只有 RFC 2965 支持此属性。

参数：

discard - true 表示无条件丢弃 cookie

另请参见：

getDiscard()

getDiscard

public boolean getDiscard()

返回 cookie 的丢弃属性

返回：

表示此 cookie 丢弃属性的 boolean 值。

另请参见：

setDiscard(boolean)

setPortlist

public void setPortlist(String ports)

指定 cookie 的端口列表，该列表在 Cookie 头中限制可能将 cookie 发送回的端口。

参数：

ports - 指定端口列表的 String，它是以逗号分隔的数字序列

另请参见：

getPortlist()

getPortlist

public String getPortlist()

返回 cookie 的端口列表属性

返回：

包含端口列表的 String；如果没有，则返回 null

另请参见：

setPortlist(java.lang.String)

setDomain

public void setDomain(String pattern)

指定应在其中显示此 cookie 的域。

RFC 2965 指定了域名的形式。域名以点 (.foo.com) 开头，意味着在指定域名系统（Domain Name System，DNS）区域中（例如，www.foo.com，但不是 a.b.foo.com）cookie 对于服务器是可见的。默认情况下，cookie 只返回给发送它们的服务器。

参数：

pattern - 包含域名（在其中此 cookie 可见）的 String；域名形式符合 RFC 2965

另请参见：

getDomain()

getDomain

public String getDomain()

返回为此 cookie 设置的域名。域名的形式根据 RFC 2965 设置。

返回：

包含域名的 String

另请参见：

setDomain(java.lang.String)

setMaxAge

public void setMaxAge(long expiry)

设置 cookie 的最大生存时间，以秒为单位。

正值表示 cookie 将在经过该值表示的秒数后过期。注意，该值是 cookie 过期的最大 生存时间，不是 cookie 的当前生存时间。

负值意味着 cookie 不会被持久存储，将在 Web 浏览器退出时删除。0 值会导致删除 cookie。

参数：

expiry - 指定 cookie 最大生存时间的整数，以秒为单位；如果为 0，则应立即丢弃 cookie；否则，cookie 的最大生存时间没有指定。

另请参见：

getMaxAge()

getMaxAge

public long getMaxAge()

返回以秒为单位指定的 cookie 最大生存时间。默认情况下，-1 表示 cookie 将保留到浏览器关闭为止。

返回：

指定 cookie 最大生存时间的整数，以秒为单位

另请参见：

setMaxAge(long)

setPath

public void setPath(String uri)

指定客户机应该返回 cookie 的路径。

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

有关设置 cookie 路径名称的更多信息，请参考 RFC 2965（可从 Internet 上获得）。

参数：

uri - 指定路径的 String

另请参见：

getPath()

getPath

public String getPath()

返回浏览器将此 cookie 返回到的服务器上的路径。cookie 对于服务器上的所有子路径都是可见的。

返回：

指定包含 servlet 名称的路径的 String，例如 /catalog

另请参见：

setPath(java.lang.String)

setSecure

public void setSecure(boolean flag)

指示浏览器是否只能使用安全协议（如 HTTPS 或 SSL）发送 cookie。

默认值为 false。

参数：

flag - 如果为 true，则仅在使用安全协议时将 cookie 从浏览器发送到使用的服务器；如果为 false，则在任何协议上都可以发送

另请参见：

getSecure()

getSecure

public boolean getSecure()

如果浏览器仅通过安全协议发送 cookie，则返回 true；如果浏览器可以使用任何协议发送 cookie，则返回 false。

返回：

如果浏览器可以使用任何标准协议，则返回 true；否则返回 false

另请参见：

setSecure(boolean)

getName

public String getName()

返回 cookie 的名称。名称在创建之后不得更改。

返回：

指定 cookie 名称的 String

setValue

public void setValue(String newValue)

在创建 cookie 之后将新值分配给 cookie。如果使用二进制值，则可能需要使用 BASE64 编码。

对于 Version 0 cookie，值不应包含空格、方括号、圆括号、等号、逗号、双引号、斜杠、问号、at 符号、冒号和分号。空值在所有浏览器上的行为不一定相同。

参数：

newValue - 指定新值的 String

另请参见：

getValue()

getValue

public String getValue()

返回 cookie 的值。

返回：

包含 cookie 当前值的 String

另请参见：

setValue(java.lang.String)

getVersion

public int getVersion()

返回此 cookie 遵守的协议版本。版本 1 遵守 RFC 2965/2109，版本 0 遵守 Netscape 起草的原始 cookie 规范。浏览器提供的 cookie 使用并标识该浏览器的 cookie 版本。

返回：

如果 cookie 遵守原始 Netscape 规范，则返回 0；如果 cookie 遵守 RFC 2965/2109，则返回 1

另请参见：

setVersion(int)

setVersion

public void setVersion(int v)

设置此 cookie 遵守的 cookie 协议版本。版本 0 遵守原始 Netscape cookie 规范。版本 1 遵守 RFC 2965/2109。

参数：

v - 如果 cookie 应该遵守原始 Netscape 规范，则 v 为 0；如果 cookie 应该遵守 RFC 2965/2109，则 v 为 1

抛出：

IllegalArgumentException - 如果 v 既不为 0，也不为 1

另请参见：

getVersion()

domainMatches

public static boolean domainMatches(String domain,
                                    String host)

检查主机名是否在域中的实用方法。

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

有效主机名 = hostname（如果主机名包含圆点）
或者 = hostname.local（如果主机名不包含圆点）

如果符合以下条件，则主机 A 的名称在域上匹配主机 B 的名称：

• 它们的主机名字符串在字符串上的比较是相同的；或者
• A 是一个 HDN 字符串，且形式为 NB，其中 N 是一个非空名称字符串，B 的形式为 .B'，B'是一个 HDN 字符串。（因此，x.y.com 在域上匹配 .Y.com，但不匹配 Y.com。）

如果符合以下条件，则主机不在域中（RFC 2965 第 3.3.2 节）：

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

示例：

• 对于 Domain=.foo.com，来自请求主机 y.x.foo.com 的 Set-Cookie2 将被拒绝，因为 H 是 y.x，包含一个圆点。
• 对于 Domain=.foo.com，来自请求主机 x.foo.com 的 Set-Cookie2 将被接受。
• 带有 Domain=.com 或 Domain=.com. 的 Set-Cookie2 将始终被拒绝，因为没有嵌入的圆点。
• 带有 Domain=ajax.com 的 Set-Cookie2 将被接受，Domain 的值将被赋予 .ajax.com，因为在值前面加了一个圆点。
• 对于 Domain=.local，来自请求主机示例的 Set-Cookie2 将被接受，因为请求主机的有效主机名是 example.local，example.local 在域上匹配 .local。

参数：

domain - 要用于检查主机名的域名

host - 相关主机名

返回：

如果它们在域上匹配，则返回 true；如果不匹配，则返回 false

toString

public String toString()

构造此 cookie 的一个 cookie 头字符串表示形式，其格式为对应的 cookie 规范定义的格式，但没有前导 "Cookie:" 标记。

覆盖：

类 Object 中的 toString

返回：

cookie 的字符串形式。该字符串具有定义的格式

equals

public boolean equals(Object obj)

测试两个 http cookie 的相等性。

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

覆盖：

类 Object 中的 equals

参数：

obj - 要与之比较的引用对象。

返回：

如果两个 http cookie 彼此相等，则返回 true；否则，返回 false

另请参见：

Object.hashCode(), Hashtable

hashCode

public int hashCode()

返回此 http cookie 的哈希码。结果是此 cookie 以下三个重要部分的哈希码值之和：名称 (name)、域 (domain) 和路径 (path)。也就是说，哈希码就是以下表达式的值：

getName().toLowerCase().hashCode()
+ getDomain().toLowerCase().hashCode()
+ getPath().hashCode()

覆盖：

类 Object 中的 hashCode

返回：

此 http cookie 的哈希码

另请参见：

Object.equals(java.lang.Object), Hashtable

clone

public Object clone()

创建并返回此对象的一个副本。

覆盖：

类 Object 中的 clone

返回：

此 http cookie 的一个副本

另请参见：

Cloneable