All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.feilong.servlet.http.entity.CookieEntity Maven / Gradle / Ivy

Go to download

feilong is a suite of core and expanded libraries that include utility classes, http, excel,cvs, io classes, and much much more.

There is a newer version: 4.3.0
Show newest version
/*
 * Copyright (C) 2008 feilong
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.feilong.servlet.http.entity;

import java.io.Serializable;

import com.feilong.core.TimeInterval;

/**
 * cookie实体,用于 {@link com.feilong.servlet.http.CookieUtil CookieUtil}.
 * 
 * 

关于 {@link #name} 和 {@link #value}字符说明:

* *
* * * * * * * * * * * * * *
字段说明
name名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号.
value名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号.
*
* *

关于cookie大小:

*
* *

* 虽然,RFC 2965官方文档没有说key name的长度限制, 并且鼓励支持大的 cookie
* 但是每个浏览器的实现不同,以下是最佳实践: *

* *

* * 整个cookie(包含name,value,expiry date 等等)大小限制在4K,如果你想兼容大部分的浏览器,建议name小于 4000 bytes,并且整个cookie小于 4093 bytes. *
* 有一点要注意的,如果name太大的话,那么你删不掉cookie(至少在javascript是这样的).删除一个cookie是将它设置为过期.如果name太大(比如4090 bytes),发现我不能设置过期时间,我这么做只是个兴趣,并不是真的要有一个很大name的 * cookie! *

* *

* 关于这个话题,如果你要兼容大部分的浏览器,那么一个domain下面不要超过50个cookies,并且每个domain下面cookie的总大小不要超过4093 bytes.
* 也就是说,所有的cookie大小不要超过4093 bytes.
* 也就是说,你可以有一个 1 个 4093 bytes大小的 cookie, 或者 2 个 2045 bytes 大小的cookies, etc.
*

*
* * *

关于 {@link #maxAge}

* *
* * * * * * * * * * * * * * * * * *
字段说明
正数(positive value)则表示该cookie会在max-age秒之后自动失效.
* 浏览器会将max-age为正数的cookie持久化,即写到对应的cookie文件中.
* 无论客户关闭了浏览器还是电脑,只要还在max-age秒之前,登录网站时该cookie仍然有效 .
负数(negative value)表示不保存不持久化,当浏览器退出就会删除
0(zero value)表示删除
* *

* 默认和servlet 保持一致,为-1,表示不保存不持久化, 浏览器退出就删除;也就是所谓的会话Cookie
* 如果需要设置有效期,可以调用 {@link TimeInterval}类 *

*
* * *

关于 {@link #path}:

* *
*

* 默认情况下,如果在某个页面创建了一个cookie,那么该页面所在目录中的其他页面也可以访问该cookie,如果这个目录下还有子目录,则在子目录中也可以访问. *

* *

示例:

* *
*

* 例如在www.xxxx.com/html/a.html中所创建的cookie,可以被www.xxxx.com/html/b.html或www.xxx.com/html/some/c.html所访问,
* 但不能被www.xxxx.com/d.html访问. *

*
* *

* 为了控制cookie可以访问的目录,需要使用path参数设置cookie,语法如下: document.cookie="name=value; path=cookieDir"; *

*

* 其中cookieDir表示可访问cookie的目录.例如: document.cookie="userId=320; path=/shop"; 就表示当前cookie仅能在shop目录下使用.
* 如果要使cookie在整个网站下可用,可以将cookie_dir指定为根目录,例如: document.cookie="userId=320; path=/"; *

* * *

注意点:

* *
*
    *
  1. path 属性值有大小写之分,应与浏览器中的地址栏的输入一致
  2. *
  3. path 不可读;
    * 同 expires一样,path 只可写,不可读.
  4. *
  5. path 不可更改;
    * 同 expires 不一样,如果我们试图更改 path,那么实际上我们是另外写了一个 cookie,而不是更改了 path 值.
  6. *
  7. path 权限有继承性;
    * 假如指定了 /test/ 目录有权限读取某 cookie,那么 /test/ 之下的目录 /test/t/ 也有权限读取该 cookie.
  8. *
*
* *
* * *

关于 {@link #domain}:

* *
*

* 和路径类似,主机名是指同一个域下的不同主机,例如:www.google.com和gmail.google.com就是两个不同的主机名.
* 默认情况下,一个主机中创建的cookie在另一个主机下是不能被访问的,
* 但可以通过domain参数来实现对其的控制,
* 其语法格式为: document.cookie="name=value; domain=cookieDomain"; *

* *

示例:

* *
*

* 以google为例,要实现跨主机访问,可以写为: document.cookie="name=value;domain=.google.com";
* 这样,所有google.com下的主机都可以访问该cookie. *

*
* *
* *

关于 {@link #httpOnly}和 {@link #secure}:

*
*
    *
  1. secure属性是防止信息在传递的过程中被监听捕获后信息泄漏
  2. *
  3. HttpOnly属性的目的是防止程序(JS脚本、Applet等),获取cookie后进行攻击.
  4. *
* *

* 但是这两个属性,并不能解决cookie在本机出现的信息泄漏的问题(FireFox的插件FireBug能直接看到cookie的相关信息) *

*
* * @author feilong * @see HTTP State Management Mechanism * @see HTTP State Management Mechanism (废弃 被rfc6265取代) * @see What is the maximum size * of a web browser cookie * @see test page and size limits for common browsers * @since 1.0.0 */ public class CookieEntity implements Serializable{ /** The Constant serialVersionUID. */ private static final long serialVersionUID = -5580364261848277853L; //--------------------------------------------------------------- /** name名称,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. */ private String name; /** * value,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. * *

* 注意:如果值长度超过4K,浏览器会忽略,不会执行记录的操作 *

* *

关于 non-ASCII (Unicode) characters:

*
* * What isn't mentioned and browsers are totally inconsistent about, is non-ASCII (Unicode) characters: * *
    *
  1. in Opera and Google Chrome, they are encoded to Cookie headers with UTF-8;
  2. * *
  3. in IE, the machine's default code page is used (locale-specific and never UTF-8);
  4. * *
  5. * Firefox (and other Mozilla-based browsers) use the low byte of each UTF-16 code point on its own (so ISO-8859-1 is OK but * anything else is mangled); *
  6. * *
  7. Safari simply refuses to send any cookie containing non-ASCII characters.
  8. * *
* *

* so in practice you cannot use non-ASCII characters in cookies at all.
* If you want to use Unicode, control codes or other arbitrary byte sequences,
* the cookie_spec demands you use an ad-hoc encoding scheme of your own choosing and suggest URL-encoding (as produced * by JavaScript's encodeURIComponent) as a reasonable choice. *

* *
*/ private String value; /** * 设置存活时间,单位秒. * *
* * * * * * * * * * * * * * * * * *
字段说明
正数(positive value)则表示该cookie会在max-age秒之后自动失效.
* 浏览器会将max-age为正数的cookie持久化,即写到对应的cookie文件中.无论客户关闭了浏览器还是电脑,只要还在max-age秒之前,登录网站时该cookie仍然有效 .
负数(negative value)表示不保存不持久化,当浏览器退出就会删除
0(zero value)表示删除
*
* * 默认和servlet 保持一致,为-1,表示不保存不持久化, 浏览器退出就删除,如果需要设置有效期,可以调用 {@link TimeInterval}类 * *

* ;Max-Age=VALUE *

* * @see javax.servlet.http.Cookie#setMaxAge(int) * * @see 4.1.2.2. The Max-Age Attribute */ private int maxAge = -1; //--------------------------------------------------------------- /** * ;Comment=VALUE ... describes cookie's use ;Discard ... implied by maxAge {@code <} 0 */ private String comment; /** * ;Domain=VALUE ... domain that sees cookie. * *

* 和路径类似,主机名是指同一个域下的不同主机,例如:www.google.com和gmail.google.com就是两个不同的主机名.
* 默认情况下,一个主机中创建的cookie在另一个主机下是不能被访问的,
* 但可以通过domain参数来实现对其的控制,
* 其语法格式为: document.cookie="name=value; domain=cookieDomain"; *

* *

示例:

* *
*

* 以google为例,要实现跨主机访问,可以写为: document.cookie="name=value;domain=.google.com";
* 这样,所有google.com下的主机都可以访问该cookie. *

*
* * @see 4.1.2.3. The Domain Attribute */ private String domain; /** * ;Path=VALUE ... URLs that see the cookie * *

* 当不设置值的时候(tomcat默认情况),如果在某个页面创建了一个cookie,那么该页面所在目录中的其他页面也可以访问该cookie,如果这个目录下还有子目录,则在子目录中也可以访问.
* 为了方便使用cookie,特意将此默认值设置为/,表示所有页面均可读取改cookie *

* *

示例:

* *
*

* 例如在www.xxxx.com/html/a.html中所创建的cookie,可以被www.xxxx.com/html/b.html或www.xxx.com/html/some/c.html所访问,
* 但不能被www.xxxx.com/d.html访问. *

* *

* 为了控制cookie可以访问的目录,需要使用path参数设置cookie,语法如下: document.cookie="name=value; path=cookieDir"; *

* *

* 其中cookieDir表示可访问cookie的目录.例如: document.cookie="userId=320; path=/shop"; 就表示当前cookie仅能在shop目录下使用.
* 如果要使cookie在整个网站下可用,可以将cookie_dir指定为根目录,例如: document.cookie="userId=320; path=/"; *

*
* * @see 4.1.2.4. The Path Attribute * */ private String path = "/"; /** * ;Secure ... e.g. use SSL. * *

* 指定是否cookie应该只通过安全协议,例如HTTPS或SSL,传送给浏览器. *

* *

* secure值为true时,在http中是无效的; 在https中才有效 *

* *

* keep cookie communication limited to encrypted transmission, directing browsers to use cookies only * via secure/encrypted connections. *

*

* However, if a web server sets a cookie with a secure attribute from a non-secure connection, the * cookie can still be intercepted when it is sent to the user by man-in-the-middle attacks.
* Therefore, for maximum security, cookies with the Secure attribute should only be set over a secure connection. *

* * @see 4.1.2.5. The Secure Attribute */ private boolean secure; /** * 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. *

* *

* ;Version=1 ... means RFC 2109++ style *

* */ private int version = 0; /** * Not in cookie specs, but supported by browsers. * *

* 如果在Cookie中设置了"HttpOnly"属性,那么通过程序(JS脚本、Applet等)将无法读取到Cookie信息,这样能有效的防止XSS攻击. *

* * @see 4.1.2.6. The HttpOnly Attribute */ private boolean httpOnly; //--------------------------------------------------------------- /** * The Constructor. */ public CookieEntity(){ super(); } /** * The Constructor. * * @param name * name名称,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. * @param value * value,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. *

* 注意:如果值长度超过4K,浏览器会忽略,不会执行记录的操作 *

*/ public CookieEntity(String name, String value){ this.name = name; this.value = value; } /** * The Constructor. * * @param name * name名称,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. * @param value * value,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. *

* 注意:如果值长度超过4K,浏览器会忽略,不会执行记录的操作 *

* @param maxAge * 设置存活时间,单位秒. *
* * * * * * * * * * * * * * * * * *
字段说明
正数(positive value)则表示该cookie会在max-age秒之后自动失效.
* 浏览器会将max-age为正数的cookie持久化,即写到对应的cookie文件中.无论客户关闭了浏览器还是电脑,只要还在max-age秒之前,登录网站时该cookie仍然有效 .
负数(negative value)表示不保存不持久化,当浏览器退出就会删除
0(zero value)表示删除
*
* * 默认和servlet 保持一致,为-1,表示不保存不持久化, 浏览器退出就删除,如果需要设置有效期,可以调用 {@link TimeInterval}类 *

* ;Max-Age=VALUE *

*/ public CookieEntity(String name, String value, int maxAge){ this.name = name; this.value = value; this.maxAge = maxAge; } //--------------------------------------------------------------- /** * Gets the name名称,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. * * @return the name名称,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号 */ public String getName(){ return name; } /** * Sets the name名称,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. * * @param name * the new name名称,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号 */ public void setName(String name){ this.name = name; } /** * value,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. * *

* 注意:如果值长度超过4K,浏览器会忽略,不会执行记录的操作 *

* *

关于 non-ASCII (Unicode) characters:

*
* * What isn't mentioned and browsers are totally inconsistent about, is non-ASCII (Unicode) characters: * *
    *
  1. in Opera and Google Chrome, they are encoded to Cookie headers with UTF-8;
  2. * *
  3. in IE, the machine's default code page is used (locale-specific and never UTF-8);
  4. * *
  5. * Firefox (and other Mozilla-based browsers) use the low byte of each UTF-16 code point on its own (so ISO-8859-1 is OK but * anything else is mangled); *
  6. * *
  7. Safari simply refuses to send any cookie containing non-ASCII characters.
  8. * *
* *

* so in practice you cannot use non-ASCII characters in cookies at all.
* If you want to use Unicode, control codes or other arbitrary byte sequences,
* the cookie_spec demands you use an ad-hoc encoding scheme of your own choosing and suggest URL-encoding (as produced * by JavaScript's encodeURIComponent) as a reasonable choice. *

* *
* * @return the value,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号 */ public String getValue(){ return value; } /** * value,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号. * *

* 注意:如果值长度超过4K,浏览器会忽略,不会执行记录的操作 *

* *

关于 non-ASCII (Unicode) characters:

*
* * What isn't mentioned and browsers are totally inconsistent about, is non-ASCII (Unicode) characters: * *
    *
  1. in Opera and Google Chrome, they are encoded to Cookie headers with UTF-8;
  2. * *
  3. in IE, the machine's default code page is used (locale-specific and never UTF-8);
  4. * *
  5. * Firefox (and other Mozilla-based browsers) use the low byte of each UTF-16 code point on its own (so ISO-8859-1 is OK but * anything else is mangled); *
  6. * *
  7. Safari simply refuses to send any cookie containing non-ASCII characters.
  8. * *
* *

* so in practice you cannot use non-ASCII characters in cookies at all.
* If you want to use Unicode, control codes or other arbitrary byte sequences,
* the cookie_spec demands you use an ad-hoc encoding scheme of your own choosing and suggest URL-encoding (as produced * by JavaScript's encodeURIComponent) as a reasonable choice. *

* *
* * @param value * the new value,名字和值都不能包含空白字符以及下列字符: @ : ;? , " / [ ] ( ) = 这些符号 */ public void setValue(String value){ this.value = value; } /** * 获得 设置存活时间,单位秒. *
* * * * * * * * * * * * * * * * * *
字段说明
正数(positive value)则表示该cookie会在max-age秒之后自动失效.
* 浏览器会将max-age为正数的cookie持久化,即写到对应的cookie文件中.无论客户关闭了浏览器还是电脑,只要还在max-age秒之前,登录网站时该cookie仍然有效 .
负数(negative value)表示不保存不持久化,当浏览器退出就会删除
0(zero value)表示删除
*
* * @return the maxAge * @see 4.1.2.2. The Max-Age Attribute */ public int getMaxAge(){ return maxAge; } /** * 设置 设置存活时间,单位秒. *
* * * * * * * * * * * * * * * * * *
字段说明
正数(positive value)则表示该cookie会在max-age秒之后自动失效.
* 浏览器会将max-age为正数的cookie持久化,即写到对应的cookie文件中.无论客户关闭了浏览器还是电脑,只要还在max-age秒之前,登录网站时该cookie仍然有效 .
负数(negative value)表示不保存不持久化,当浏览器退出就会删除
0(zero value)表示删除
*
* * @param maxAge * the maxAge to set * @see 4.1.2.2. The Max-Age Attribute */ public void setMaxAge(int maxAge){ this.maxAge = maxAge; } /** * 获得 ;Comment=VALUE . * * @return the comment */ public String getComment(){ return comment; } /** * 设置 ;Comment=VALUE . * * @param comment * the comment to set */ public void setComment(String comment){ this.comment = comment; } /** * 获得 ;Domain=VALUE. * *

* 和路径类似,主机名是指同一个域下的不同主机,例如:www.google.com和gmail.google.com就是两个不同的主机名.
* 默认情况下,一个主机中创建的cookie在另一个主机下是不能被访问的,
* 但可以通过domain参数来实现对其的控制,
* 其语法格式为: document.cookie="name=value; domain=cookieDomain"; *

* *

示例:

* *
*

* 以google为例,要实现跨主机访问,可以写为: document.cookie="name=value;domain=.google.com";
* 这样,所有google.com下的主机都可以访问该cookie. *

*
* * @return the domain * @see 4.1.2.3. The Domain Attribute */ public String getDomain(){ return domain; } /** * 设置 ;Domain=VALUE . * *

* 和路径类似,主机名是指同一个域下的不同主机,例如:www.google.com和gmail.google.com就是两个不同的主机名.
* 默认情况下,一个主机中创建的cookie在另一个主机下是不能被访问的,
* 但可以通过domain参数来实现对其的控制,
* 其语法格式为: document.cookie="name=value; domain=cookieDomain"; *

* *

示例:

* *
*

* 以google为例,要实现跨主机访问,可以写为: document.cookie="name=value;domain=.google.com";
* 这样,所有google.com下的主机都可以访问该cookie. *

*
* * @param domain * the domain to set * @see 4.1.2.3. The Domain Attribute */ public void setDomain(String domain){ this.domain = domain; } /** * 获得 ;Path=VALUE . * * ;Path=VALUE ... URLs that see the cookie * *

* 当不设置值的时候(tomcat默认情况),如果在某个页面创建了一个cookie,那么该页面所在目录中的其他页面也可以访问该cookie,如果这个目录下还有子目录,则在子目录中也可以访问.
* 为了方便使用cookie,特意将此默认值设置为/,表示所有页面均可读取改cookie *

* *

示例:

* *
*

* 例如在www.xxxx.com/html/a.html中所创建的cookie,可以被www.xxxx.com/html/b.html或www.xxx.com/html/some/c.html所访问,
* 但不能被www.xxxx.com/d.html访问. *

* *

* 为了控制cookie可以访问的目录,需要使用path参数设置cookie,语法如下: document.cookie="name=value; path=cookieDir"; *

* *

* 其中cookieDir表示可访问cookie的目录.例如: document.cookie="userId=320; path=/shop"; 就表示当前cookie仅能在shop目录下使用.
* 如果要使cookie在整个网站下可用,可以将cookie_dir指定为根目录,例如: document.cookie="userId=320; path=/"; *

*
* * @return the path * * @see 4.1.2.4. The Path Attribute */ public String getPath(){ return path; } /** * 设置 ;Path=VALUE . * * ;Path=VALUE ... URLs that see the cookie * *

* 当不设置值的时候(tomcat默认情况),如果在某个页面创建了一个cookie,那么该页面所在目录中的其他页面也可以访问该cookie,如果这个目录下还有子目录,则在子目录中也可以访问.
* 为了方便使用cookie,特意将此默认值设置为/,表示所有页面均可读取改cookie *

* *

示例:

* *
*

* 例如在www.xxxx.com/html/a.html中所创建的cookie,可以被www.xxxx.com/html/b.html或www.xxx.com/html/some/c.html所访问,
* 但不能被www.xxxx.com/d.html访问. *

* *

* 为了控制cookie可以访问的目录,需要使用path参数设置cookie,语法如下: document.cookie="name=value; path=cookieDir"; *

* *

* 其中cookieDir表示可访问cookie的目录.例如: document.cookie="userId=320; path=/shop"; 就表示当前cookie仅能在shop目录下使用.
* 如果要使cookie在整个网站下可用,可以将cookie_dir指定为根目录,例如: document.cookie="userId=320; path=/"; *

*
* * @param path * the path to set * * @see 4.1.2.4. The Path Attribute */ public void setPath(String path){ this.path = path; } /** * ;Secure ... e.g. use SSL. * *

* 指定是否cookie应该只通过安全协议,例如HTTPS或SSL,传送给浏览器. *

* *

* secure值为true时,在http中是无效的; 在https中才有效 *

* *

* keep cookie communication limited to encrypted transmission, directing browsers to use cookies only * via secure/encrypted connections. *

*

* However, if a web server sets a cookie with a secure attribute from a non-secure connection, the * cookie can still be intercepted when it is sent to the user by man-in-the-middle attacks.
* Therefore, for maximum security, cookies with the Secure attribute should only be set over a secure connection. *

* * @return the secure * * @see 4.1.2.5. The Secure Attribute */ public boolean getSecure(){ return secure; } /** * ;Secure ... e.g. use SSL. * *

* 指定是否cookie应该只通过安全协议,例如HTTPS或SSL,传送给浏览器. *

* *

* secure值为true时,在http中是无效的; 在https中才有效 *

* *

* keep cookie communication limited to encrypted transmission, directing browsers to use cookies only * via secure/encrypted connections. *

*

* However, if a web server sets a cookie with a secure attribute from a non-secure connection, the * cookie can still be intercepted when it is sent to the user by man-in-the-middle attacks.
* Therefore, for maximum security, cookies with the Secure attribute should only be set over a secure connection. *

* * @param secure * the secure to set * * @see 4.1.2.5. The Secure Attribute */ public void setSecure(boolean secure){ this.secure = secure; } /** * 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. *

* *

* ;Version=1 ... means RFC 2109++ style *

* * @return the version */ public int getVersion(){ return version; } /** * 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. *

* *

* ;Version=1 ... means RFC 2109++ style *

* * @param version * the version to set */ public void setVersion(int version){ this.version = version; } /** * Not in cookie specs, but supported by browsers. * *

* 如果在Cookie中设置了"HttpOnly"属性,那么通过程序(JS脚本、Applet等)将无法读取到Cookie信息,这样能有效的防止XSS攻击. *

* * @return the httpOnly * @see 4.1.2.6. The HttpOnly Attribute */ public boolean getHttpOnly(){ return httpOnly; } /** * Not in cookie specs, but supported by browsers. * *

* 如果在Cookie中设置了"HttpOnly"属性,那么通过程序(JS脚本、Applet等)将无法读取到Cookie信息,这样能有效的防止XSS攻击. *

* * @param httpOnly * the httpOnly to set * @see 4.1.2.6. The HttpOnly Attribute */ public void setHttpOnly(boolean httpOnly){ this.httpOnly = httpOnly; } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy