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的方式使用