java.net
類別 HttpCookie

java.lang.Object
  java.net.HttpCookie

所有已實作的介面：

Cloneable

public final class HttpCookie
extends Object
implements Cloneable

HttpCookie 物件表示一個 http cookie，該 cookie 帶有伺服器和使用者代理之間的狀態資訊。廣泛採用 Cookie 來創建有狀態 (stateful) Session。

有 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 是一個非空(null)名稱字元串，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