鸿蒙OS HttpCookie

HttpCookie

java.lang.Object

|---java.net.HttpCookie

public final class HttpCookie
extends Object
implements Cloneable

一个 HttpCookie 对象代表一个 HTTP cookie，它携带服务器和用户代理之间的状态信息。 Cookie 被广泛用于创建有状态会话。

有 3 个 HTTP cookie 规范：

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

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

构造函数摘要

构造函数	描述
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；如果可以使用任何协议发送，则返回 false。
String	getValue()	返回 cookie 的值。
int	getVersion()	返回此 cookie 遵守的协议版本。
boolean	hasExpired()	报告此 HTTP cookie 是否已过期。
int	hashCode()	返回此 HTTP cookie 的哈希码。
boolean	isHttpOnly()	如果此 cookie 包含 HttpOnly 属性，则返回 true。
static ListHttpCookie	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 返回到的 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 方法进行更改。

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

参数：

参数名称	参数描述
name	一个字符串，指定 cookie 的名称
value	一个字符串，指定 cookie 的值

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果 cookie 名称包含非法字符
NullPointerException	如果名称为空

方法详情

parse

public static ListHttpCookie parse(String header)

从 set-cookie 或 set-cookie2 标头字符串构造 cookie。 RFC 2965 第 3.2.2 节 set-cookie2 语法表示一个标题行可能包含多个 cookie 定义，因此这是一种静态实用程序方法，而不是另一个构造函数。

参数：

参数名称	参数描述
header	指定 set-cookie 标头的字符串。 标头应以“set-cookie”或“set-cookie2”标记开头； 或者它根本不应该有前导标记。

返回:

从标题行字符串解析的 cookie 列表

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果标头字符串违反 cookie 规范的语法或 cookie 名称包含非法字符。
NullPointerException	如果标题字符串为空

hasExpired

public boolean hasExpired()

报告此 HTTP cookie 是否已过期。

返回:

true 表示此 HTTP cookie 已过期； 否则为false

setComment

public void setComment(String purpose)

指定描述 cookie 用途的注释。 如果浏览器将 cookie 呈现给用户，则该注释很有用。 Netscape 版本 0 cookie 不支持注释。

参数：

参数名称	参数描述
purpose	一个字符串，指定要向用户显示的评论

getComment

public String getComment()

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

返回:

包含评论的字符串，如果没有，则返回 null

setCommentURL

public void setCommentURL(String purpose)

指定描述 cookie 用途的评论 URL。 如果浏览器将 cookie 呈现给用户，则评论 URL 很有用。 评论 URL 仅为 RFC 2965。

参数：

参数名称	参数描述
purpose	一个字符串，指定要向用户显示的评论 URL

getCommentURL

public String getCommentURL()

返回描述此 cookie 用途的评论 URL，如果 cookie 没有评论 URL，则返回 null。

返回:

包含评论 URL 的字符串，如果没有则返回 null

setDiscard

public void setDiscard(boolean discard)

指定用户代理是否应无条件丢弃 cookie。 这是 RFC 2965 唯一的属性。

参数：

参数名称	参数描述
discard	true 表示无条件丢弃cookie

getDiscard

public boolean getDiscard()

返回 cookie 的丢弃属性

返回:

表示此 cookie 的丢弃属性的布尔值

setPortlist

public void setPortlist(String ports)

指定 cookie 的端口列表，它限制 cookie 可以在 Cookie 标头中发送回的端口。

参数：

参数名称	参数描述
ports	一个字符串指定端口列表，它是逗号分隔的一系列数字

getPortlist

public String getPortlist()

返回 cookie 的端口列表属性

返回:

字符串包含端口列表，如果没有则为 null

setDomain

public void setDomain(String pattern)

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

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

参数：

参数名称	参数描述
pattern	一个字符串，其中包含此 cookie 可见的域名； 表格符合 RFC 2965

getDomain

public String getDomain()

返回为此 cookie 设置的域名。 域名的格式由 RFC 2965 设置。

返回:

包含域名的字符串

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 的路径必须包含设置 cookie 的 servlet，例如 /catalog，它使 cookie 对服务器上 /catalog 下的所有目录可见。

参数：

参数名称	参数描述
uri	指定路径的字符串

getPath

public String getPath()

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

返回:

一个字符串，指定包含 servlet 名称的路径，例如 /catalog

setSecure

public void setSecure(boolean flag)

指示是否应仅使用安全协议（例如 HTTPS 或 SSL）发送 cookie。

默认值为假。

参数：

参数名称	参数描述
flag	如果为 true，则 cookie 只能通过 HTTPS 等安全协议发送。 如果为 false，则可以通过任何协议发送。

getSecure

public boolean getSecure()

如果发送此 cookie 应限制为安全协议，则返回 true；如果可以使用任何协议发送，则返回 false。

返回：

如果 cookie 可以通过任何标准协议发送，则为 false； 否则为true

getName

public String getName()

返回 cookie 的名称。 创建后无法更改名称。

返回:

指定 cookie 名称的字符串

setValue

public void setValue(String newValue)

创建 cookie 后为 cookie 分配一个新值。 如果您使用二进制值，您可能需要使用 BASE64 编码。

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

参数：

参数名称	参数描述
newValue	指定新值的字符串

getValue

public String getValue()

返回 cookie 的值。

返回:

包含 cookie 的当前值的字符串

getVersion

public int getVersion()

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

返回:

如果 cookie 符合原始 Netscape 规范，则为 0； 1 如果 cookie 符合 RFC 2965/2109

setVersion

public void setVersion(int v)

设置此 cookie 遵守的 cookie 协议的版本。 版本 0 符合最初的 Netscape cookie 规范。 版本 1 符合 RFC 2965/2109。

参数：

参数名称	参数描述
v	0 如果 cookie 应该符合原始的 Netscape 规范； 1 如果 cookie 应符合 RFC 2965/2109

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果 v 既不是 0 也不是 1

isHttpOnly

public boolean isHttpOnly()

如果此 cookie 包含 HttpOnly 属性，则返回 true。 这意味着脚本引擎（如 javascript）不应访问 cookie。

返回:

如果此 cookie 应被视为 HTTPOnly，则为 true

setHttpOnly

public void setHttpOnly(boolean httpOnly)

指示是否应将 cookie 视为仅 HTTP。 如果设置为 true，则意味着 cookie 不应被 javascript 等脚本引擎访问。

参数：

参数名称	参数描述
httpOnly	如果为 true，则使 cookie 仅 HTTP，即仅作为 HTTP 请求的一部分可见。

domainMatches

public static boolean domainMatches(String domain, String host)

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

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

如果主机名包含点，则有效主机名 = 主机名；如果不包含点，则 = hostname.local

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

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

如果出现以下情况，主机不在域中（RFC 2965 sec. 3.3.2）：

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

例子:

• 来自请求主机 y.x.foo.com 的 Domain=.foo.com 的 Set-Cookie2 将被拒绝，因为 H 是 y.x 并且包含一个点。
• 来自请求主机 x.foo.com 的 Set-Cookie2 用于 Domain=.foo.com 将被接受。
• 带有 Domain=.com 或 Domain=.com. 的 Set-Cookie2 将始终被拒绝，因为没有嵌入的点。
• 将接受来自 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 来自同一个域（不区分大小写）、具有相同名称（不区分大小写）和具有相同路径（区分大小写）时，结果才为真。

覆盖：

类 Object 中的等于

参数：

参数名称	参数描述
obj	要与之比较的参考对象。

返回:

如果两个 HTTP cookie 相等，则为 true； 否则为假

hashCode

public int hashCode()

返回此 HTTP cookie 的哈希码。 结果是此 cookie 的三个重要组成部分的哈希码值的总和：名称、域和路径。 也就是说，哈希码是表达式的值：

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

覆盖：

类 Object 中的 hashCode

返回:

这个 HTTP cookie 的哈希码

clone

public Object clone()

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

覆盖：

在类 Object 中克隆

返回:

此 HTTP cookie 的克隆