狂淘

<!ELEMENT web-app (icon?, display-name?, description?,
distributable?, context-param*, filter*, filter-mapping*,
listener*, servlet*, servlet-mapping*, session-config?,
mime-mapping*, welcome-file-list?,
error-page*, taglib*, resource-env-ref*, resource-ref*,
security-constraint*, login-config?, security-role*,env-entry*,
ejb-ref*, ejb-local-ref*)>

正如您所看到的，這個(gè)元素含有23個(gè)子元素，而且子元素都是可選的。問(wèn)號(hào)(？)表示子元素是可選的，而且只能出現(xiàn)一次。星號(hào)(*)表示子元素可在部署描述符中出現(xiàn)零次或多次。有些子元素還可以有它們自己的子元素。
web.xml文件中web-app元素聲明的是下面每個(gè)子元素的聲明。下面的章節(jié)講述部署描述符中可能包含的所有子元素。
注意：
在Servlet 2.3中，子元素必須按照DTD文件語(yǔ)法描述中指定的順序出現(xiàn)。比如，如果部署描述符中的web-app元素有servlet和servlet-mapping兩個(gè)子元素，則servlet子元素必須出現(xiàn)在servlet-mapping子元素之前。在Servlet 2.4中，順序并不重要。
下面對(duì)web.xml文件各元素進(jìn)行詳解

1. icon元素
icon元素用來(lái)指定GIF格式或JPEG格式的小圖標(biāo)(16×16)或大圖標(biāo)(32×32)的文件名。

<!ELEMENT icon (small-icon?, large-icon?)>
<!ELEMENT small-icon (#PCDATA)>
<!ELEMENT large-icon (#PCDATA)>

icon元素包括兩個(gè)可選的子元素：small-icon子元素和large-icon子元素。文件名是Web應(yīng)用歸檔文件(WAR)的根的相對(duì)路徑。
部署描述符并沒(méi)有使用icon元素。但是，如果使用XML工具編輯部署描述符，XML編輯器可以使用icon元素。

2. display-name元素
如果使用工具編輯部署描述符，display-name元素包含的就是XML編輯器顯示的名稱。

<!ELEMENT display-name (#PCDATA)>

下面是一個(gè)含有display-name元素的部署描述符：

3. description元素
可以使用description元素來(lái)提供有關(guān)部署描述符的信息。XML編輯器可以使用description元素的值。

<!ELEMENT description (#PCDATA)>

4. distributable元素
可以使用distributable元素來(lái)告訴servlet/JSP容器，編寫(xiě)將在分布式Web容器中部署的應(yīng)用：

<!ELEMENT distributable EMPTY>

例如，下面是一個(gè)含有distributable元素的部署描述符的例子：

5. context-param元素
context-param元素含有一對(duì)參數(shù)名和參數(shù)值，用作應(yīng)用的servlet上下文初始化參數(shù)。參數(shù)名在整個(gè)Web應(yīng)用中必須是惟一的。

<!ELEMENT context-param (param-name, param-value, description?)>
<!ELEMENT param-name (#PCDATA)>
<!ELEMENT param-value (#PCDATA)>
<!ELEMENT description (#PCDATA)>

param-name 子元素包含有參數(shù)名，而param-value子元素包含的是參數(shù)值。作為選擇，可用description子元素來(lái)描述參數(shù)。

下面是一個(gè)含有context-param元素的有效部署描述符：

6. filter元素
filter元素用于指定Web容器中的過(guò)濾器。在請(qǐng)求和響應(yīng)對(duì)象被servlet處理之前或之后，可以使用過(guò)濾器對(duì)這兩個(gè)對(duì)象進(jìn)行操作。利用下一節(jié)介紹 的filter-mapping元素，過(guò)濾器被映射到一個(gè)servlet或一個(gè)URL模式。這個(gè)過(guò)濾器的filter元素和filter-mapping 元素必須具有相同的名稱。

<!ELEMENT filter (icon?, filter-name, display-name?, description?,
filter-class, init-param*)>
<!ELEMENT filter-name (#PCDATA)>
<!ELEMENT filter-class (#PCDATA)>

icon、display-name和description元素的用法和上一節(jié)介紹的用法相同。init-param元素與context-param 元素具有相同的元素描述符。filter-name元素用來(lái)定義過(guò)濾器的名稱，該名稱在整個(gè)應(yīng)用中都必須是惟一的。filter-class元素指定過(guò)濾 器類的完全限定的名稱。

下面是一個(gè)使用filter元素的部署描述符的例子：

7. filter-mapping元素
filter-mapping元素用來(lái)聲明Web應(yīng)用中的過(guò)濾器映射。過(guò)濾器可被映射到一個(gè)servlet或一個(gè)URL模式。將過(guò)濾器映射到一個(gè) servlet中會(huì)造成過(guò)濾器作用于servlet上。將過(guò)濾器映射到一個(gè)URL模式中則可以將過(guò)濾器應(yīng)用于任何資源，只要該資源的URL與URL模式匹 配。過(guò)濾是按照部署描述符的filter-mapping元素出現(xiàn)的順序執(zhí)行的。

<!ELEMENT filter-mapping (filter-name, (url-pattern | servlet-name))>
<!ELEMENT filter-name (#PCDATA)>
<!ELEMENT url-pattern (#PCDATA)>
<!ELEMENT servlet-name (#PCDATA)>

filter-name值必須對(duì)應(yīng)filter元素中聲明的其中一個(gè)過(guò)濾器名稱。下面是一個(gè)含有filter-mapping元素的部署描述符：

<filter-mapping>
<filter-name>Encryption Filter</filter-name>
<servlet-name>EncryptionFilteredServlet</servlet-name>
</filter-mapping>
</web-app>

8. listener元素
listener元素用來(lái)注冊(cè)一個(gè)監(jiān)聽(tīng)器類，可以在Web應(yīng)用中包含該類。使用listener元素，可以收到事件什么時(shí)候發(fā)生以及用什么作為響應(yīng)的通知。

<!ELEMENT listener (listener-class)>
<!ELEMENT listener-class (#PCDATA)>

下面是一個(gè)含有l(wèi)istener元素的有效部署描述符：

9. servlet元素
servlet元素用來(lái)聲明一個(gè)servlet。

<!ELEMENT servlet (icon?, servlet-name, display-name?, description?,
(servlet-class|jsp-file), init-param*, load-on-startup?, run-as?,
security-role-ref*)>
<!ELEMENT servlet-name (#PCDATA)>
<!ELEMENT servlet-class (#PCDATA)>
<!ELEMENT jsp-file (#PCDATA)>
<!ELEMENT init-param (param-name, param-value, description?)>
<!ELEMENT load-on-startup (#PCDATA)>
<!ELEMENT run-as (description?, role-name)>
<!ELEMENT role-name (#PCDATA)>

icon、display-name和description元素的用法和上一節(jié)介紹的用法相同。init-param元素與context-param元素具有相同的元素描述符。可以使用init-param子元素將初始化參數(shù)名和參數(shù)值傳遞給servlet。

(1) servlet-name、servlet-class和jsp-file元素

servlet元素必須含有servlet-name元素和servlet-class元素，或者servlet-name元素和jsp-file元素。描述如下：
● servlet-name元素用來(lái)定義servlet的名稱，該名稱在整個(gè)應(yīng)用中必須是惟一的。
● servlet-class元素用來(lái)指定servlet的完全限定的名稱。
● jsp-file元素用來(lái)指定應(yīng)用中JSP文件的完整路徑。這個(gè)完整路徑必須由a/開(kāi)始。

(2) load-on-startup元素

當(dāng)啟動(dòng)Web容器時(shí)，用load-on-startup元素自動(dòng)將servlet加入內(nèi)存。加載servlet就意味著實(shí)例化這個(gè)servlet，并調(diào)用 它的init方法?？梢允褂眠@個(gè)元素來(lái)避免第一個(gè)servlet請(qǐng)求的響應(yīng)因?yàn)閟ervlet載入內(nèi)存所導(dǎo)致的任何延遲。如果load-on- startup元素存在，而且也指定了jsp-file元素，則JSP文件會(huì)被重新編譯成servlet，同時(shí)產(chǎn)生的servlet也被載入內(nèi)存。
load-on-startup元素的內(nèi)容可以為空，或者是一個(gè)整數(shù)。這個(gè)值表示由Web容器載入內(nèi)存的順序。舉個(gè)例子，如果有兩個(gè)servlet元素都 含有l(wèi)oad-on-startup子元素，則load-on-startup子元素值較小的servlet將先被加載。如果load-on- startup子元素值為空或負(fù)值，則由Web容器決定什么時(shí)候加載servlet。如果兩個(gè)servlet的load-on-startup子元素值相 同，則由Web容器決定先加載哪一個(gè)servlet。

(3) run-as元素

如果定義了run-as元素，它會(huì)重寫(xiě)用于調(diào)用Web應(yīng)用中servlet所設(shè)定的Enterprise JavaBean(EJB)的安全身份。Role-name是為當(dāng)前Web應(yīng)用定義的一個(gè)安全角色的名稱。

(4) security-role-ref元素

security-role-ref元素定義一個(gè)映射，該映射在servlet中用isUserInRole (String name)調(diào)用的角色名與為Web應(yīng)用定義的安全角色名之間進(jìn)行。security-role-ref元素的描述如下：
<!ELEMENT security-role-ref (description?, role-name, role-link)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT role-name (#PCDATA)>
<!ELEMENT role-link (#PCDATA)>

role-link元素用來(lái)將安全角色引用鏈接到已定義的安全角色。role-link元素必須含有已經(jīng)在security-role元素中定義的一個(gè)安全角色的名稱。

(5) Faces Servlet的servlet元素

在 JSF應(yīng)用中，需要為Faces Servlet定義一個(gè)servlet元素，如下所示：

<!-- Faces Servlet -->
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup> 1 </load-on-startup>
</servlet>

<!-- Faces Servlet Mapping -->
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>

</web-app>

10. seervlet-mapping 元素
seervlet-mapping 元素將URL模式映射到某個(gè)servlet。

<!ELEMENT servlet-mapping (servlet-name, url-pattern)>
<!ELEMENT servlet-name (#PCDATA)>
<!ELEMENT url-pattern (#PCDATA)>

在前面的“servlet元素”一節(jié)中已經(jīng)介紹了使用servlet-mapping元素的例子。

11. session-config元素
session-config元素為Web應(yīng)用中的javax.servlet.http.HttpSession對(duì)象定義參數(shù)。

<!ELEMENT session-config (session-timeout?)>
<!ELEMENT session-timeout (#PCDATA)>

session-timeout元素用來(lái)指定默認(rèn)的會(huì)話超時(shí)時(shí)間間隔，以分鐘為單位。該元素值必須為整數(shù)。如果session-timeout元素的值為零或負(fù)數(shù)，則表示會(huì)話將永遠(yuǎn)不會(huì)超時(shí)。

下面是一個(gè)部署描述符，在用戶最近訪問(wèn)HttpSession對(duì)象30分鐘后，HttpSession對(duì)象默認(rèn)為無(wú)效：

12. mime-mapping元素
mime-mapping元素將mime類型映射到擴(kuò)展名。

<!ELEMENT mime-mapping (extension, mime-type)>
<!ELEMENT extension (#PCDATA)>
<!ELEMENT mime-type (#PCDATA)>

extension元素用來(lái)描述擴(kuò)展名。mime-type元素則為MIME類型。

舉個(gè)例子，下面的部署描述符將擴(kuò)展名txt映射為text/plain：

13. welcome-file-list元素
當(dāng)用戶在瀏覽器中輸入的URL不包含某個(gè)servlet名或JSP頁(yè)面時(shí)，welcome-file-list元素可指定顯示的默認(rèn)文件。

<!ELEMENT welcome-file-list (welcome-file+)>
<!ELEMENT welcome-file (#PCDATA)>

如果用戶鍵入的URL不包含servlet名稱、JSP頁(yè)面或其他資源，則不會(huì)在應(yīng)用目錄中找到main.html文件，這時(shí)就會(huì)顯示jsp目錄下的welcome.jsp文件。

14. error-page元素
error-page元素用于將一段錯(cuò)誤代碼或一個(gè)異常類型映射到Web應(yīng)用中的資源路徑，從而在產(chǎn)生特殊的HTTP錯(cuò)誤或指定的Java異常時(shí)，將顯示相關(guān)的資源。

<!ELEMENT error-page ((error-code | exception-type), location)>
<!ELEMENT error-code (#PCDATA)>
<!ELEMENT exception-type (#PCDATA)>
<!ELEMENT location (#PCDATA)>

error-code元素包含HTTP錯(cuò)誤代碼。exception-type是Java異常類型的完全限定的名稱。location元素是Web應(yīng)用中的資源相對(duì)于應(yīng)用目錄的路徑。location的值必須從a/開(kāi)始。

舉個(gè)例子，每次產(chǎn)生HTTP 404錯(cuò)誤代碼時(shí)，下面的部署描述符可使Web容器顯示error404.html頁(yè)面：

15. taglib元素
taglib元素描述JSP定制標(biāo)記庫(kù)。

<!ELEMENT taglib (taglib-uri, taglib-location)>
<!ELEMENT taglib-uri (#PCDATA)>
<!ELEMENT taglib-location (#PCDATA)>

taglib-uri元素是用于Web應(yīng)用中的標(biāo)記庫(kù)的URI。taglib-uri元素的值與WEB-INF目錄相對(duì)應(yīng)。
taglib-location元素包含一個(gè)位置，其中可以找到標(biāo)記庫(kù)的標(biāo)記庫(kù)描述符(TLD)文件。

16. resource-env-ref元素
可以使用resource-env-ref元素來(lái)指定對(duì)管理對(duì)象的servlet引用的聲明，該對(duì)象與servlet環(huán)境中的資源相關(guān)聯(lián)。

<!ELEMENT resource-env-ref (description?, resource-env-ref-name,
resource-env-ref-type)>
<!ELEMENT resource-env-ref-name (#PCDATA)>
<!ELEMENT resource-env-ref-type (#PCDATA)>

resource-env-ref-name元素是資源環(huán)境引用的名稱，其值為servlet代碼中使用的環(huán)境的入口名稱。該名稱是一個(gè)與java:comp/env相對(duì)應(yīng)的Java命名和目錄接口(JNDI)名稱，該名稱在整個(gè)Web應(yīng)用中必須是惟一的。

17. resource-ref元素
resource-ref元素用于指定對(duì)外部資源的servlet引用的聲明。

<!ELEMENT resource-ref (description?, res-ref-name,
res-type, res-auth, res-sharing-scope?)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT res-ref-name (#PCDATA)>
<!ELEMENT res-type (#PCDATA)>
<!ELEMENT res-auth (#PCDATA)>
<!ELEMENT res-sharing-scope (#PCDATA)>

resource-ref子元素的描述如下：
● res-ref-name是資源工廠引用名的名稱。該名稱是一個(gè)與java:comp/env上下文相對(duì)應(yīng)的JNDI名稱，并且在整個(gè)Web應(yīng)用中必須是惟一的。
● res-auth表明：servlet代碼通過(guò)編程注冊(cè)到資源管理器，或者是容器將代表servlet注冊(cè)到資源管理器。該元素的值必須為Application或Container。
● res-sharing-scope表明：是否可以共享通過(guò)給定資源管理器連接工廠引用獲得的連接。該元素的值必須為Shareable(默認(rèn)值)或Unshareable。

18. security-constraint元素
部署描述符中的security-constraint元素允許不通過(guò)編程就可以限制對(duì)某個(gè)資源的訪問(wèn)。

<!ELEMENT security-constraint (display-name?,
web-resource-collection+,
auth-constraint?, user-data-constraint?)>
<!ELEMENT display-name (#PCDATA)>
<!ELEMENT web-resource-collection (web-resource-name, description?,
url-pattern*, http-method*)>
<!ELEMENT auth-constraint (description?, role-name*)>
<!ELEMENT user-data-constraint (description?, transport-guarantee)>

(1) web-resource-collection元素

web-resource-collection元素標(biāo)識(shí)需要限制訪問(wèn)的資源子集。在web-resource-collection元素中，可以定義URL模式和HTTP方法。如果不存在HTTP方法，就將安全約束應(yīng)用于所有的方法。

<!ELEMENT web-resource-collection (web-resource-name, description?,
url-pattern*, http-method*)>
<!ELEMENT web-resource-name (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT url-pattern (#PCDATA)>
<!ELEMENT http-method (#PCDATA)>

web-resource-name是與受保護(hù)資源相關(guān)聯(lián)的名稱。http-method元素可被賦予一個(gè)HTTP方法，比如GET和POST。

(2) auth-constraint元素

auth-constraint元素用于指定可以訪問(wèn)該資源集合的用戶角色。如果沒(méi)有指定auth-constraint元素，就將安全約束應(yīng)用于所有角色。

<!ELEMENT auth-constraint (description?, role-name*)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT role-name (#PCDATA)>

role-name元素包含安全角色的名稱。

(3) user-data-constraint元素

user-data-constraint元素用來(lái)顯示怎樣保護(hù)在客戶端和Web容器之間傳遞的數(shù)據(jù)。

<!ELEMENT user-data-constraint (description?, transport-guarantee)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT transport-guarantee (#PCDATA)>

transport-guarantee元素必須具有如下的某個(gè)值：
● NONE，這意味著應(yīng)用不需要傳輸保證。
● INTEGRAL，意味著服務(wù)器和客戶端之間的數(shù)據(jù)必須以某種方式發(fā)送，而且在傳送中不能改變。
● CONFIDENTIAL，這意味著傳輸?shù)臄?shù)據(jù)必須是加密的數(shù)據(jù)。

在大多數(shù)情況下，安全套接字層(SSL)用于INTEGRAL或CONFIDENTIAL。

19. login-config元素
login-config元素用來(lái)指定所使用的驗(yàn)證方法、領(lǐng)域名和表單驗(yàn)證機(jī)制所需的特性。

<!ELEMENT login-config (auth-method?, realm-name?,
form-login-config?)>
<!ELEMENT auth-method (#PCDATA)>
<!ELEMENT realm-name (#PCDATA)>
<!ELEMENT form-login-config (form-login-page, form-error-page)>

login-config子元素的描述如下：
● auth-method指定驗(yàn)證方法。它的值為下面的一個(gè)：BASIC、DIGEST、FORM或 CLIENT-CERT
● realm-name指定HTTP Basic驗(yàn)證中使用的領(lǐng)域名。
● form-login-config指定基于表單的登錄中應(yīng)該使用的登錄頁(yè)面和出錯(cuò)頁(yè)面。如果沒(méi)有使用基于表單的驗(yàn)證，則忽略這些元素。這個(gè)元素的定義如下，其中form-login-page用于指定顯示登錄頁(yè)面的資源路徑， form-error-page則用于指定用戶登錄失敗時(shí)顯示出錯(cuò)頁(yè)面的資源路徑。這兩個(gè)頁(yè)面路徑都必須以a/開(kāi)始，并與應(yīng)用目錄相對(duì)應(yīng)。
<!ELEMENT form-login-config (form-login-page, form-error-page)>
<!ELEMENT form-login-page (#PCDATA)>
<!ELEMENT form-error-page (#PCDATA)>

20. security-role元素
security-role元素指定用于安全約束中的安全角色的聲明。

<!ELEMENT security-role (description?, role-name)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT role-name (#PCDATA)>

21. env-entry元素
env-entry元素用于指定應(yīng)用環(huán)境入口。

<!ELEMENT env-entry (description?, env-entry-name, env-entry-value?,
env-entry-type)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT env-entry-name (#PCDATA)>
<!ELEMENT env-entry-value (#PCDATA)>
<!ELEMENT env-entry-type (#PCDATA)>

env-entry-name元素包含Web應(yīng)用環(huán)境入口的名稱。該名稱是一個(gè)與java:comp/env相對(duì)應(yīng)的JNDI名稱，并且在整個(gè)應(yīng)用中必須是惟一的。
env-entry-value元素包含Web應(yīng)用環(huán)境入口的值。該值必須是一個(gè)字符串類型的值，并且對(duì)于指定類型的構(gòu)造函數(shù)是有效的，該函數(shù)獲得一個(gè) String參數(shù)；或者對(duì)于java.lang.Character是有效的，java.lang.Character對(duì)象是一個(gè)字符。
env-entry-type元素包含環(huán)境入口值的完全限定的Java類型，該環(huán)境入口值是Web應(yīng)用代碼所期望的。這個(gè)env-entry-type元素的值必須是如下之一：

java.lang.Boolean
java.lang.Byte
java.lang.Character
java.lang.String
java.lang.Short
java.lang.Integer
java.lang.Long
java.lang.Float
java.lang.Double

22. ejb-ref元素
ejb-ref元素用于指定EJB的home接口的引用。

<!ELEMENT ejb-ref (description?, ejb-ref-name, ejb-ref-type, home,
remote, ejb-link?)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT ejb-ref-name (#PCDATA)>
<!ELEMENT ejb-ref-type (#PCDATA)>
<!ELEMENT home (#PCDATA)>
<!ELEMENT remote (#PCDATA)>
<!ELEMENT ejb-link (#PCDATA)>

ejb-ref-name包含EJB引用的名稱。EJB引用是servlet環(huán)境中的一個(gè)入口，它與java:comp/env相對(duì)應(yīng)。這個(gè)名稱在Web應(yīng)用中必須是惟一的。為求一致性，推薦您的ejb-ref-name元素名稱以ejb/開(kāi)始。
ejb-ref-name元素包含引用的EJB的期望類型。這個(gè)值必須是Entity或Session。
home元素包含EJB的home接口的完全限定的名稱。remote元素包含EJB的remote接口的完全限定的名稱。
ejb-ref或ejb-local-ref元素中用到的ejb-link元素可指定EJB 引用被鏈接到另一個(gè)EJB。Ejb-link元素的值必須是同一個(gè)J2EE應(yīng)用單元中某個(gè)EJB的ejb-name。Ejb-link元素中的名稱可以由指定ejb-jar的路徑名組成，該ejb-jar包含引用的EJB。目標(biāo)bean的名稱添加在后面，用字符a# 與路徑名分隔。路徑名與包含引用EJB的Web應(yīng)用的WAR相對(duì)應(yīng)。這就允許我們惟一標(biāo)識(shí)具有相同ejb-name的多個(gè)企業(yè)bean。

23. ejb-local-ref元素
ejb-local-ref元素用于聲明對(duì)EJB的本地home的引用。

<!ELEMENT ejb-local-ref (description?, ejb-ref-name, ejb-ref-type,
local-home, local, ejb-link?)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT ejb-ref-name (#PCDATA)>
<!ELEMENT ejb-ref-type (#PCDATA)>
<!ELEMENT local-home (#PCDATA)>
<!ELEMENT local (#PCDATA)>
<!ELEMENT ejb-link (#PCDATA)>

local元素包含EJB本地接口的完全限定的名稱。Local-home元素包含EJB本地home接口的完全限定的名稱。