javax.servlet.http.Cookie翻译

转自:http://lavasoft.blog.51cto.com/62575/78163
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, www.foo.com, but not a.b.foo.com). By default, cookies are only returned to the server that sent them. 如果域名使用RFC 2109规范，那么名字应该以点开始 (.foo.com)，并且意味着这个cookie在指定的域名系统（DNS）下是有效的，比如（www.foo.com，但不是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