鴻蒙OS HttpCookie

HttpCookie

java.lang.Object

|---java.net.HttpCookie

public final class HttpCookie
extends Object
implements Cloneable

一個(gè) HttpCookie 對(duì)象代表一個(gè) HTTP cookie，它攜帶服務(wù)器和用戶代理之間的狀態(tài)信息。 Cookie 被廣泛用于創(chuàng)建有狀態(tài)會(huì)話。

有 3 個(gè) HTTP cookie 規(guī)范：

網(wǎng)景 RFC 2109 草案 - http://www.ietf.org/rfc/rfc2109.txt RFC 2965 -http://www.ietf.org/rfc/rfc2965.txt

HttpCookie 類可以接受所有這 3 種語(yǔ)法形式。

構(gòu)造函數(shù)摘要

構(gòu)造函數(shù)	描述
HttpCookie(String name, String value)	構(gòu)造一個(gè)具有指定名稱和值的 cookie。

方法總結(jié)

修飾符和類型	方法	描述
Object	clone()	創(chuàng)建并返回此對(duì)象的副本。
static boolean	domainMatches(String domain, String host)	檢查主機(jī)名是否在域中的實(shí)用方法。
boolean	equals(Object obj)	測(cè)試兩個(gè) HTTP cookie 的相等性。
String	getComment()	返回描述此 cookie 用途的注釋，如果 cookie 沒有注釋，則返回 null。
String	getCommentURL()	返回描述此 cookie 用途的評(píng)論 URL，如果 cookie 沒有評(píng)論 URL，則返回 null。
boolean	getDiscard()	返回 cookie 的丟棄屬性
String	getDomain()	返回為此 cookie 設(shè)置的域名。
long	getMaxAge()	返回 cookie 的最長(zhǎng)期限，以秒為單位。
String	getName()	返回 cookie 的名稱。
String	getPath()	返回瀏覽器將此 cookie 返回到的服務(wù)器上的路徑。
String	getPortlist()	返回 cookie 的端口列表屬性
boolean	getSecure()	如果發(fā)送此 cookie 應(yīng)限制為安全協(xié)議，則返回 true；如果可以使用任何協(xié)議發(fā)送，則返回 false。
String	getValue()	返回 cookie 的值。
int	getVersion()	返回此 cookie 遵守的協(xié)議版本。
boolean	hasExpired()	報(bào)告此 HTTP cookie 是否已過期。
int	hashCode()	返回此 HTTP cookie 的哈希碼。
boolean	isHttpOnly()	如果此 cookie 包含 HttpOnly 屬性，則返回 true。
static ListHttpCookie	parse(String header)	從 set-cookie 或 set-cookie2 標(biāo)頭字符串構(gòu)造 cookie。
void	setComment(String purpose)	指定描述 cookie 用途的注釋。
void	setCommentURL(String purpose)	指定描述 cookie 用途的評(píng)論 URL。
void	setDiscard(boolean discard)	指定用戶代理是否應(yīng)無(wú)條件丟棄 cookie。
void	setDomain(String pattern)	指定應(yīng)在其中顯示此 cookie 的域。
void	setHttpOnly(boolean httpOnly)	指示是否應(yīng)將 cookie 視為僅 HTTP。
void	setMaxAge(long expiry)	以秒為單位設(shè)置 cookie 的最長(zhǎng)期限。
void	setPath(String uri)	指定客戶端應(yīng)將 cookie 返回到的 cookie 路徑。
void	setPortlist(String ports)	指定 cookie 的端口列表，它限制 cookie 可以在 Cookie 標(biāo)頭中發(fā)送回的端口。
void	setSecure(boolean flag)	指示是否應(yīng)僅使用安全協(xié)議（例如 HTTPS 或 SSL）發(fā)送 cookie。
void	setValue(String newValue)	創(chuàng)建 cookie 后為 cookie 分配一個(gè)新值。
void	setVersion(int v)	設(shè)置此 cookie 遵守的 cookie 協(xié)議的版本。
String	toString()	構(gòu)造此 cookie 的 cookie 標(biāo)頭字符串表示，其格式由相應(yīng)的 cookie 規(guī)范定義，但沒有前導(dǎo)“Cookie:”標(biāo)記。

從類 java.lang.Object 繼承的方法
finalize, getClass, notify, notifyAll, wait, wait, wait

構(gòu)造函數(shù)詳細(xì)信息

HttpCookie

public HttpCookie(String name, String value)

構(gòu)造一個(gè)具有指定名稱和值的 cookie。

該名稱必須符合 RFC 2965。這意味著它只能包含 ASCII 字母數(shù)字字符，并且不能包含逗號(hào)、分號(hào)或空格或以 $ 字符開頭。 創(chuàng)建后無(wú)法更改 cookie 的名稱。

該值可以是服務(wù)器選擇發(fā)送的任何值。 它的值可能只對(duì)服務(wù)器感興趣。 cookie 的值可以在創(chuàng)建后使用 setValue 方法進(jìn)行更改。

默認(rèn)情況下，cookie 是根據(jù) RFC 2965 cookie 規(guī)范創(chuàng)建的。 可以使用 setVersion 方法更改版本。

參數(shù)：

參數(shù)名稱	參數(shù)描述
name	一個(gè)字符串，指定 cookie 的名稱
value	一個(gè)字符串，指定 cookie 的值

Throws:

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

方法詳情

parse

public static ListHttpCookie parse(String header)

從 set-cookie 或 set-cookie2 標(biāo)頭字符串構(gòu)造 cookie。 RFC 2965 第 3.2.2 節(jié) set-cookie2 語(yǔ)法表示一個(gè)標(biāo)題行可能包含多個(gè) cookie 定義，因此這是一種靜態(tài)實(shí)用程序方法，而不是另一個(gè)構(gòu)造函數(shù)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
header	指定 set-cookie 標(biāo)頭的字符串。 標(biāo)頭應(yīng)以“set-cookie”或“set-cookie2”標(biāo)記開頭； 或者它根本不應(yīng)該有前導(dǎo)標(biāo)記。

返回:

從標(biāo)題行字符串解析的 cookie 列表

Throws:

Throw名稱	Throw描述
IllegalArgumentException	如果標(biāo)頭字符串違反 cookie 規(guī)范的語(yǔ)法或 cookie 名稱包含非法字符。
NullPointerException	如果標(biāo)題字符串為空

hasExpired

public boolean hasExpired()

報(bào)告此 HTTP cookie 是否已過期。

返回:

true 表示此 HTTP cookie 已過期； 否則為false

setComment

public void setComment(String purpose)

指定描述 cookie 用途的注釋。 如果瀏覽器將 cookie 呈現(xiàn)給用戶，則該注釋很有用。 Netscape 版本 0 cookie 不支持注釋。

參數(shù)：

參數(shù)名稱	參數(shù)描述
purpose	一個(gè)字符串，指定要向用戶顯示的評(píng)論

getComment

public String getComment()

返回描述此 cookie 用途的注釋，如果 cookie 沒有注釋，則返回 null。

返回:

包含評(píng)論的字符串，如果沒有，則返回 null

setCommentURL

public void setCommentURL(String purpose)

指定描述 cookie 用途的評(píng)論 URL。 如果瀏覽器將 cookie 呈現(xiàn)給用戶，則評(píng)論 URL 很有用。 評(píng)論 URL 僅為 RFC 2965。

參數(shù)：

參數(shù)名稱	參數(shù)描述
purpose	一個(gè)字符串，指定要向用戶顯示的評(píng)論 URL

getCommentURL

public String getCommentURL()

返回描述此 cookie 用途的評(píng)論 URL，如果 cookie 沒有評(píng)論 URL，則返回 null。

返回:

包含評(píng)論 URL 的字符串，如果沒有則返回 null

setDiscard

public void setDiscard(boolean discard)

指定用戶代理是否應(yīng)無(wú)條件丟棄 cookie。 這是 RFC 2965 唯一的屬性。

參數(shù)：

參數(shù)名稱	參數(shù)描述
discard	true 表示無(wú)條件丟棄cookie

getDiscard

public boolean getDiscard()

返回 cookie 的丟棄屬性

返回:

表示此 cookie 的丟棄屬性的布爾值

setPortlist

public void setPortlist(String ports)

指定 cookie 的端口列表，它限制 cookie 可以在 Cookie 標(biāo)頭中發(fā)送回的端口。

參數(shù)：

參數(shù)名稱	參數(shù)描述
ports	一個(gè)字符串指定端口列表，它是逗號(hào)分隔的一系列數(shù)字

getPortlist

public String getPortlist()

返回 cookie 的端口列表屬性

返回:

字符串包含端口列表，如果沒有則為 null

setDomain

public void setDomain(String pattern)

指定應(yīng)在其中顯示此 cookie 的域。

域名的格式由 RFC 2965 指定。域名以點(diǎn) (.foo.com) 開頭，表示 cookie 對(duì)指定域名系統(tǒng) (DNS) 區(qū)域中的服務(wù)器可見（例如，www. foo.com，但不是 a.b.foo.com）。 默認(rèn)情況下，cookie 僅返回給發(fā)送它們的服務(wù)器。

參數(shù)：

參數(shù)名稱	參數(shù)描述
pattern	一個(gè)字符串，其中包含此 cookie 可見的域名； 表格符合 RFC 2965

getDomain

public String getDomain()

返回為此 cookie 設(shè)置的域名。 域名的格式由 RFC 2965 設(shè)置。

返回:

包含域名的字符串

setMaxAge

public void setMaxAge(long expiry)

以秒為單位設(shè)置 cookie 的最長(zhǎng)期限。

正值表示 cookie 將在經(jīng)過這么多秒后過期。 請(qǐng)注意，該值是 cookie 過期的最大期限，而不是 cookie 的當(dāng)前期限。

負(fù)值表示 cookie 不會(huì)永久存儲(chǔ)，并且會(huì)在 Web 瀏覽器退出時(shí)被刪除。 零值會(huì)導(dǎo)致 cookie 被刪除。

參數(shù)：

參數(shù)名稱	參數(shù)描述
expiry	一個(gè)整數(shù)，以秒為單位指定 cookie 的最大年齡； 如果為零，則應(yīng)立即丟棄 cookie； 否則，未指定 cookie 的最大年齡。

getMaxAge

public long getMaxAge()

返回 cookie 的最長(zhǎng)期限，以秒為單位。 默認(rèn)情況下，-1 表示 cookie 將持續(xù)存在，直到瀏覽器關(guān)閉。

返回:

一個(gè)整數(shù)，以秒為單位指定 cookie 的最大年齡

setPath

public void setPath(String uri)

指定客戶端應(yīng)將 cookie 返回到的 cookie 路徑。

該 cookie 對(duì)您指定的目錄中的所有頁(yè)面以及該目錄的子目錄中的所有頁(yè)面都是可見的。 cookie 的路徑必須包含設(shè)置 cookie 的 servlet，例如 /catalog，它使 cookie 對(duì)服務(wù)器上 /catalog 下的所有目錄可見。

參數(shù)：

參數(shù)名稱	參數(shù)描述
uri	指定路徑的字符串

getPath

public String getPath()

返回瀏覽器將此 cookie 返回到的服務(wù)器上的路徑。 cookie 對(duì)服務(wù)器上的所有子路徑可見。

返回:

一個(gè)字符串，指定包含 servlet 名稱的路徑，例如 /catalog

setSecure

public void setSecure(boolean flag)

指示是否應(yīng)僅使用安全協(xié)議（例如 HTTPS 或 SSL）發(fā)送 cookie。

默認(rèn)值為假。

參數(shù)：

參數(shù)名稱	參數(shù)描述
flag	如果為 true，則 cookie 只能通過 HTTPS 等安全協(xié)議發(fā)送。 如果為 false，則可以通過任何協(xié)議發(fā)送。

getSecure

public boolean getSecure()

如果發(fā)送此 cookie 應(yīng)限制為安全協(xié)議，則返回 true；如果可以使用任何協(xié)議發(fā)送，則返回 false。

返回：

如果 cookie 可以通過任何標(biāo)準(zhǔn)協(xié)議發(fā)送，則為 false； 否則為true

getName

public String getName()

返回 cookie 的名稱。 創(chuàng)建后無(wú)法更改名稱。

返回:

指定 cookie 名稱的字符串

setValue

public void setValue(String newValue)

創(chuàng)建 cookie 后為 cookie 分配一個(gè)新值。 如果您使用二進(jìn)制值，您可能需要使用 BASE64 編碼。

對(duì)于版本 0 cookie，值不應(yīng)包含空格、方括號(hào)、圓括號(hào)、等號(hào)、逗號(hào)、雙引號(hào)、斜杠、問號(hào)、at 符號(hào)、冒號(hào)和分號(hào)。 空值在所有瀏覽器上的行為方式可能不同。

參數(shù)：

參數(shù)名稱	參數(shù)描述
newValue	指定新值的字符串

getValue

public String getValue()

返回 cookie 的值。

返回:

包含 cookie 的當(dāng)前值的字符串

getVersion

public int getVersion()

返回此 cookie 遵守的協(xié)議版本。 版本 1 符合 RFC 2965/2109，版本 0 符合 Netscape 起草的原始 cookie 規(guī)范。 瀏覽器提供的 cookie 使用并識(shí)別瀏覽器的 cookie 版本。

返回:

如果 cookie 符合原始 Netscape 規(guī)范，則為 0； 1 如果 cookie 符合 RFC 2965/2109

setVersion

public void setVersion(int v)

設(shè)置此 cookie 遵守的 cookie 協(xié)議的版本。 版本 0 符合最初的 Netscape cookie 規(guī)范。 版本 1 符合 RFC 2965/2109。

參數(shù)：

參數(shù)名稱	參數(shù)描述
v	0 如果 cookie 應(yīng)該符合原始的 Netscape 規(guī)范； 1 如果 cookie 應(yīng)符合 RFC 2965/2109

Throws:

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

isHttpOnly

public boolean isHttpOnly()

如果此 cookie 包含 HttpOnly 屬性，則返回 true。 這意味著腳本引擎（如 javascript）不應(yīng)訪問 cookie。

返回:

如果此 cookie 應(yīng)被視為 HTTPOnly，則為 true

setHttpOnly

public void setHttpOnly(boolean httpOnly)

指示是否應(yīng)將 cookie 視為僅 HTTP。 如果設(shè)置為 true，則意味著 cookie 不應(yīng)被 javascript 等腳本引擎訪問。

參數(shù)：

參數(shù)名稱	參數(shù)描述
httpOnly	如果為 true，則使 cookie 僅 HTTP，即僅作為 HTTP 請(qǐng)求的一部分可見。

domainMatches

public static boolean domainMatches(String domain, String host)

檢查主機(jī)名是否在域中的實(shí)用方法。

這個(gè)概念在 cookie 規(guī)范中有所描述。 要理解這個(gè)概念，首先需要定義一些術(shù)語(yǔ)：

如果主機(jī)名包含點(diǎn)，則有效主機(jī)名 = 主機(jī)名；如果不包含點(diǎn)，則 = hostname.local

主機(jī) A 的名稱域與主機(jī) B 的匹配，如果：

• 他們的主機(jī)名字符串字符串比較相等； 或者
• A 是 HDN 字符串，格式為 NB，其中 N 是非空名稱字符串，B 的格式為 .B'，B' 是 HDN 字符串。 （因此，x.y.com 域匹配 .Y.com 但不匹配 Y.com。）

如果出現(xiàn)以下情況，主機(jī)不在域中（RFC 2965 sec. 3.3.2）：

• Domain 屬性的值不包含嵌入的點(diǎn)，并且該值不是 .local。
• 從請(qǐng)求主機(jī)派生的有效主機(jī)名與域?qū)傩圆黄ヅ洹?/li>
• 請(qǐng)求主機(jī)是 HDN（不是 IP 地址），格式為 HD，其中 D 是域?qū)傩缘闹?，H 是包含一個(gè)或多個(gè)點(diǎn)的字符串。

例子:

• 來(lái)自請(qǐng)求主機(jī) y.x.foo.com 的 Domain=.foo.com 的 Set-Cookie2 將被拒絕，因?yàn)?H 是 y.x 并且包含一個(gè)點(diǎn)。
• 來(lái)自請(qǐng)求主機(jī) x.foo.com 的 Set-Cookie2 用于 Domain=.foo.com 將被接受。
• 帶有 Domain=.com 或 Domain=.com. 的 Set-Cookie2 將始終被拒絕，因?yàn)闆]有嵌入的點(diǎn)。
• 將接受來(lái)自 Domain=.local 的請(qǐng)求主機(jī)示例的 Set-Cookie2，因?yàn)檎?qǐng)求主機(jī)的有效主機(jī)名是 example.local，并且 example.local 域匹配 .local。

參數(shù):

參數(shù)名稱	參數(shù)描述
domain	用于檢查主機(jī)名的域名
host	有問題的主機(jī)名

返回:

如果它們域匹配，則為 true； 如果不是，則為false

toString

public String toString()

構(gòu)造此 cookie 的 cookie 標(biāo)頭字符串表示，其格式由相應(yīng)的 cookie 規(guī)范定義，但沒有前導(dǎo)“Cookie:”標(biāo)記。

覆蓋：

類 Object 中的 toString

返回:

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

equals

public boolean equals(Object obj)

測(cè)試兩個(gè) HTTP cookie 的相等性。

僅當(dāng)兩個(gè) cookie 來(lái)自同一個(gè)域（不區(qū)分大小寫）、具有相同名稱（不區(qū)分大小寫）和具有相同路徑（區(qū)分大小寫）時(shí)，結(jié)果才為真。

覆蓋：

類 Object 中的等于

參數(shù)：

參數(shù)名稱	參數(shù)描述
obj	要與之比較的參考對(duì)象。

返回:

如果兩個(gè) HTTP cookie 相等，則為 true； 否則為假

hashCode

public int hashCode()

返回此 HTTP cookie 的哈希碼。 結(jié)果是此 cookie 的三個(gè)重要組成部分的哈希碼值的總和：名稱、域和路徑。 也就是說(shuō)，哈希碼是表達(dá)式的值：

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

覆蓋：

類 Object 中的 hashCode

返回:

這個(gè) HTTP cookie 的哈希碼

clone

public Object clone()

創(chuàng)建并返回此對(duì)象的副本。

覆蓋：

在類 Object 中克隆

返回:

此 HTTP cookie 的克隆