原文地址:http://blog.csdn.net/lgg201/archive/2010/02/27/5329364.aspx
安装
1. 下载 jar 包 , 并加入到 WEB-INF/lib 下
2. 在 WEB-INF/web.xml 中增加下面的配置
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>
org.tuckey.web.filters.urlrewrite.UrlRewriteFilter
</filter-class>
</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<!--
拦截所有的
url -->
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
3. 在 WEB-INF/ 下增加配置文件 urlrewrite.xml
4. 重启上下文环境
过滤器的参数
1. confReloadCheckInterval:
配置文件重加载间隔 . 0 表示随时加载 , -1 表示不重加载 , 默认 -1
2. confPath:
配置文件路径 . 是相对 context 的路径 , 默认 /WEB-INF/urlrewrite.xml
3. logLevel:
设置日志级别 , 可以是 : TRACE, DEBUG, INFO( 默认 ), WARN, ERROR, FATAL, log4j, commons, slf4j, sysout:{level}( 比如 sysout:DEBUG), 如果你使用普通的日志级别有一定困难 , 可以调为 : sysout:DEBUG( 表明是使用控制台输出的调试级别 )
4. statusPath:
设置改变状态路径 , 不能和已经安装的应用冲突 ( 注意 , 默认是 /rewrite-status), 注意 , 必须以 / 开始
5. statusEnabled:
设置 status 是否开启 , 期望得到的值是 true, false, 默认 true
6. statusEnabledOnHosts:
设置允许 status 的主机 , * 可以被用作通配符 , 默认是 ”localhost, local, 127.0.0.1”
7. modRewriteConf:
设置 rewrite 模式 , 默认是 false, 使用 mod-rewrite( 可以参照 apache 服务器的 mod_rewrite 相关资料 ) 方式的配置文件 , 如果设置为 true 并且 confPath 没有设置则配置文件路径将会被默认为 /WEB-INF/.htaccess
8. modRewriteConfText:
从这些参数的值加从载 mod_rewrite 样式的配置 , 设置这些参数则其他所有的参数都会被忽略 . 比如 :
<init-param>
<param-name>modRewriteConfText</param-name>
<param-value>
RewriteRule ^/~([^/]+)/?(.*) /u/$1/$2 [R]
RewriteRule ^/([uge])/([^/]+)$ /$1/$2/ [R]
</param-value>
</init-param>
9. allowConfSwapViaHttp:
设置是否允许通过 HTTP 方式交互设置参数 , 比如 , 通过调用 /rewrite-status/?conf=WEB-INF/urlrewrite2.xml
配置文件 WEB-INF/urlrewrite.xml
1. DTD 约束
<!DOCTYPE urlrewrite
PUBLIC "-//tuckey.org//DTD UrlRewrite 3.0//EN"
"http://tuckey.org/res/dtds/urlrewrite3.0.dtd">
2. <urlrewrite />
2.1. default-match-type( 可选 ):
2.1.1. regex, 默认 . 所有未指定 match-type 属性的 rule 都使用 java 正则表达式进行匹配
2.1.2. wildcard: 所有未指定 match-type 属性的 rule 都使用通配符匹配引擎匹配
2.2. decode-using( 可选 ):
2.2.1. header, utf8: 默认 . 使用 request.getCharacterEncoding() 得到的编码对 URL 解码 , 如果是空 , 使用 utf8.
2.2.2. null: 不进行解码 . 设置为 : decode-using=”null”
2.2.3. header: 仅仅使用 request.getCharacterEncoding() 解码
2.2.4. [encoding]: 仅仅使用一个指定的字符编码比如 ISO-8859-1.
2.2.5. header, [encoding]: 对一个 URL 解码时使用 request.getCharacterEncoding(), 如果得到的值为空 , 则使用 encoding 指定的编码 .
2.3. use-query-string( 可选 ):
2.3.1. false: 默认 . 在 from 进行匹配的时候 , 查询字符串不会参加
2.3.2. true: 查询字符串参与 from 的匹配
2.4. use-context( 可选 ):
2.4.1. false: 默认 . from 元素匹配时 , application 的 contex 路径将不会增加到 url 中
2.4.2. true: application 的 contex 路径参与 from 元素的匹配
3. <rule />: 0 个或多个
3.1. enabled( 可选 ):
3.1.1. true: 默认 . 允许这个规则
3.1.2. false: 废弃这个规则
3.2. match-type( 可选 ):
3.2.1. regex: 默认 . 使用 java 正则匹配
3.2.2. wildcard: 使用通配符表达式引擎
4. <outbound-ruld />: 0 个或多个 . 和普通的 rule 非常相似 , 但是这里是在 response.encodeURL() 方法调用时进行重写的 .
4.1. enabled( 可选 ):
4.1.1. true: 默认 . 允许规则
4.1.2. false: 废弃规则
4.2. encodefirst( 可选 ):
4.2.1. fasle: 默认 , 在运行了 encodeURL() 方法之后运用这个重写规则
4.2.2. true: 在 encodeURL() 之前运用这个重写规则
5. <name />: 一个用于记录规则名称的可选元素 , 可以在 <rule /> 和 <outbound-rule /> 上使用
6. <note />: 用于记录规则描述的一个简单可选元素 , 可以用在 <rule /> 和 <outbound-rule /> 上 .
7. <condition />: 针对规则的选择条件 . 注意 , 在规则运用的时候必须满足所有的条件 .
7.1. type( 可选 ):
7.1.1. header: 默认 . 如果设置 , 头名称必须通过 <condition /> 的 name 属性指定
7.1.2. method: 请求方法 . GET, POST, HEAD 等
7.1.3. port: application 运行的端口
7.1.4. time: 服务器当前时间 ( 使用 Unix 时间戳 ), 这个通常被用于确保内容仅在设置的时间存活
7.1.5. year: 服务器的当前年
7.1.6. month: 服务器的当前月份
7.1.7. dayofmonth: 当天是一月的第几天 , 每月第一天是 1
7.1.8. dayofweek: 当天是一周的第几天 , 星期天是 7
7.1.9. ampm: 上午或下午
7.1.10. hourofday: 一天的第多少小时 (24 小时制 )
7.1.11. minute: 当前服务器时间的分
7.1.12. second: 当前服务器时间的秒
7.1.13. millisecond: 当前服务器时间的毫秒
7.1.14. attribute: 检查 request 的属性 (getAttribute) 值 , 要检查的属性名称通过 <condition /> 的 name 指定
7.1.15. auth-type: 检查 request 属性的值 . request.getAuthType
7.1.16. character-encoding: 接收到请求的编码
7.1.17. content-length: 请求的长度 ( 对于拒绝响应大请求很有用 )
7.1.18. content-type: 请求类型
7.1.19. context-path: 请求的 contex 路径
7.1.20. cookie: 检查 cookie 值 , cookie 的名称通过 <condition /> 的 name 属性指定
7.1.21. parameter: 检查请求参数 , 参数名称通过 <condition /> 的 name 属性指定
7.1.22. path-info: 相当于 request.getPathInfo()
7.1.23. path-translated: 相当于 request.getTranslated()
7.1.24. protocol: 用于过滤协议
7.1.25. query-string: 得到 url 后面的参数字符串
7.1.26. remote-addr: IP 地址过滤
7.1.27. remote-host: 远程主机过滤 ( 注意 , 仅仅在应用服务器配置了查看 ( 远程 ) 主机名时才可用 )
7.1.28. remote-user: 当前登录用户 , 如果用户被授权可用
7.1.29. requested-session-id: 当前 session 的 id
7.1.30. request-uri: 请求 URL 的从协议名到查询字符串部分
7.1.31. request-url: 重构后的 URL, 返回的 URL 包含协议 , 服务器名称 , 端口 , 路径 , 但不包含查询字符串
7.1.32. session-attribute: 检查 session 中的属性 (getAttribute), 属性名称通过 <condition /> 的 name 属性设置 .
7.1.33. session-isnew: 检查 session 是不是新的
7.1.34. server-name: 请求发送到的服务器的主机名 ( 从 host 这个头中得到的不是机器名 )
7.1.35. scheme: 请求的 scheme
7.1.36. user-in-role: 注意 , 这里的值不能是正则表达式
7.2. name: 配合一些特殊 type 使用的 , 可以是任何值
7.3. next:
7.3.1. and: 默认 . 下一个和这一个条件都必须匹配
7.3.2. or: 下一个或这一个条件匹配
7.4. operator:
7.4.1. equal: 默认 . 指定正则和真实值匹配
7.4.2. notequal: 真实值和正则不匹配
7.4.3. greater: 大于 , 仅用于数值
7.4.4. less: 小于
7.4.5. greaterorequal: 大于等于
7.4.6. lessorequal: 小于等于
8. <from />: 通常在 <rule /> 和 <outbound-rule /> 中都必须指定一个 , 值可以是正则表达式 (Perl5 方式的正则 ), 注意 : from 指定的 url 是和 contex 相关的
8.1. casesensitive:
8.1.1. false: 默认 . 大小写不敏感
8.1.2. true: 大小写敏感
9. <to />: 可以是一个 perl5 样式的正则替换表达式
9.1. type:
9.1.1. forward: 默认 . 请求匹配这个 <rule /> 的所有 <condition />, 并且 URL 使用内部跳转到 ”to” 指定的地址 ( 注意 , 这里 forward 到的 URL 必须和 UrlRewriteFilter 位于同一个容器中 )
9.1.2. passthrough: 和 forward 相同
9.1.3. redirect: 请求匹配所有 <condition /> 和这个 <rule /> 的 <from />, 通知客户端跳转到 <to /> 指定地址
9.1.4. permanent-redirect: 相当于做了以下事情
response.setStatus(
HttpServletResponse.SC_MOVED_PERMANENTLY
);
response.setHeader(“Location”, [<to /> 指定的值 ]);
9.1.5. temporary-redirect: 相当于做了以下事情
response.setStatus(
HttpServletResponse. SC_MOVED_TEMPORARILY
);
response.setHeader(“Location”, [<to /> 指定的值 ]);
9.1.6. pre-include
9.1.7. post-include
9.1.8. proxy: 请求 URL 将会以全路径被代理 , 使用此特性需要引入 commons-http 和 commons-codec 包
9.2. last:
9.2.1. false: 默认 . 其余 <rule /> 将会处理如果这个匹配
9.2.2. true: 如果匹配这个规则将不会处理
9.3. encode:
9.3.1. false: <rule /> 下是默认值 . 在 rewrite 之前 , 用 response.encodeURL([to 的值 ]) 编码 URL
9.3.2. true: <outbound-rule /> 下默认值 . 不会编码 URL
9.4. context:
如果应用服务器配置了允许 ” 穿透 context” 通信 , 那么这个属性可以被用于 forward( 并且仅仅能用于 forward) 请求到另外一个 serlvet context….. 也就是跨应用 forward
在 Tomcat 上 , server.xml 或 context.xml 中配置 crossContext=”true”, 例如 : 允许两个应用 ”app” 和 ”forum” 之间通信 , 那么可以如下配置 :
<Context docBase=”app” path=”/app” reloadable=”true” crossContext=”true” />
<Context docBase=”forum” path=”/forum” reloadable=”true” crossContext=”true” />
10. <to /> 的其他方面
10.1. <to /> 可以是 null, 意义为 : 如果匹配请求不再继续 , 相当于没有调用 chain.doFilter
10.2. 使用 $N 获取 <from /> 中配置的子组 , N 必须是 1 至 10 之间的数
10.3. 任何 <condition /> 中可以使用的 type 中的值都可以在 <to /> 中使用 , 比如 <to>/%{parameter:page}</to>
10.4. 函数调用 : ${ 函数名 : 参数 1: 参数 2} 可以在 <set /> 和 <to /> 中使用
name | example | example returns |
replace | ${replace:my cat is a blue cat:cat:dog} | my dog is a blue dog |
replaceFirst | ${replace:my cat is a blue cat:cat:dog} | my cat is a blue dog |
escape | ${escape:a b c} | a+b+c |
unescape | ${unescape:a+b+c} | a b c |
lower | ${lower:Hello World} | hello world |
upper | ${upper:hello} | HELLO |
trim | ${trim: abc def } | abc def |
11. <set />: 在匹配规则的时候 , 允许设置一些值 .
11.1. type:
11.1.1. request: 默认 . 类似于 request.setAttribute
11.1.2. session: session.setAttribute
11.1.3. response-header: response.setHeader
11.1.4. cookie: 值以 ”[value][:domain[:lifetime[:path]]]” 的格式设置 . 是指给客户端浏览器设置 cookie, cookie 名称由 <set /> 的 name 属性指定
11.1.4.1. value: cookie 的值
11.1.4.2. domain: 服务器
11.1.4.3. lifetime: 存货时间
11.1.4.4. path: cookie 的 path
11.1.5. status: response.setStatus
11.1.6. content-type: response.setContentType
11.1.7. charset: response.setCharacterEncoding
11.1.8. expires: 设置 HTTP 头中的过期时间 , 设置的格式为 { 数值 类型 }, 比如 : “1 day 2 seconds”
11.1.9. locale: response.setLocale
11.1.10. parameter: 允许将 request.getParameter 得到的某个参数的值在这里进行重新处理
11.1.11. method: 允许将 request.getMethod() 得到的值进行重新处理
11.2. name: type 是 request, session, response-header, cookie 的时候 , 必须设置 name
11.3. 举例 :
<rule>
<condition name=”user-agent”>Mozilla/3/.0 (compatible; AvantGo .*)</condition>
<from>.*</from>
<set name=”client”>AvantGo</set>
</rule>
<rule>
<condition name=”user-agent”>UP/.Browser/3.*SC03 .*</condition>
<from>.*</from>
<set name=”client”>Samsung SCH-6100</set>
</rule>
12. <run />: 允许在 <rule /> 和 <condition /> 都匹配的时候 , 执行一个对象方法
12.1. class: 全限定名的类名 , 期望调用方法的类名 .
12.2. method( 可选 ): 默认值为 run. 期望调用的方法名 . 该方法必须有两个参数 (HttpServletRequest request, HttpServletResponse response). 注意 , 如果该对象有 init(ServletConfig) 或 destroy() 方法 , 在创建和销毁对象的时候会自动调用 , ServletConfig 中可以得到初始化参数 , 参数通过 <init-param /> 的方式传递 :
<run class=”selfimpr.MyServlet” method=”doGet”>
<init-param>
<param-name>id</param-name>
<param-value>1</param-value>
</init-param>
</run>
12.3. neweachtime: 默认 false. 表明是否每次请求都创建一个对象实例 .
13. Tip
13.1. 在配置中如果要使用 ”&”, 用 &
13.2. 简单起见 , 给 <from /> 的配置前面和后面分别加上 ^, $, 这两个是正则表达式中的强制开始和结尾标志
13.3. 如果使用 <outbound-rule> 要记得代码中的 url 都是编码过的
13.4. 正则表达式非常复杂灵活 , 请阅读 java.util.regex.Pattern 中的 java 正则介绍
13.5. 如果觉得正则难以理解 , 可以使用通配符方式
13.6. contex 是非常重要的 , 如果有一个应用的 context 是 ”/myapp”, 并且你的请求是 ”/myapp/somefolder/somepage.jsp”, 容器交给 UrlRewriteFilter 的 url 会是 ”/somefolder/somepage.jsp”, 这可能难以理解 , 但是在你的 <rule> 和 <condition> 中不要包含 context path, 它是容器负责处理的 .
14. 通配符 :
通配符匹配引擎可以替代正则表达式 , 在 <condition> 和 <rule> 中设置 match-type 是 wildcard 用以开启支持通配符 .( 或者设置 default-match-type)
例如 :
/big/url/* 匹配 /big/url/abc.html 但是不匹配 /big/url/abc/dir/ 或 /big/url/abc/
/big/url/** 匹配 /big/url/abc.html, /big/url/abc/dir/ 和 /big/url/abc/
也可以和正则的替换一样 , 每个 * 代表一个参数 , 在 <set> 和 <to> 中用 $N 的方式使用
使用 mod-rewrite 样式的配置
filter 配置
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
<!-- defaults to false. use mod_rewrite style configuration file (if this is true and confPath
is not specified confPath will be set to /WEB-INF/.htaccess) -->
<init-param>
<param-name>modRewriteConfText</param-name>
<param-value><![CDATA[
# redirect mozilla to another area
RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
RewriteRule ^/no-moz-here$ /homepage.max.html [L]
]]></param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
WEB-INF/.htaccess 下的具体匹配配置
# redirect mozilla to another area
RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
RewriteRule ^/no-moz-here$ /homepage.max.html [L]
URL 注解匹配
1. urlrewrite3.0 之后 , 使用 JDK1.6 及以上可以使用注解来生成 urlrewrite 的配置文件 .