urlrewrite.xml配置文件中的元素分析

转载：点击打开链接

urlrewrite.xml配置文件中的元素分析

配置文件是一个放在WEB-INF文件夹下，命名为urlrewrite.xml名称的简单的xml文件, UrlRewriteFilter DTD 文件对学习并理解该配置文件非常有效.可以去官网下载最新的DTD(http://tuckey.org/urlrewrite/manual/3.0/index.html)

(由于英语水平有限，官网都是英文，有不到之处，敬请谅解)

1、urlrewrite.xml有一个根元素urlrewrite，并且至少包含一个匹配规则rule

2、一个rule元素内必须包含一个from元素和一个to元素，但是condition元素和set元素可以没有，也可以有多个

3、当一个rule元素拦截请求时，所有的condition元素都要满足。这个请才会与from匹配

optional:可选的

<urlrewrite>元素:

顶级元素：里面的属性值都是可选的

Attribute	Possible Value	Explanation
default-match-type  (optional)	regex (default)	当用正则表达式时，所有的rule和conditions都会被审查(除非match-type指定一个特定的值在rule)
	wildcard	用通配符时,所有的rule和conditions都会被审查(除非match-type指定一个特定的值在rule)
decode-using  (optional)	utf8 (default)	编码时用的编码:utf-8
	null	不指定编码
	[encoding]	指定一个支持的编码  例如：ISO-8859-1，GBK等.
use-query-string  (optional)	false (default)	查询字符串不会被附加到匹配的from元素后面
	true	查询字符串将会被附加到匹配的from元素后面
use-context  (optional)	false (default)	应用路径不会被附加到匹配的from元素后面
	true	应用路径将会被附加到匹配的from元素后面

<rule>元素（Zero or more. The basis of a rule.）：

Attribute	Possible Value	Explanation
enabled  (optional)	true (default)	启用这个rule
	false	禁用这个rule.
match-type  (optional)	regex (default)	这个rules和它的conditions将会被正则表达式审查
	wildcard	这个rules和它的conditions将会被通配符审查

正则表达式：

 <rule match-type="regex">
       <from>^/world/([a-z]+)/([a-z]+)$</from>
       <to>/world.jsp</to>
    </rule>

通配符：

    <rule match-type="wildcard">
       <from>/world/*/*</from>
       <to>/world.jsp</to>
    </rule>

<outbound-rule>元素（zero or more）：

这个和正常的rule相似，只不过是用来重写通过用response.encodeURL()来请求的url

Attribute	Possible Value	Explanation
enabled  (optional)	true (default)	启用这个rule
	false	禁用这个 rule.
encodefirst  (optional)	false (default)	执行完outbound-rule之后执行encodeURL()
	true	在执行outbound-rule之前执行encodeURL()

    <outbound-rule>
        <from>^/world.jsp?country=([a-z]+)&amp;city=([a-z]+)$</from>
        <to>/world/$1/$2</to>
    </outbound-rule>

用上面的规则执行下面的代码：

<a href="<%= response.encodeURL("/world.jsp?country=usa&amp;city=nyc") %>">nyc</a>  

     将会输出：

<a href="/world/usa/nyc">nyc</a>

或者使用：
<a href="<c:url value="/world.jsp?country=${country}&amp;city=${city}" />">nyc</a>也输出 <a href="/world/usa/nyc">nyc</a>

<name>元素：

这是一个可选的参数用于定义rule的名称，也可以用于outbound-rule

<rule>
        <name>World Rule</name>
        <from>^/world/([a-z]+)/([a-z]+)$</from>
        <to>/world.jsp?country=$1&amp;city=$2</to>
    </rule>

<note>元素：

一个简单的可选参数，用于说明rule和outbound-rule的说明

 <rule>
        <name>World Rule</name>
        <note>
            Cleanly redirect world requests to JSP,
            a country and city must be specified.
            </note>
        <from>^/world/([a-z]+)/([a-z]+)$</from>
        <to>/world.jsp</to>
    </rule>

<condition>元素：

一个为rule设置conditions的元素，所有的conditions在rule拦截时都会执行（除非next设置为or）

Attribute	Possible Value	Explanation
type  (optional)	header (default)	如果用这个，则header 名字必须命名为"name"的属性值
	method	请求的方法  GET、POST、HEAD等
	port	应用服务器运行的端口
	time	服务器的当前时间（从00:00:00 1970-01-01 UTC开始的秒数 i.e. (new Date()).getTime()
	year	服务的年份 i.e. (Calendar.getInstance()).get(Calendar.YEAR)
	month	服务器的月份  i.e. (Calendar.getInstance()).get(Calendar.MONTH)
	dayofmonth	返回服务器一个月中的第几天. March first is 1  i.e. (Calendar.getInstance()).get(Calendar.DAY_OF_MONTH)
	dayofweek	返回服务器一周中的第几天. Saturday is 1, Sunday is 7  i.e. (Calendar.getInstance()).get(Calendar.DAY_OF_WEEK)
	ampm	返回服务器上午或者下午时间 i.e. (Calendar.getInstance()).get(Calendar.AM_PM)
	hourofday	返回一天的小时(24小时) i.e. (Calendar.getInstance()).get(Calendar.HOUR_OF_DAY)
	minute	返回服务器当前时间的分钟数 i.e. (Calendar.getInstance()).get(Calendar.MINUTE)
	second	返回当前时间的秒数 i.e. (Calendar.getInstance()).get(Calendar.SECOND)
	millisecond	返回当前服务器的毫秒数.  i.e. (Calendar.getInstance()).get(Calendar.MILLISECOND)
	attribute	检查请求属性的值(不要和parameter混淆)，当用这个属性时，name必须被设置 i.e. request.getAttribute([name])
	auth-type	检查请求属性的值(不要和parameter混淆) i.e. request.getAuthType()
	character-encoding	请求的编码 i.e. request.getCharacterEncoding()
	content-length	请求的长度(可以用来拒绝大数据的请求) i.e. request.getContentLength()
	content-type	请求的类型 i.e. request.getContentType()
	context-path	请求的应用路径 i.e. request.getContextPath()
	cookie	cookie的值，用这个的时候必须指定名字 i.e. request.getCookies() 根据指定的名字获得值并检查值
	parameter	一个比在查询字符串中寻找参数的更简单的方式，name必须指定.  i.e. request.getParameter([name])
	path-info	i.e. request.getPathInfo()
	path-translated	i.e. request.getPathTranslated()
	protocol	请求的协议  e.g. HTTP/1.1  i.e. request.getProtocol()
	query-string	用于请求的查询字符串, e.g. id=2345&name=bob  i.e. request.getQueryString()
	remote-addr	获取请求的ip地址, e.g. 123.123.123.12  i.e. request.getRemoteAddr()
	remote-host	获取请求的主机名, e.g. 123qw-dsl.att.com (这个仅在你的应用服务器配置主机名的情况下有效，但是大部分都不配置).  i.e. request.getRemoteHost()
	remote-user	获取请求的用户名，如果用户名认证过  i.e. request.getRemoteUser()
	requested-session-id	返回客户端的sessionId, i.e. request.getRequestedSessionId()
	request-uri	i.e. request.getRequestURI()
	request-url	i.e. request.getRequestURL()
	session-attribute	(note, name must be set)  i.e. session.getAttribute([name])
	session-isnew	检查session是否是新的 i.e. session.isNew()
	server-name	The host name of the server to which the request was sent (from the host header not the machine name).  i.e. request.getServerName()
	scheme	返回请求的模式, e.g. http or https  i.e. request.getScheme()
	user-in-role	(Note, 值不能是一个正则表达式)  i.e. request.isUserInRole([value])
name  (optional)	(can be anything)	如果type是header，那么指定的http header的名称和这个名字相对
next  (optional)	and (default)	下一个rule和这个rule必须匹配
	or	下一个rule和这个rule可能匹配
operator  (optional)	equal (default)	当conditions被设置，正则表达式必须匹配或者值相等.
	notequal	请求的值不等于条件的值.这个运算符仅用于数字类型
	greater	请求的值大于条件的值.这个运算符仅用于数字类型
	less	请求的值小于条件的值.这个运算符仅用于数字类型
	greaterorequal	请求的值大于等于条件的值.这个运算符仅用于数字类型
	lessorequal	请求的值小于等于条件的值.这个运算符仅用于数字类型

    

<from>元素：

必须定义一个from 为每个rule或者outbound-rule.

Attribute	Possible Value	Explanation
casesensitive  (optional)	false (default)	大小写不敏感匹配. ie, "/WellingtoN" 匹配 "/wellington".
	true	大小写敏感匹配. ie, "/aAa" 不匹配 "/aaa".

例如：

    <from>^/world/([a-z]+)$</from>

<to>元素：

值中也可以使用正则表达式

Attribute	Possible Value	Explanation
type  (optional)	forward (default)	(和conditions匹配的请求rule，在rule中from中的url将会被转发到to元素中指定的url) Requests matching the "conditions" for this "rule", and the URL in the "from" element will be internally forwarded to the URL specified in the "to" element. (这种情况下，to元素中的url必须在同一应用) Note: In this case the "to" URL must be in the same context as UrlRewriteFilter. This is the same as doing:  RequestDispatcher rq = request.getRequestDispatcher([to value]);  rq.forward(request, response);
	passthrough	Identical to "forward".(和forward相同)
	redirect	(请求和conditions、from匹配时候将惠执行http redirected)Requests matching the "conditions" and the "from" for this rule will be HTTP redirected. This is the same a doing:  HttpServletResponse.sendRedirect([to value]))
	permanent-redirect	The same as doing:  response.setStatus(HttpServletResponse.SC_MOVED_PERMANENTLY);  response.setHeader("Location", [to value]);  (note, SC_MOVED_TEMPORARILY is HTTP status code 301)
	temporary-redirect	The same as doing: (和这个一样) response.setStatus(HttpServletResponse.SC_MOVED_TEMPORARILY);  response.setHeader("Location", [to value]);  (note, SC_MOVED_TEMPORARILY is HTTP status code 302)
	pre-include
	post-include
last  (optional)	false (default)	The rest of the "rules" will be processed if this one succeeds.(这个匹配成功后其他的rules将会被执行)
	true	No more "rules" will be processed if this one is a match.(匹配成功后不会有更多的rules被执行)
encode  (optional)	false (default if under rule)	(在重写执行之前response.encodeURL([to]) 将会被执行)
	true (default if under outbound-rule)	(response.encodeURL([to]) 不会被调用)

<set>元素：

当请求匹配rule时，可以设置一些值

Attribute	Possible Value	Explanation
type  (optional)	request (default)	和 request.setAttribute([name], [value]) 一样 (note, name必须被设置).
	session	和request.getSesison(true).setAttribute([name], [value])一样 (note, name必须被设置).
	response-header	和 response.setHeader([name], [value])一样 (note, name必须被设置t).
	cookie	值得格式是"[value][:domain[:lifetime[:path]]]". ，设置一个cookie在客户端浏览器，cookie的名字被name属性指定,filed是cookie的域 像'.apache.org'，可选参数lifetime是cookie的有效期，可选参数path是cookie的路径(名字必须设置) Value can be in the format "[value][:domain[:lifetime[:path]]]".  This sets a cookie on the client's browser. The cookie's name is specified by the name attribute. The field is the domain of the cookie, such as '.apache.org',the optional lifetime is the lifetime of the cookie in minutes, and the optional path is the path of the cookie (note, name must be set).
	status	和response.setStatus([value])一样
	content-type	与response.setContentType([value])类似
	charset	与 response.setContentType([value])类似
	locale	与 response.setLocale([value])类似 指定locale格式(有效的格式：, zh, zh-CN, zh-CN-southern i.e. "-"  分割语言，国家和各种变量(如果有)).
name  (optional)	(can be anything)	If type is request, session, response-header, cookie this specifies the name item.如果类型是request、session、response-header、cookie，指定条目名称

下面这个例子请求客户端被设置 "AvantGo" or "Samsung SCH-6100",这些值在servelte或者jsp中有request.getAttribute("client").可以获取

    <rule>
        <condition name="user-agent">Mozilla/3\.0 (compatible; AvantGo .*)</from>
        <from>.*</from>
        <set name="client">AvantGo</set>
    </rule>
    <rule>
        <condition name="user-agent">UP\.Browser/3.*SC03 .* </from>
        <from>.*</from>
        <set name="client">Samsung SCH-6100</set>
    </rule>

<run>元素：

当一个rule和它的conditions匹配时，可以在对象上执行一个方法

Attribute	Explanation
class	在对象上执行方法的类，必须是类全名
method (optional, default run)	要执行的方法，方法必须有参数(HttpServletRequest, HttpServletResponse) 例如： run(HttpServletRequest request, HttpServletResponse response)  注意, init(ServletConfig) or destroy() 将会被执行或者销毁在执行一个实例时
neweachtime (optional, default false)	如果你想在每次执行之前都创建新实例，请将参数设置为true

当rule匹配下面的例子时, WorldServlet.doGet(HttpServletRequest, HttpServletResponse)将会被执行,请求将会转发到 /world-presentation.jsp.

    <rule>
        <from>^/world/[a-z]+/[a-z]+$</from>
        <run class="com.blah.web.WorldServlet" method="doGet" />
        <to>/world-presentation.jsp</to>
    </rule>

注意： 你可以为servelt指定初始化参数（像给servelt指定一样）Note, you can specify init-param's the same way you would for a servlet.

    <run class="com.blah.web.MyServlet" method="doGet">
        <init-param>
            <param-name>someParamName</param-name>
            <param-value>10</param-value>
        </init-param>
    </run>

调用方法抛出异常时， 原始异常和RuntimeException异常的子类将会抛出RuntimeException ，其他异常将会抛出 ServletException，需要去处理它们

<class-rule>元素：

允许每个请求动态匹配时都执行一个方法(Allows you to run a method every time a request come in for 100% dynamic rules. See the org.tuckey.web.filters.urlrewrite.sample package for an example.)

Attribute	Explanation
class	在对象上执行方法的类，必须是类全名
method (optional, default matches)	要执行的方法，方法必须有参数(HttpServletRequest, HttpServletResponse) e.g. run(HttpServletRequest request, HttpServletResponse response)  注意, init(ServletConfig) or destroy() 将会被执行或者销毁在执行一个实例时
last (optional, default true	如果是false  及时它匹配到也会执行 接下来的rule（更好的匹配rule被发现）  If false more rules will be processed following this rule even if it is matched (so that a better match may be found).

Example:

    <class-rule class="com.blah.web.MyRuleClass" />