15.1、部署描述符概述

web-app元素为根元素，并且可以利用子元素来指定以下内容

1、servlet声明

2、servlet映射

3、ServletContext初始参数

4、会话配置

5、监听器类

6、过滤器定义和映射

7、MIME类型映射

8、welcome文件列表

9、错误页面

10、JSP相关的特定设置

11、JNDI设置

15.1.1、核心元素

context-param

context-param元素用于为ServletContext赋值。它可以通过在ServletContext中调用getInitParameter方法获取到。只要其参数名称在整个应用程序中是唯一的，则可以有多个context-param元素。ServletContext.getInitParameterNames()将返回所有的ServletContext参数名称。

context-param元素中必须包含一个param-name元素和一个param-value元素。param-name元素中包含参数名称，param-value元素中则包含参数值。description元素是可选的，它也可以用来描述参数。

<context-param>
		<param-name>location</param-name>
		<param-value>localhost</param-value>
	</context-param>
	<context-param>
		<description>The port number used</description>
		<param-name>port</param-name>
		<param-value>8080</param-value>
	</context-param>

distributable

distributable元素用来表明这个应用程序应该部署到一个分布式的Servlet/JSP容器中，distributable元素必须为空。例如，下面就是一个distributable元素

<distributable/>

error-page元素中包含了一个HTTP错误码与一个资源路径之间的映射，或者是一种java异常类型与一个资源路径之间的映射。error-page元素命令容器，在发生HTTP错误事件，或者抛出指定的异常时，应该返回指定的资源。

该元素中必须包含以下子元素：

1、error-code，指定一个HTTP错误码。

2、exception-type，指定要不活的java异常类型的全类名

3、location，指定要在错误事件或者异常中显示的资源的位置，location元素必须以/开头。

下面就是一个error-page元素的例子：

<error-page>
		<error-code>404</error-code>
		<location>/error.html</location>
	</error-page>

filter

该元素用来指定一种Servlet过滤器，它至少包含一个filter-name元素和一个filter-class元素。另外，它还可以可选的包含以下元素：icon、display-name、description、init-param和async-supported。

filter-name元素定义过滤器的名称。过滤器的名称在整个应用程序中必须是唯一的。filter-class元素指定过滤器类的全类名，init-param元素用来指定过滤器的初始参数，其元素描述与<context-param>的相同。filter元素中可以有多个init-param元素。

下面是两个filter元素，其名称分别为UpperCaseFilter和ImageFilter。

<filter>
		<filter-name>UpperCaseFilter</filter-name>
		<filter-class>com.example.UpperCaseFilter</filter-class>
	</filter>
	<filter>
		<filter-name>ImageFilter</filter-name>
		<filter-class>com.example.ImageFilter</filter-class>
		<init-param>
			<param-name>frequency</param-name>
			<param-value>1909</param-value>
		</init-param>
		<init-param>
			<param-name>resolution</param-name>
			<param-value>1024</param-value>
		</init-param>
	</filter>

filter-mapping元素定义过滤器要应用到的一个或多个资源。过滤器也可以应用于Servlet或者URL模式，将过滤器映射到Servlet，将致使过滤器的作用于Servlet。将过滤器映射到URL模式，则将使过滤器作用于所有其URL与URL模式匹配的任意资源。它们的过滤顺序与filter-mapping元素在部署描述符中出现的顺序一致。

filter-mapping元素中包含了一个filter-name元素和一个url-pattern元素，或者servlet-name元素。

filter-name值必须与利用filter元素声明的某一个过滤器的名称相匹配。

下面是两个filter元素和两个filter-mapping元素：

<filter>
		<filter-name>Logging Filter</filter-name>
		<filter-class>com.example.LoggingFilter</filter-class>
	</filter>
	<filter>
		<filter-name>Security Filter</filter-name>
		<filter-class>com.example.SecurityFilter</filter-class>
	</filter>
	<filter-mapping>
		<filter-name>Logging Filter</filter-name>
		<servlet-name>FirstServlet</servlet-name>
	</filter-mapping>
	<filter-mapping>
		<filter-name>Security Filter</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>

listener元素用来注册一个监听器，它包含一个listener-class元素，用于定义监听器类的全类名，例如：

<listener>
		<listener-class>com.example.AppListener</listener-class>
	</listener>

locale-encoding-mapping-list元素中包含一个或多个locale-encoding-mapping元素。locale-encoding-mapping元素将一个语言环境的名称映射成一个编码，并且包含一个locale元素和一个encoding元素。<locale>的值必须是ISO 639中定义的某一个language-code，例如en，或者是一个language-code_country-code，例如en_US。如果使用的是language-code_country-code，那么country-code部分必须为ISO 3166中定义的某一个国家代码。

例如，下面的locale-encoding-mapping-list中包含了一个locale-encoding-mapping元素，它将japanese（日文）映射成Shift_JIS编码。

<locale-encoding-mapping-list>
		<locale-encoding-mapping>
			<locale>ja</locale>
			<encoding>Shift_JIS</encoding>
		</locale-encoding-mapping>
	</locale-encoding-mapping-list>

login-config元素指定用来验证用户的验证方法，如果采用基于表单的验证，那么则还可以定义表单登录机制所需的realm名称和属性。login-config元素中有一个可选的auth-method元素，一个可选的realm-name元素，和一个可选的form-login-config元素。

auth-method元素指定访问验证方法，它的值可能为：BASIC、DIGEST、FORM或者CLIENT-CERT。

realm-name元素指定要在Basic访问验证和Digest访问验证中使用的realm名称。

form-login-config元素指定在基于表单的验证中要用到的登录页面和错误页面。如果没有使用基于表单的验证，则可以忽略这些元素。

form-login-config元素中有一个form-login-page元素和一个form-error-page元素，form-login-page元素指定显示Login页面的资源路径。这个路径必须以“/”开头，并且是相对与应用程序目录的。

form-error-page元素用于指定在登录失败时显示错误页面的资源路径。这个路径必须以/开头，并且是相对于应用程序的目录的。

举个例子：

<login-config>
		<auth-method>DIGEST</auth-method>
		<realm-name>Members Only</realm-name>
	</login-config>

<login-config>
		<auth-method>FORM</auth-method>
		<form-login-config>
			<form-login-page>/loginForm.jsp</form-login-page>
			<form-error-page>/errorPage.jsp</form-error-page>
		</form-login-config>
	</login-config>

mime-mapping元素是将一个MIME类型映射成一个扩展，它包含一个extension元素和一个mime-type元素。extension元素描述扩展，mime-type元素指定MIME类型。例如，下面就是一个mime-mapping元素的例子：

<mime-mapping>
		<extension>txt</extension>
		<mime-type>text/plain</mime-type>
	</mime-mapping>

security-constraint元素可以通过声明的方式来限制对某个资源集合的访问。

security-constraint元素中包含一个可选的display-name元素，一个或多个web-resource-collection元素，一个可选的auth-constraint元素，以及一个可选的user-data-constraint元素。

web-resource-collection元素定义需要限制访问的资源集合。在这里，可以定义一个或者多个URL模式，以及一个或者多个需要受到限制的HTTP方法。如果没有指定HTTP方法，那么这个安全约束将应用于所有的HTTP方法。

auth-constraint元素定义可以访问该资源集合的用户角色。如果没有设置auth-constraint元素，那么该安全约束将应用于所有角色。

user-data-constraint元素用来指明在客户与Servlet/JSP容器之间的传输的数据应该如何进行保护。

web-resource-collection元素中包含一个web-resource-name元素，一个可选的description元素，有零个或者多个url-pattern元素，以及有零个或者多个http-method元素。

web-resource-name元素中包含了一个与被保护资源相关的名称

http-method元素中可以设置一个HTTP方法，如GET、POST或者TRACE。

auth-constraint元素中包含一个可选的description元素，有零个或者多个role-name元素。role-name元素中包含某个安全角色的名称。

user-data-constraint元素中包含一个可选的description元素和一个transport-guarantee元素。transport-guarantee元素必须具有以下其中一个值：NONE、INTEGRAL或者CONFIDENTIAL。NONE表示该应用程序不需要传输保证。INTEGRAL表示服务器与客户端之间的数据应该以一种在传输过程中无法更改的方式进行发送。CONFIDENTIAL表示所传输的数据必须进行加密。在大多数情况下，SSL是用于INTEGRAL或者CONFIDENTIAL的。

以下是一个范例：

<security-constraint>
		<web-resource-collection>
			<web-resource-name>Members Only</web-resource-name>
			<url-pattern>/members/*</url-pattern>
		</web-resource-collection>
		<auth-constraint>
			<role-name>payingMember</role-name>
		</auth-constraint>
	</security-constraint>
	<login-config>
		<auth-method>Digest</auth-method>
		<realm-name>Digest Access Authentication</realm-name>
	</login-config>

security-role元素用来指定安全约束中所有的安全角色声明。这个元素有一个可选的description元素和一个role-name元素。下面是一个security-role元素的示例。

<security-role>
		<role-name>payingMember</role-name>
	</security-role>

servlet元素用来声明一个Servlet，它可以包含以下元素：

1、一个可选的icon元素

2、一个可选的description元素

3、一个可选的display-name元素

4、一个servlet-name元素

5、一个servlet-class元素，或者一个jsp-file元素

6、有零个或者多个init-param元素

7、一个可选的load-on-startup元素

8、一个可选的run-as元素

9、一个可选的enabled元素

10、一个可选的async-supported元素

11、一个可选的multipart-config元素

12、有零个或者多个security-role-ref元素

将安全角色引用PM映射到名为payingMember的安全角色，其语法如下：

<security-role-ref>
			<role-name>PM</role-name>
			<role-link>payingMember</role-link>
		</security-role-ref>

下面是个servlet元素的例子：

<servlet>
		<servlet-name>UploadServlet</servlet-name>
		<servlet-class>com.brainysoftware.UploadServlet</servlet-class>
		<load-on-startup>10</load-on-startup>
	</servlet>
	<servlet>
		<servlet-name>SecureServlet</servlet-name>
		<servlet-class>com.brainysoftware.SecureServlet</servlet-class>
		<load-on-startup>20</load-on-startup>
	</servlet>

servlet-mapping元素将一个Servlet映射到一个URL模式。servlet-mapping元素必须有一个servlet-name元素和一个url-pattern元素。

下面的servlet-mapping元素将一个Servlet映射到URL模式/first。

<servlet>
		<servlet-name>FirstServlet</servlet-name>
		<servlet-class>com.brainysoftware.FirstServlet</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>FirstServlet</servlet-name>
		<url-pattern>/first</url-pattern>
	</servlet-mapping>

session-config元素为javax.servlet.http.HttpSession实例定义参数，这个元素可以包含一个或者多个以下元素：session-timeout、cookie-config或tracking-mode。

session-timeout元素定义默认回话超时的时间间隔，其单位为分钟。这个值必须为整数值。如果session-timeout元素的值为0，或者为负数，那么这个回话将永远不会超时。

cookie-config元素定义会话的配置，用来追踪这个Servlet/JSP应用程序创建的cookie。

tracking-mode元素为该WEB应用程序创建的会话定义追踪模式，其有效值为COOKIE、URL或者SSL。

下面的session-config元素将使当前应用程序中的HttpSession对象在12分钟没有活动之后失效。

<session-config>
		<session-timeout>12</session-timeout>
	</session-config>

welcome-file-list元素定义了当用户在浏览器中输入的URL不包含Servlet名称或JSP页面或静态资源时，要显示的文件或者Servlet

welcome-file-list元素中包含一个或者多个welcome-file元素。welcome-file元素中包含默认的文件名称。如果找不到第一个welcome-file元素中指定的文件，Web容器将尝试进行显示第二个，以此类推。

下面列举一个welcome-file-list元素：

<welcome-file-list>
	<welcome-file>index.htm</welcome-file>
	<welcome-file>index.html</welcome-file>
	<welcome-file>index.jsp</welcome-file>
</welcome-file-list>

<welcome-file-list>
	<welcome-file>index.html</welcome-file>
	<welcome-file>servlet/welcome</welcome-file>
</welcome-file-list>

15.1.2、特定于JSP的元素

<web-app>下的jsp-config元素中包含了特定于JSP的元素。它可以有零个或者多个taglib元素，以及有零个或者多个jsp-property-group元素。taglib元素和jsp-property-group元素将在下面讨论。

taglib

taglib元素描述了一个JSP定制标签库。taglib元素中包含了一个taglib-uri元素和一个taglib-location元素。

taglib元素定义了Servlet/JSP应用程序中所用的标签类库URI。<taglib-uri>的值是相对于部署描述符的位置。

taglib-location元素为标签类库定义了TLD文件的位置。

下面是个taglib的例子

<jsp-config>
	<taglib>
		<taglib-uri>http://brainysoftware.com/taglib/complex</taglib-uri>
		<taglib-location>/WEB-INF/jsp/complex.tld</taglib-location>
	</taglib>
</jsp-config>

jsp-property-group元素中集合了许多jsp文件，以便可以为她们提供通用的属性信息，利用<jsp-property-group>下的子元素可以完成下列任务：

1、是否忽略EL

2、是否允许有脚本元素

3、页面编码信息

4、某个资源是一个JSP文档（用XML编写）

5、前言及代码自动生成的内容

jsp-property-group元素具有以下子元素：

1、一个可选的description元素

2、一个可选的display-name元素

3、一个可选的icon元素

4、一个或多个url-pattern元素

5、一个可选的el-ignored元素

6、一个可选的page-encoding元素

7、一个可选的scripting-invalid元素

8、一个可选的is-xml元素

9、零个或者多个include-prelude元素

10、零个或者多个include-code元素

下面就是一个使所有jsp页面中的EL运算都会被忽略的jsp-property-group元素

<jsp-config>
	<jsp-property-group>
		<url-pattern>*.jsp</url-pattern>
		<el-ignored>true</el-ignored>
	</jsp-property-group>
</jsp-config>

<jsp-config>
	<jsp-property-group>
		<url-pattern>*.jsp</url-pattern>
		<scripting-invalid>true</scripting-invalid>
	</jsp-property-group>
</jsp-config>

15.2、部署

自从有了Servlet开始，部署Servlet/JSP应用程序一直都是一间很容易的事情。它只需要将原始目录结构下的所有应用程序资源压缩成一个war文件即可。你也可以使用JDk中的jar工具，或者像WinZip这样的流行工具。总之，你只需要确保压缩好的文件扩展名为war即可。如果使用的是WinZip，压缩好了之后重命名即可。

我们必须将所有的类库和类文件以及HTML文件、JSp页面、图片、版权信息等，全部放在war文件中。但是不要包含java源文件。需要用到该程序的任何人只需要复制一份war文件，并将它部署到一个Servlet/JSP容器中即可。

15.3、Web Fragment

Servlet3中新增了web fragment，这是在现成Web应用程序中部署插件或者框架的一项新特性。web fragment只在对部署描述符进行补充，无须编辑web.xml文件。web fragment基本上就是一个jar包文件，其中包含了常用的Web对象，如Servlet、过滤器、监听器，以及其他资源，如JSP页面和静态图片。web fragment也可以带有描述符，这是一个与部署描述符类似的XML文档。web fragment描述符必须命名为web-fragment.xml，并且必须放在压缩包的META-INF目录下。web fragment描述符中可以包含部署描述中web-app元素下的所有元素，以及一些特定于web fragment的元素。一个应用程序中可以有多个web fragment。

下面展示了web fragment描述符的大体框架，web-fragment元素中甚至可以带有metadata-complete属性。如果这个属性值为true，那么web fragment中包含的类中的注解将会全部被忽略。

<?xml version="1.0" encoding="utf-8"?>
<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
	http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
	version="3.0"
	[metadata-cmplete="true|false"]
>

</web-fragment>

下面是个例子：

FragmentServlet.java

package fragment.servlet;

import java.io.IOException;
import java.io.PrintWriter;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class FragmentServlet extends HttpServlet {

	private static final long serialVersionUID = 1L;
	
	@Override
	public void doGet(HttpServletRequest request, HttpServletResponse response)
			throws ServletException, IOException {
		response.setContentType("text/html");
		PrintWriter out = response.getWriter() ;
		out.println("A plug-in") ;
	}

}

<?xml version="1.0" encoding="utf-8"?>
<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
	http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
	version="3.0"
>
	<servlet>
		<servlet-name>FragmentServlet</servlet-name>
		<servlet-class>fragment.servlet.FragmentServlet</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>FragmentServlet</servlet-name>
		<url-pattern>/fragment</url-pattern>
	</servlet-mapping>
</web-fragment>

在cmd里执行下图的命令，把文件打成jar包

把生成的jar包拷贝到项目中，在浏览器输入http://localhost:8080/filedowmload/fragment查看结果

第十五章_部署