Java-UrlRewrite中文官方文档

原文地址: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

[/code]

PUBLIC "-//tuckey.org//DTD UrlRewrite 3.0//EN"

[/code]

"http://tuckey.org/res/dtds/urlrewrite3.0.dtd">

[/code]
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
的配置文件
.