本章為部署描述符中Web容器支持詳細描述Java Servlet 規(guī)范3.0版本要求。部署描述符在應(yīng)用開發(fā)者，應(yīng)用組裝者和部署者之前傳達一個Web應(yīng)用的元素和配置信息。
對Java Servlet2.4及以上版本，部署描述符按照XML模式文檔的方式被定義。
為了向后兼容使用2.2版本API的應(yīng)用的應(yīng)用，Web容器也需要支持2.2版本的部署描述符。為了向后兼容使用2.3版本API的應(yīng)用的應(yīng)用，Web容器也需要支持2.3版本的部署描述符。2.2版本，2.3版本。
一、部署描述符元素
下列配置和部署信息的類型被要求在Web應(yīng)用部署描述符中對所有servlet容器都被支持：
- ServletContext初始化參數(shù)
- Session配置
- Servlet聲明
- Servlet映射
- 應(yīng)用生命周期監(jiān)聽類
- Filter定義和Filter映射
- MIME類型映射
- 歡迎文件列表
- 錯誤頁面
- Locale和編碼映射
- 安全配置，包括登錄配置，安全限制，安全角色，安全角色引用和運行方式
二、處理部署描述符的規(guī)則
本節(jié)列出了一些通用規(guī)則，Web容器和開發(fā)者必須注意一個Web應(yīng)用的部署描述符的處理。
- Web容器必須為部署描述符的文本節(jié)點的元素內(nèi)容移除所有前導(dǎo)和后綴空格，在XML1.0中這被定義為"S(white space)"。
- 部署描述符必須對模式有效。操作Web應(yīng)用的Web容器和工具有很多選擇來檢查一個WAR的有效性。這包括檢查部署描述符文檔的有效性。
此外，推薦操作Web應(yīng)用的Web容器和工具提供一層語義檢查。在非一致性的Web應(yīng)用case中，工具和容器應(yīng)該通知開發(fā)者描述性的錯誤信息。高端應(yīng)用服務(wù)器提供商被鼓勵以工具和容器分離的方式提供這種有效性檢查。 - 在本規(guī)范中，web-app下的子元素可以按任意順序聲明。由于XML模式的限制，元素distributable，session-config，welcome-file-list，jsp-config，login-config和locale-encoding-mapping-list從可選改變到0或者更多。當部署描述符包含多余一個session-config，jsp-config和login-config時，容器必須通知開發(fā)者一個描述性錯誤信息。當有多個出現(xiàn)時，容器必須合并welcome-file-list和locale-encoding-mapping-list中的項目。distributale的多次出現(xiàn)必須像distributable單次出現(xiàn)一樣對待。
- 在部署描述符中指定的URI路徑被認為是URL編碼格式。當URL包含CR(#xD)或者LF(#xA)時，容器必須通知開發(fā)者一個描述性錯誤信息。容器必須保留URL中所有其它包含空格的字符。
- 容器必須嘗試規(guī)范部署描述符中的路徑。比如，/a/../b格式的路徑必須被解析為/b。對以'../'開頭的路徑的路徑開始或者解析在部署描述符中不是有效路徑。
- 指向一個相對WAR根路徑的資源，或者一個映射相對于WAR根路徑的路徑的URI路徑，除非特殊說明，都應(yīng)該以前導(dǎo)'/'開頭。
- 值是枚舉類型元素，值對大小寫敏感。
三、部署描述符
本規(guī)范的部署描述符地址。
四、部署描述符圖
本節(jié)說明部署描述中的元素。屬性并沒有展示在這個圖中。
- web-app 元素
web-app元素對一個Web應(yīng)用而言，是部署描述符根。元素包含下列元素。這個元素有一個必須的元素version來指定部署描述符遵守哪個版本的規(guī)范。這個元素下的所有子元素能夠以任意順序出現(xiàn)。
圖4-1 web-app 元素結(jié)構(gòu)
web-app元素結(jié)構(gòu) - description元素
description元素用來提供對父級元素的一個文本描述。這個元素不僅出現(xiàn)在web-app元素中，也會出現(xiàn)在其它多個元素中。它有個可選的屬性xml:lang來表明在描述中使用哪種語言。屬性的默認值是English("en")。 - display-name元素
display-name包含一個簡寫名字，它用來被工具展示。這個顯示名字不必唯一。這個元素有一個可選的屬性xml:lang來指明語言。 - icon元素
icon元素包含小圖和大圖元素，它們用來為代表GUI工具中父級元素的小的和大的GIF或者JPEG圖標指明文件名。 - distributable元素
distributable元素表明Web應(yīng)用適當?shù)鼐幋a來被部署到一個分布式servlet容器中。 - context-param元素
context-param包含一個Web應(yīng)用的servlet上下文初始化參數(shù)的聲明。 - filter元素
filter在Web應(yīng)用中聲明了一個filter。在filter-mapping元素中使用filter-name值引用，filter被映射到一個servlet或者一個URL模式上。Filters能夠在運行時通過FilterConfig接口訪問部署描述符中聲明的初始化參數(shù)。filter-name元素的元素內(nèi)容一定不能為空。filter-class是filter的完整類名。init-param元素包含name-value對來作為filter的初始化參數(shù)。可選的async-supported元素表明filter支持異步請求處理。
圖4-2 filter元素結(jié)構(gòu)
filter元素結(jié)構(gòu) - filter-mapping元素
filter-mapping被容器用來決定哪些filters以什么順序應(yīng)用在一個請求上。filter-name的值必須要是在部署描述符中聲明的filter。匹配請求能夠用url-pattern或者servlet-name指明。
圖4-3 filter-mapping元素結(jié)構(gòu)
filter-mapping元素結(jié)構(gòu) - listener元素
listener元素為一個應(yīng)用listener bean表明部署properties。子元素listener-class聲明：應(yīng)用中的一個class必須被注冊為一個Web應(yīng)用listener bean。值是listener類的全路徑名。
圖4-4 listener 元素結(jié)構(gòu)
listener 元素結(jié)構(gòu) - servlet元素
servlet被用來聲明一個servlet。它包含了一個servlet的聲明數(shù)據(jù)。jsp-file元素包含了一個Web應(yīng)用中以一個'/'開頭的JSP文件的完整路徑。如果一個jsp-file被指明，并且load-on-startup元素出現(xiàn)，那么JSP被重新編譯和加載。servlet-name元素包含了servlet的規(guī)范名字。每個servlet名字在web應(yīng)用中是唯一的。servlet-name的元素內(nèi)容一定不能為空。servlet-class包含servlet的完整類名。run-as元素指明了被用來指定一個組件的身份。它包含可選的description，以及被role-name指明的一個安全角色的名字。元素load-on-startup表明這個servlet應(yīng)該在web應(yīng)用啟動的時候被加載（實例化并且調(diào)用init()方法）。這個元素的元素內(nèi)容必須是一個整數(shù)，用以表明servlet應(yīng)該被加載的順序。如果這個值為負整數(shù)，或者這個元素沒有出現(xiàn)，容器會在它想加載時候去加載這個servlet。如果這個值是正數(shù)或者0，容器必須在應(yīng)用部署的時候加載和初始化這個servlet。容器必須保證數(shù)字小的servlet在數(shù)字大的servlet之前被加載。容器可以對有相同load-on-startup值的servlet選擇servlet的加載順序。security-role-ref元素在組件里或者在一個部署組件代碼中聲明了安全角色引用。它由可選的description，在代碼（role-name）中使用的安全角色名字以及一個對安全角色（role-link）的可選鏈接組成。如果安全角色沒有被指明，部署者必須選擇一份合適的安全角色。可選的async-supported元素表明servlet能夠支持異步請求處理。如果一個servlet支持文件上傳功能和mime-multipart請求的處理，對同樣的配置能夠在部署描述符中通過multipart-config元素被提供。multipart-config元素能夠被使用來指明文件被存儲的位置，文件被上傳的最大大小，最大請求大小以及文件被寫到磁盤的大小閾值。
圖4-5 servlet元素結(jié)構(gòu)
servlet元素結(jié)構(gòu) - servlet-mapping元素
servlet-mapping在一個servlet和一個URL模式之間定義了一個映射。
圖4-6 servlet-mapping元素結(jié)構(gòu)
servlet-mapping元素結(jié)構(gòu) - session-config元素
session-config為Web應(yīng)用定義了會話參數(shù)。子元素session-timeout為所有在Web應(yīng)用中被創(chuàng)建的會話定義了默認會話超時區(qū)間。具體的超時必須通過一個完整的分鐘數(shù)來表達。如果超時是0或者更少，容器確保會話的默認行為永不超時。如果這個元素沒有被指定，容器必須設(shè)置它的默認超時周期。
圖4-7 session-config元素結(jié)構(gòu)
session-config元素結(jié)構(gòu) - mime-映射元素
mime-mapping定義了一個擴展和一個mime類型之間的映射。extension元素包含了一個描述一個擴展的字符串，比如'txt'。
圖4-8 mime-mapping元素結(jié)構(gòu)
mime-mapping元素結(jié)構(gòu) - welcome-file-list元素
welcome-file-list包含一個歡迎文件的有序列表。子元素welcome-file包含一個文件名來用作一個默認歡迎文件，比如index.html。
圖4-9 welcome-file-list元素結(jié)構(gòu)
welcome-file-list元素結(jié)構(gòu) - error-page元素
error-page包含一個錯誤碼或者一個異常類型到一個web應(yīng)用中資源路徑的映射。子元素exception-type包含一個Java異常類型的完整類名。子元素location包含了web應(yīng)用中相對于web應(yīng)用根路徑的資源位置。位置的值必須有一個前導(dǎo)'/'。
圖4-10 error-page元素結(jié)構(gòu)
error-page元素結(jié)構(gòu) - jsp-config元素
jsp-config被用來在web應(yīng)用中為JSP文件提供全局配置信息。它有兩個子元素，taglib和jsp-property-group。taglib元素能夠被用來提供一個tag庫上的信息，它被web應(yīng)用中的JSP頁面使用。
圖4-11 jsp-config 元素結(jié)構(gòu)
jsp-config 元素結(jié)構(gòu) - security-constraint元素
security-constraint被用來關(guān)聯(lián)有一個或者多個web資源集合的安全約束。子元素web-resource-collection指明了資源和web應(yīng)用中應(yīng)用于那些資源上的HTTP方法的一個子集，一個安全約束會應(yīng)用在這個web應(yīng)用上。auth-constraint表明一個應(yīng)該被允許訪問這個資源集合的用戶角色。這里使用的role-name必須對應(yīng)security-role元素的role-name或者是特別保留的角色名字''。如果''和角色名字同時出現(xiàn)，容器把這個解析為所有所有角色。如果沒有角色被指定，沒有用戶被允許訪問Web應(yīng)用中被security-constraint描述的部分。當決定訪問時，容器匹配角色名字對大小寫敏感。user-data-constraint表明數(shù)據(jù)怎樣在客戶端之前交流，并且容器應(yīng)該通過子元素transport-guarantee來被保護。transport-guarantee的合法值是NONE，INTEGRAL或者CONFIDENTIAL。
圖4-12 security-constraint 元素結(jié)構(gòu)
security-constraint 元素結(jié)構(gòu) - login-config元素
login-config被用來配置應(yīng)該被使用的認證方法，應(yīng)該被使用的realm名字以及被表單登錄機制所需的屬性。子元素auth-method為web應(yīng)用配置認證機制。元素內(nèi)容必須是BASIC，DIGEST，F(xiàn)ORM，CLIENT或者一個具體提供商認證規(guī)范。realm-name指明了realm名字，它被用來為認證規(guī)范選擇web應(yīng)用。form-login-config指明了應(yīng)該在表單提交中被使用的登錄和錯誤頁面。如果基于表單登錄沒有被使用，這些元素將會被忽略。
圖4-13 login-config元素結(jié)構(gòu)
login-config元素結(jié)構(gòu) - security-role元素
security-role定義了一個安全角色。子元素role-name定義了安全角色的名字。這個名字必須為NMTOKEN遵循字典規(guī)則。
圖4-14 security-role元素結(jié)構(gòu)
security-role元素結(jié)構(gòu) - env-entry元素
env-entry聲明了一個應(yīng)用的環(huán)境入口。子元素env-entry-name包含一個部署組件環(huán)境入口的名字。這個名字是相對于java:comp/env上下文的JNDI名字。名字在部署描述符中必須唯一。env-entry-type包含環(huán)境入口值的完整Java類型，應(yīng)用代碼需要這個環(huán)境變量的入口值。子元素env-entry-value定義了一個部署逐漸環(huán)境入口的值。這個值必須是一個字符串，這個字符串對指定類型的構(gòu)造函數(shù)有效，這個構(gòu)造函數(shù)需要一個字符串作為參數(shù)，或者一個java.lang.Character類型的單個字符。可選的injection-target元素被用來把命名的資源注入定義到域或者JavaBean properties中。一個injection-target指定了一個類和一個資源被注入進來來的類的名字。injection-target-class為被注入類指定了完整的類路徑名。injection-target-name在具體類里制定了類名。第一個被找到的目標作為JavaBean property名字。如果沒有沒找到，找到的目標走位一個域名。具體的資源將會在類初始化期間通過調(diào)用set方法或者把值設(shè)置到名字域里來被注入到目標里。如果一個injection-target為環(huán)境入口被指明，env-entry-type可以被忽略或者必須匹配注入對象的類型。如果沒有指定injection-target，那么env-entry-type是必須要的。
圖4-15 env-entry 元素結(jié)構(gòu)
env-entry元素結(jié)構(gòu) - ejb-ref元素
ejb-ref聲明了指向企業(yè)bean的home的引用。ejb-ref-name指明了在引用企業(yè)bean的部署組件的代碼中被使用的名字。ejb-ref-type是被引用企業(yè)bean的期望類型，是Entity或者Session。home定義被引用企業(yè)bean的home接口的完整名字。remote定義了被引用bean的remote接口的完整名字。ejb-link指明了鏈接到一個企業(yè)bean的EJB引用。除了這些元素，injection-target元素能夠被用來定義被命名企業(yè)bean注入到一個組件域或者property中。
圖4-16 ejb-ref元素結(jié)構(gòu)
ejb-ref元素結(jié)構(gòu) - ejb-local-ref元素
ejb-local-ref聲明了指向企業(yè)bean的本地home的引用。local-home定義了企業(yè)bean的本地home接口的完整名字。local定義了企業(yè)bean的本地引用的完整名字。
圖4-17 ejb-local-ref元素結(jié)構(gòu)
ejb-local-ref元素 - service-ref元素
service-ref聲明了指向一個Web服務(wù)的引用。service-ref-name聲明了邏輯名字，模塊中的組件使用這個名字來查找Web服務(wù)。推薦所有服務(wù)應(yīng)用名字都以/service/開頭。service-interface定義了客戶端依賴的JAX-WS服務(wù)接口完整類名。大多數(shù)場景中，值將會是javax.xml.rpc.Service。一個JAX-WS生成的服務(wù)接口類也會被指定。wsdl-file元素包含一個WSDL文件的URI位置。這個位置相對于模塊的根。jaxrpc-mapping-file包含一個文件的名字，這個文件描述了應(yīng)用使用的Java接口和wsdl-file中的WSDL描述之間的JAX-WS映射。文件名字在一個模塊文件中是一個相對路徑。service-qname元素聲明了正在被引用的具體WSDL服務(wù)元素。如果沒有聲明wsdl-file，它將不會被指定。port-component-ref元素聲明了一個容器上的客戶端依賴來把Service Endpoint Interface解析到一個WSDL端口。給Service Endpoint Interface關(guān)聯(lián)一個特殊端口是可選的。這僅在一個Service.getPort(Class)調(diào)用時被容器使用。handler元素為一個端口組件聲明了一個處理器。處理器可以使用HandlerInfo接口來訪問init-name name-value對。如果port-name沒有被指定，處理器被認為與所有服務(wù)的端口關(guān)聯(lián)。可以參考JSR-109獲得詳細信息。
圖4-18 service-ref元素結(jié)構(gòu)
service-ref元素結(jié)構(gòu) - resource-ref 元素
resource-ref包含一個部署組件引用一個外部資源的聲明。res-ref-name指明了一個資源管理連接工廠引用的名字。名字是相對于java:comp/env上下文的JNDI名字。名字在部署文件中必須唯一。res-type元素指明了數(shù)據(jù)源的類型。類型是完整的Java語言類或者被數(shù)據(jù)源實現(xiàn)的接口。res-auth指明了部署組件代碼是否編程式地登記到資源管理，或者容器是否根據(jù)部署組件登記到資源管理。對于后面一種情況，容器使用部署者提供的信息。res-sharing-scope指明了通過特定資源管理連接工廠引用獲取的連接是否能被共享。如果被指定，值必須是Shareable或者Unshareable。可選的injection-target元素被用來把命名的資源注入到fields或者Javabeans properties中。
圖4-19 resource-ref元素結(jié)構(gòu)
resource-ref元素結(jié)構(gòu) - resource-env-ref元素
resource-env-ref包含了部署組件的引用，它指向部署組件環(huán)境中與一個資源關(guān)聯(lián)的被管理的對象。resource-env-ref-name指明了資源環(huán)境引用的名字。值是在部署組件中代碼中被使用的環(huán)境入口名字和一個相對java:comp/env上下文的JNDI名字，并且在部署組件中必須唯一。resource-env-ref-type指明了資源環(huán)境引用的類型。它是一個Java語言類或者接口的完整名字。可選的injection-target元素被用來定義把命名資源注入到fields或者JavaBeans properties中。resource-env-ref-type必須被提供，除非一個注入目標被指明。如果否被指明，類型必須兼容注入目標的類型。
圖4-20 resource-env-ref元素結(jié)構(gòu)
resource-env-ref元素結(jié)構(gòu) - message-destination-ref元素
message-destination-ref包含了一個部署組件引用的聲明，它指向一個與部署組件環(huán)境中與一個資源關(guān)聯(lián)的消息目標。message-destination-ref-name元素指明了一個消息目的地引用的名字。它的值是在部署組件代碼中被使用的環(huán)境入口名字。名字是一個相對java:comp/env上下文的JNDI名字，并且在一個企業(yè)beans的ejb-jar或者其它的部署文件中必須唯一。message-destination-type指明了目的地的類型。類型通過將會被實現(xiàn)的Java接口指定。message-destination-usage指明了通過引用表明的消息目的地的使用。值表明了消息是否會從消息目的地被消費，是否會為目的地生產(chǎn)消息，或者兩者皆是。組裝者利用這些信息把一個目的地的生產(chǎn)者與它的消費者關(guān)聯(lián)起來。message-destination-link鏈接了一個消息目的地引用或者消息啟動bean到一個消息目的地。組裝者設(shè)置這個值來反應(yīng)應(yīng)用中生產(chǎn)者和消費者之間的信息流。值必須是相同部署文件或者相同Java EE應(yīng)用單元其它部署文件中一個消息目的地的message-destination-name。值可以由一個路徑名字組成，這個名字指明了一個部署文件，它包含了被引用消息目的地，目的地在路徑名中通過“#”追加或者分隔。路徑名相對于部署文件，它包含引用消息目的地的部署組件。這允許有相同名字的多個消息目的地被確定唯一身份。可選的injection-target元素被用來定義命名資源到fields或者JavaBeans properties的注入。message-destination-type必須被指明，除非一個注入目標被指明，這種情形下目標的類型會被使用。如果都被指定，類型必須與注入目標類型兼容。
例子：
<message-destination-ref>
<message-destination-ref-name>
jms/StockQueue
</message-destination-ref-name>
<message-destination-type>
javax.jms.Queue
</message-destination-type>
<message-destination-usage>
Consumes
</message-destination-usage>
<message-destination-link>
CorporateStocks
</message-destination-link>
</message-destination-ref>
圖4-21 message-destination-ref元素結(jié)構(gòu)
message-destination-ref元素結(jié)構(gòu) - message-destination元素
message-destination指明了一個消息目的地。這個元素描述的邏輯目的地被部署者映射到一個物理目的地。message-destination-name元素為一個消息目的地指明了一個名字。在部署文件中，這個名字在消息目的地名字間必須唯一。
例子：
<message-destination>
<message-destination-name>
CorporateStocks
</message-destination-name>
</message-destination>
圖4-22 message-destination元素結(jié)構(gòu)
message-destination元素結(jié)構(gòu) - locale-encoding-mapping-list元素
locale-encoding-mapping-list包含locale和encoding之間的映射，它通過子元素locale-encoding指定。
例子：
<locale-encoding-mapping-list>
<locale-encoding-mapping>
<locale>ja</locale>
<encoding>Shift_JIS</encoding>
</locale-encoding-mapping>
</locale-encoding-mapping-list>
圖4-23 locale-encoding-mapping-list元素結(jié)構(gòu)
locale-encoding-mapping-list元素結(jié)構(gòu)
五、例子
下列例子說明了在部署描述符規(guī)范中列出的定義的使用。
圖5-1 基本部署描述符例子
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd” version=”2.5”>
<display-name>A Simple Application</display-name>
<context-param>
<param-name>Webmaster</param-name>
<param-value>webmaster@mycorp.com</param-value>
</context-param>
<servlet>
<servlet-name>catalog</servlet-name>
<servlet-class>com.mycorp.CatalogServlet</servlet-class>
<init-param>
<param-name>catalog</param-name>
<param-value>Spring</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>catalog</servlet-name>
<url-pattern>/catalog/*</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>30</session-timeout>
</session-config>
<mime-mapping>
<extension>pdf</extension>
<mime-type>application/pdf</mime-type>
</mime-mapping>
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
</welcome-file-list>
<error-page>
<error-code>404</error-code>
<location>/404.html</location>
</error-page>
</web-app>-
安全的例子
例5-2 使用安全的部署描述符
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd” version=”2.5”>
<display-name>A Secure Application</display-name>
<servlet>
<servlet-name>catalog</servlet-name>
<servlet-class>com.mycorp.CatalogServlet</servlet-class>
<init-param>
<param-name>catalog</param-name>
<param-value>Spring</param-value>
</init-param>
<security-role-ref>
<role-name>MGR</role-name>
<role-link>manager</role-link>
</security-role-ref>
</servlet><security-role> <role-name>manager</role-name> </security-role> <servlet-mapping> <servlet-name>catalog</servlet-name> <url-pattern>/catalog/*</url-pattern> </servlet-mapping> <security-constraint> <web-resource-collection> <web-resource-name>SalesInfo </web-resource-name> <url-pattern>/salesinfo/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL </transport-guarantee> </user-data-constraint> </security-constraint> </web-app>
翻譯自 Java Servlet Specification
Version 3.0 Rev a
Author:Rajiv Mordani
Date: December 2010
