原創地址：http://lavasoft.blog.51cto.com/62575/78163
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
javax.servlet.http
Class Cookie
java.lang.Object
|
+--javax.servlet.http.Cookie
public class Cookie
extends java.lang.Object
implements java.lang.Cloneable
Creates a cookie, a small amount of information sent by a servlet to a Web browser, saved by the browser, and later sent back to the server. A cookie's value can uniquely identify a client, so cookies are commonly used for session management. 創建一個cookie，一個小量信息通過Servlet發送給Web瀏覽器，通過瀏覽器保存，以後再從瀏覽器發送給服務器。一個cookie的值能唯一識別一個客戶端，因此cookie常用於session的管理。
A cookie has a name, a single value, and optional attributes such as a comment, path and domain qualifiers, a maximum age, and a version number. Some Web browsers have bugs in how they handle the optional attributes, so use them sparingly to improve the interoperability of your servlets. 一個cookie有一個名字和一個值和一些可選擇的屬性例如註釋、路徑、域、最大有效時間、版本號等。一些瀏覽器在處理可選項時有bug，因此應保守使用以提高sevlet的交互性。
The servlet sends cookies to the browser by using the HttpServletResponse.addCookie(javax.servlet.http.Cookie) method, which adds fields to HTTP response headers to send cookies to the browser, one at a time. The browser is expected to support 20 cookies for each Web server, 300 cookies total, and may limit cookie size to 4 KB each. Sevlet發送cookie使用HttpServletResponse.addCookie(javax.servlet.http.Cookie)方法，一個瀏覽器預計最多可支持300個cookie，對一個站點最多支持20個cookie，並且可能限制一個cookie的大小不超過4KB。
The browser returns cookies to the servlet by adding fields to HTTP request headers. Cookies can be retrieved from a request by using the HttpServletRequest.getCookies() method. Several cookies might have the same name but different path attributes. 瀏覽器通過HTTP請求的處理者返回cookie到一個servlet。cookie能被從HttpServletRequest.getCookies()中重新獲取到。
Cookies affect the caching of the Web pages that use them. HTTP 1.0 does not cache pages that use cookies created with this class. This class does not support the cache control defined with HTTP 1.1. Cookie影響每一個使用它的web頁。 (......)
This class supports both the Version 0 (by Netscape) and Version 1 (by RFC 2109) cookie specifications. By default, cookies are created using Version 0 to ensure the best interoperability. 這個類同時支持版本0和版本1的cookie規範。默認情況下，cookie使用版本0來創建以確保最好的交互性。
Constructor Summary
Cookie(java.lang.String name, java.lang.String value)
Constructs a cookie with a specified name and value. 使用指定的名稱和值構建一個cookie。
Method Summary
java.lang.Object clone()
Overrides the standard java.lang.Object.clone method to return a copy of this cookie. 返回cookie克隆的副本，這個方法覆蓋了java.lang.Object.clone()方法。
java.lang.String getComment()
Returns the comment describing the purpose of this cookie, or null if the cookie has no comment.返回一個描述cookie用途的註釋，如果沒有註釋，則返回null。
java.lang.String getDomain()
Returns the domain name set for this cookie.返回一個cookie域名。(域名指定cookie在哪個域中有效，例如：Domain=.blog.51cto.com)
int getMaxAge()
Returns the maximum age of the cookie, specified in seconds, By default, -1 indicating the cookie will persist until browser shutdown. 返回cookie在客戶端最大的有效時間，以秒爲單位。默認情況下爲-1，表示cookie將一直有效直到瀏覽器關閉。
java.lang.String getName()
Returns the name of the cookie.返回cookie的名字。
java.lang.String getPath()
Returns the path on the server to which the browser returns this cookie.返回cookie對服務器上哪個url有效。
boolean getSecure()
Returns true if the browser is sending cookies only over a secure protocol, or false if the browser can send cookies using any protocol. 如果瀏覽器僅僅安全協議下發送cookie則返回true。瀏覽器能使用任何協議發送cookie則返回fasle。
java.lang.String getValue()
Returns the value of the cookie. 返回cookie的值。
int getVersion()
Returns the version of the protocol this cookie complies with.返回cookie內容所遵循的版本。（目前只有值爲1時可用）。
void setComment(java.lang.String purpose)
Specifies a comment that describes a cookie's purpose.設置描述cookie用途的註釋。
void setDomain(java.lang.String pattern)
Specifies the domain within which this cookie should be presented.設置cookie在哪一個域中使用。
void setMaxAge(int expiry)
Sets the maximum age of the cookie in seconds.設置cookie最大的有效時間。
void setPath(java.lang.String uri)
Specifies a path for the cookie to which the client should return the cookie.設置cookie的有效路徑。
void setSecure(boolean flag)
Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL.設置是否使用安全協議如HTTPS或SSL等發送cookie。
void setValue(java.lang.String newValue)
Assigns a new value to a cookie after the cookie is created. 給一個cookie重新指定一個新值。
void setVersion(int v)
Sets the version of the cookie protocol this cookie complies with.設置cookie使用的協議版本。
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Constructor Detail
Cookie
public Cookie(java.lang.String name,
java.lang.String value)
Constructs a cookie with a specified name and value. 使用指定的名稱和值創建一個cookie。
The name must conform to RFC 2109. That means it can contain only ASCII alphanumeric characters and cannot contain commas, semicolons, or white space or begin with a $ character. The cookie's name cannot be changed after creation. 這個名稱必須遵循RFC 2109的規範。這意味着它僅僅能包含ASCII碼字符，並且不能包含逗號，分號，或者空格，或者以$開頭的字符串，cookie的名字在創建後就不能再改變了。
The value can be anything the server chooses to send. Its value is probably of interest only to the server. The cookie's value can be changed after creation with the setValue method. 這個值可以發送給任何的服務器，但是僅對某個服務器有作用。這個值在創建後可以通過setValue方法來改變。
By default, cookies are created according to the Netscape cookie specification. The version can be changed with the setVersion method. 默認情況下，依照Netscape cookie規範來創建，版本可以通過setVersion來改變。
Parameters:
name - a String specifying the name of the cookie 一個指定cookie名字的字符串。
value - a String specifying the value of the cookie 一個指定cookie值的字符串。
Throws:
java.lang.IllegalArgumentException - if the cookie name contains illegal characters (for example, a comma, space, or semicolon) or it is one of the tokens reserved for use by the cookie protocol
See Also:
setValue(java.lang.String), setVersion(int)
Method Detail
setComment
public void setComment(java.lang.String purpose)
Specifies a comment that describes a cookie's purpose. The comment is useful if the browser presents the cookie to the user. Comments are not supported by Netscape Version 0 cookies. 設置用來描述cookie目的的註釋，如果瀏覽器將這個cookie給一個使用者，這個信息將很有用。註釋不支持通過Netscape版本0的cookie。
Parameters:
purpose - a String specifying the comment to display to the user 一個顯示給使用者的字符串註釋。
See Also:
getComment()
getComment
public java.lang.String getComment()
Returns the comment describing the purpose of this cookie, or null if the cookie has no comment.返回一個描述cookie意圖的註釋，當沒有註釋的時候返回null。
Returns:
a String containing the comment, or null if none
See Also:
setComment(java.lang.String)
setDomain
public void setDomain(java.lang.String pattern)
Specifies the domain within which this cookie should be presented. 指定cookie將在哪個域裏面有效。
The form of the domain name is specified by RFC 2109. A domain name begins with a dot (.foo.com) and means that the cookie is visible to servers in a specified Domain Name System (DNS) zone (for example, [url]www.foo.com[/url], but not a.b.foo.com). By default, cookies are only returned to the server that sent them. 如果域名使用RFC 2109規範，那麼名字應該以點開始 (.foo.com)，並且意味着這個cookie在指定的域名系統（DNS）下是有效的，比如（[url]www.foo.com[/url]，但不是a.b.foo.com）。默認情況下，cookie僅能返回給發送他們的服務器。
Parameters:
pattern - a String containing the domain name within which this cookie is visible; form is according to RFC 2109
See Also:
getDomain()
getDomain
public java.lang.String getDomain()
Returns the domain name set for this cookie. The form of the domain name is set by RFC 2109.返回一個cookie域名。域名使用RFC 2109規範。
Returns:
a String containing the domain name
See Also:
setDomain(java.lang.String)
setMaxAge
public void setMaxAge(int expiry)
Sets the maximum age of the cookie in seconds. 以秒爲單位設置cookie最大的有效時間。
A positive value indicates that the cookie will expire after that many seconds have passed. Note that the value is the maximum age when the cookie will expire, not the cookie's current age. 一個明確值指定cookie將在多少秒過後失效。注意，這個值是cookie有效期滿的最大值，不是當前cookie的存在時間。
A negative value means that the cookie is not stored persistently and will be deleted when the Web browser exits. A zero value causes the cookie to be deleted.一個負值意味着cookie不連續存儲，並且在瀏覽器推出的時候刪除。一個0值將導致cookie被刪除。
Parameters:
expiry - an integer specifying the maximum age of the cookie in seconds; if negative, means the cookie is not stored; if zero, deletes the cookie
See Also:
getMaxAge()
getMaxAge
public int getMaxAge()
Returns the maximum age of the cookie, specified in seconds, By default, -1 indicating the cookie will persist until browser shutdown. 返回cookie最大有效期，默認情況下，-1表示cookie將一直有效，直到瀏覽器關閉。
Returns:
an integer specifying the maximum age of the cookie in seconds; if negative, means the cookie persists until browser shutdown
See Also:
setMaxAge(int)
setPath
public void setPath(java.lang.String uri)
Specifies a path for the cookie to which the client should return the cookie. 爲應該返回cookie的客戶端cookie指定一個路徑。
The cookie is visible to all the pages in the directory you specify, and all the pages in that directory's subdirectories. A cookie's path must include the servlet that set the cookie, for example, /catalog, which makes the cookie visible to all directories on the server under /catalog. 這個cookie將對指定目錄中及其子目錄所有的頁可見。一個cookie路徑必須包含設置它的那個servlet，例如，/catalog,這使得cookie在/catalog下可見。
Consult RFC 2109 (available on the Internet) for more information on setting path names for cookies.查看RFC 2109規範，有更多關於設置路徑名的信息。
Parameters:
uri - a String specifying a path
See Also:
getPath()
getPath
public java.lang.String getPath()
Returns the path on the server to which the browser returns this cookie. The cookie is visible to all subpaths on the server.返回一個cookie返回服務器的路徑，並且這個cookie對服務器上該路徑下所有的子路徑有效。
Returns:
a String specifying a path that contains a servlet name, for example, /catalog
See Also:
setPath(java.lang.String)
setSecure
public void setSecure(boolean flag)
Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL. 指定瀏覽器將使用安全協議（例如,HTTPS 或 SSL）發送cookie。
The default value is false. 默認值是false。
Parameters:
flag - if true, sends the cookie from the browser to the server only when using a secure protocol; if false, sent on any protocol
See Also:
getSecure()
getSecure
public boolean getSecure()
Returns true if the browser is sending cookies only over a secure protocol, or false if the browser can send cookies using any protocol. 如果瀏覽器僅僅安全協議下發送cookie則返回true。瀏覽器能使用任何協議發送cookie則返回fasle。
Returns:
true if the browser uses a secure protocol; otherwise, true
See Also:
setSecure(boolean)
getName
public java.lang.String getName()
Returns the name of the cookie. The name cannot be changed after creation. 返回cookie的名字。在創建後名字不能改變。
Returns:
a String specifying the cookie's name
setValue
public void setValue(java.lang.String newValue)
Assigns a new value to a cookie after the cookie is created. If you use a binary value, you may want to use BASE64 encoding. 爲一個已經創建好的cookie指定一個新值，如果使用二進制值，則可能要使用BASE64編碼。
With Version 0 cookies, values should not contain white space, brackets, parentheses, equals signs, commas, double quotes, slashes, question marks, at signs, colons, and semicolons. Empty values may not behave the same way on all browsers. 在版本0cookie裏，不能包含空格、括號、圓括號、等號、逗號、雙引號、問號、冒號等等。空值一樣可以在所有瀏覽器上工作。
Parameters:
newValue - a String specifying the new value
See Also:
getValue(), Cookie
getValue
public java.lang.String getValue()
Returns the value of the cookie.返回一個cookie的值。
Returns:
a String containing the cookie's present value
See Also:
setValue(java.lang.String), Cookie
getVersion
public int getVersion()
Returns the version of the protocol this cookie complies with. Version 1 complies with RFC 2109, and version 0 complies with the original cookie specification drafted by Netscape. Cookies provided by a browser use and identify the browser's cookie version. 返回cookie遵循的版本。版本1遵循RFC 2109規範，版本0遵循老的Netscape制定的cookie規範。cookie只能通過瀏覽器使用來標識，並且認出一個cookie的版本。
Returns:
0 if the cookie complies with the original Netscape specification; 1 if the cookie complies with RFC 2109
See Also:
setVersion(int)
setVersion
public void setVersion(int v)
Sets the version of the cookie protocol this cookie complies with. Version 0 complies with the original Netscape cookie specification. Version 1 complies with RFC 2109. 設置cookie所遵循的本版。版本0遵循Netscape公司的cookie規範，版本1遵循RFC 2109規範。
Since RFC 2109 is still somewhat new, consider version 1 as experimental; do not use it yet on production sites.由於RFC 2109是較新的規範，認爲版本1是一個實驗規範：不能適用於生產環境。
Parameters:
v - 0 if the cookie should comply with the original Netscape specification; 1 if the cookie should comply with RFC 2109
See Also:
getVersion()
clone
public java.lang.Object clone()
Overrides the standard java.lang.Object.clone method to return a copy of this cookie. 返回cookie克隆的副本，這個方法覆蓋了java.lang.Object.clone()方法。
Overrides:
clone in class java.lang.Object