- java.lang.Object
-
- java.net.HttpCookie
-
- All Implemented Interfaces:
-
Cloneable
public final class HttpCookie extends Object implements Cloneable
HttpCookie对象表示HTTP cookie,它承载服务器和用户代理之间的状态信息。 Cookie被广泛采用来创建有状态会话。有3个HTTP cookie规范:
Netscape draft
RFC 2109 - http://www.ietf.org/rfc/rfc2109.txt
RFC 2965 - http://www.ietf.org/rfc/rfc2965.txtHttpCookie类可以接受所有这三种形式的语法。
- 从以下版本开始:
- 1.6
-
-
构造方法摘要
构造方法 Constructor 描述 HttpCookie(String name, String value)
构造具有指定名称和值的cookie。
-
方法摘要
所有方法 静态方法 接口方法 具体的方法 Modifier and Type 方法 描述 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()
返回true
如果发送此cookie应该被限制为一个安全协议,或者false
如果可以使用任何协议发送。String
getValue()
返回cookie的值。int
getVersion()
返回该Cookie符合的协议版本。boolean
hasExpired()
报告此HTTP Cookie是否已过期。int
hashCode()
返回此HTTP cookie的哈希码。boolean
isHttpOnly()
如果此cookie包含 HttpOnly属性,则返回true
。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
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)
指示Cookie是否应仅使用安全协议(如HTTPS或SSL)发送。void
setValue(String newValue)
在创建cookie之后为cookie分配一个新值。void
setVersion(int v)
设置cookie符合的cookie协议的版本。String
toString()
构造此Cookie的Cookie标题字符串表示形式,其格式为相应Cookie规范定义的格式,但不包含前导“Cookie:”标记。
-
-
-
构造方法详细信息
-
HttpCookie
public HttpCookie(String name, String value)
构造具有指定名称和值的cookie。该名称必须符合RFC 2965.这意味着它只能包含ASCII字母数字字符,不能包含逗号,分号或空格或以$字符开头。 创建后无法更改Cookie的名称。
该值可以是服务器选择发送的任何值。 它的价值可能仅对服务器感兴趣。 使用
setValue
方法创建后,cookie的值可以更改。默认情况下,根据RFC 2965 cookie规范创建Cookie。 该版本可以通过
setVersion
方法更改。- 参数
-
name
- 一个指定cookie名称的String
-
value
- 一个String
指定cookie的值 - 异常
-
IllegalArgumentException
- 如果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
- 一个String
指定set-cookie标题。 标题应以“set-cookie”或“set-cookie2”标记开头; 或者它应该没有领先的标记。 - 结果
- 从标题行字符串中解析的Cookie列表
- 异常
-
IllegalArgumentException
- 如果头字符串违反了cookie规范的语法,或者cookie名称包含非法字符。 -
NullPointerException
- 如果标题字符串是null
-
hasExpired
public boolean hasExpired()
报告此HTTP Cookie是否已过期。- 结果
-
true
表示此HTTP cookie已过期; 否则,false
-
setComment
public void setComment(String purpose)
指定描述Cookie目的的注释。 如果浏览器向用户显示cookie,则该注释很有用。 Netscape Version 0 cookies不支持评论。- 参数
-
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很有用。 评论URL仅限于RFC 2965。- 参数
-
purpose
- 一个String
指定要向用户显示的注释URL - 另请参见:
-
getCommentURL()
-
getCommentURL
public String getCommentURL()
返回描述此cookie的目的的注释URL,如果cookie没有注释URL,则返回null
。- 结果
-
一个
String
包含注释URL,或者null
如果没有 - 另请参见:
-
setCommentURL(java.lang.String)
-
setDiscard
public void setDiscard(boolean discard)
指定用户代理是否无条件丢弃该cookie。 这是RFC 2965 only属性。- 参数
-
discard
-true
表示无条件丢弃cookie - 另请参见:
-
getDiscard()
-
getDiscard
public boolean getDiscard()
返回cookie的丢弃属性- 结果
-
一个
boolean
代表这个cookie的丢弃属性 - 另请参见:
-
setDiscard(boolean)
-
setPortlist
public void setPortlist(String ports)
指定cookie的端口列表,该端口列表限制Cookie可以在Cookie头中发回的端口。- 参数
-
ports
- aString
指定端口列表,它是逗号分隔的数字系列 - 另请参见:
-
getPortlist()
-
getPortlist
public String getPortlist()
返回cookie的端口列表属性- 结果
-
一个
String
包含端口列表或null
如果没有 - 另请参见:
-
setPortlist(java.lang.String)
-
setDomain
public void setDomain(String pattern)
指定应显示此Cookie的域。域名的格式由RFC 2965指定。域名以点(
.foo.com
)开头,意味着cookie对于指定的域名系统(DNS)区域中的服务器是可见的(例如,www.foo.com
,但不是a.b.foo.com
)。 默认情况下,Cookie只返回给发送它们的服务器。- 参数
-
pattern
- 一个String
其中包含该cookie可见的域名; 形式根据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浏览器退出时将被删除。 零值会导致cookie被删除。
- 参数
-
expiry
- 指定cookie的最大年龄(以秒为单位)的整数; 如果为零,则应立即丢弃该cookie; 否则,cookie的最大年龄未指定。 - 另请参见:
-
getMaxAge()
-
getMaxAge
public long getMaxAge()
返回cookie的最大使用年限,以秒为单位。 默认情况下,-1
表示cookie将持续到浏览器关机。- 结果
- 一个整数,指定cookie的最大年龄(以秒为单位)
- 另请参见:
-
setMaxAge(long)
-
setPath
public void setPath(String uri)
指定客户端应该返回cookie的cookie的路径。该cookie对于您指定的目录中的所有页面以及该目录子目录中的所有页面都是可见的。 cookie的路径必须包含设置cookie的servlet,例如/ catalog ,这使得cookie可以在/ catalog下的服务器上的所有目录中看到。
有关设置cookie路径名称的更多信息,请参阅RFC 2965(Internet上可用)。
- 参数
-
uri
- 指定路径的一个String
- 另请参见:
-
getPath()
-
getPath
public String getPath()
返回浏览器返回此Cookie的服务器上的路径。 cookie对服务器上的所有子路径都可见。- 结果
-
一个
String
指定包含servlet名称的路径,例如 / catalog - 另请参见:
-
setPath(java.lang.String)
-
setSecure
public void setSecure(boolean flag)
指示Cookie是否应仅使用安全协议(如HTTPS或SSL)发送。默认值为
false
。- 参数
-
flag
- 如果是true
,则只能通过HTTPS等安全协议发送cookie。 如果是false
,可以通过任何协议发送。 - 另请参见:
-
getSecure()
-
getSecure
public boolean getSecure()
返回true
如果发送这个cookie应该被限制在一个安全的协议中,或者是false
如果它可以使用任何协议发送。- 结果
-
false
如果cookie可以通过任何标准协议发送; 否则,true
- 另请参见:
-
setSecure(boolean)
-
getName
public String getName()
返回cookie的名称。 创建后无法更改名称。- 结果
-
一个
String
指定cookie的名称
-
setValue
public void setValue(String newValue)
在创建cookie之后为cookie分配一个新值。 如果使用二进制值,则可能需要使用BASE64编码。使用版本0的Cookie,值不应包含空格,括号,括号,等号,逗号,双引号,斜线,问号,符号,冒号和分号。 空值在所有浏览器上的行为可能不一样。
- 参数
-
newValue
- 一个String
指定新值 - 另请参见:
-
getValue()
-
getValue
public String getValue()
返回cookie的值。- 结果
-
一个
String
包含cookie的当前值 - 另请参见:
-
setValue(java.lang.String)
-
getVersion
public int getVersion()
返回该Cookie符合的协议版本。 版本1符合RFC 2965/2109,版本0符合Netscape起草的原始cookie规范。 浏览器提供的Cookie使用浏览器的Cookie版本。- 结果
- 0如果cookie符合原始的Netscape规范; 1如果cookie符合RFC 2965/2109
- 另请参见:
-
setVersion(int)
-
setVersion
public void setVersion(int v)
设置cookie符合的cookie协议的版本。 版本0符合原始的Netscape cookie规范。 版本1符合RFC 2965/2109。- 参数
-
v
- 0如果cookie应符合原始的Netscape规范; 1如果cookie应符合RFC 2965/2109 - 异常
-
IllegalArgumentException
- 如果v
既不是0也不是1 - 另请参见:
-
getVersion()
-
isHttpOnly
public boolean isHttpOnly()
如果此cookie包含HttpOnly属性,则返回true
。 这意味着脚本引擎不能访问cookie,比如javascript。- 结果
-
true
如果这个cookie应该被认为是HTTPOnly - 另请参见:
-
setHttpOnly(boolean)
-
setHttpOnly
public void setHttpOnly(boolean httpOnly)
指示Cookie是否应被视为仅HTTP。 如果设置为true
则意味着脚本引擎(如JavaScript)不能访问该cookie。- 参数
-
httpOnly
- 如果true
仅使用cookie HTTP,即仅作为HTTP请求的一部分可见。 - 另请参见:
-
isHttpOnly()
-
domainMatches
public static boolean domainMatches(String domain, String host)
检查主机名是否在域中的实用方法。这个概念在cookie规范中描述。 要理解这个概念,需要首先定义一些术语:
effective host name = hostname if host name contains dot
or = hostname.local if not主机A的名称域 - 匹配主机B的,如果:
- their host name strings string-compare equal; or
- A is a HDN string and has the form NB, where N is a non-empty name string, B has the form .B', and B' is a HDN string. (So, x.y.com domain-matches .Y.com but not Y.com.)
如果主机不在域中(RFC 2965秒3.3.2):
- The value for the Domain attribute contains no embedded dots, and the value is not .local.
- The effective host name that derives from the request-host does not domain-match the Domain attribute.
- The request-host is a HDN (not IP address) and has the form HD, where D is the value of the Domain attribute, and H is a string that contains one or more dots.
例子:
- A Set-Cookie2 from request-host y.x.foo.com for Domain=.foo.com would be rejected, because H is y.x and contains a dot.
- A Set-Cookie2 from request-host x.foo.com for Domain=.foo.com would be accepted.
- A Set-Cookie2 with Domain=.com or Domain=.com., will always be rejected, because there is no embedded dot.
- A Set-Cookie2 from request-host example for Domain=.local will be accepted, because the effective host name for the request- host is example.local, and example.local domain-matches .local.
- 参数
-
domain
- 用于检查主机名的域名 -
host
- 有问题的主机名 - 结果
-
true
如果他们的域匹配;false
如果没有
-
toString
public String toString()
构造此Cookie的Cookie标题字符串表示形式,其格式为相应Cookie规范定义的格式,但不包含前导“Cookie:”标记。
-
equals
public boolean equals(Object obj)
测试两个HTTP Cookie的相等性。结果是
true
只有两个cookie来自同一个域(不区分大小写),具有相同的名称(不区分大小写),并且具有相同的路径(区分大小写)。- 重写:
-
equals
在Object
- 参数
-
obj
- 与之比较的参考对象。 - 结果
-
true
如果两个HTTP cookies相互等价; 否则,false
- 另请参见:
-
Object.hashCode()
,HashMap
-
hashCode
public int hashCode()
返回此HTTP cookie的哈希码。 结果是这个cookie的三个重要组件的哈希码值的总和:名称,域和路径。 也就是说,哈希码是表达式的值:getName().toLowerCase().hashCode()
+ getDomain().toLowerCase().hashCode()
+ getPath().hashCode()- 重写:
-
hashCode
在Object
- 结果
- 这个HTTP cookie的哈希码
- 另请参见:
-
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
-