部署描述符

部署描述符是JavaEE程序常见的一部分，但是之前都没有较为全面的学习过，这里就较为全面的记录一下部署描述符中的元素。部署一个Servlet 3 或以上应用程序是一件轻而易举的事。通过Servlet注解，对于不太复杂的应用程序，甚至可以部署没有描述符的Servlet/JSP应用程序。但是需要更加精细配置或是我们不能修改框架源码的情况，仍然需要部署描述符。首先，部署描述符必须命名为web.xml并位于WEB-INF目录下。Java类编译后class文件和配置文件都会放置在WEB-INF/classes目录下，而Java类库都放在WEB-INF/lib目录下，所有的应用程序资源打包成war为后缀的jar文件，这个war中包含WEB-INF(web.xml,  classes，lib)，页面资源。

在存在如下场景，部署描述符不能少：

• 需要传递全局初始化参数给ServletContext
• 有多个过滤器，并要设置调用顺序
• 需要修改会话超时设置
• 需要限制资源的访问，并配置用户身份验证方式

先来看看web.xml的头部声明：

<?xml version="1.0" encoding="UTF-8"?>
<web-app 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://java.sun.com/xml/ns/javaee" 
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_1.xsd" version="3.1">
    [metadata-complete="true|false"]
     ...
</web-app>

xsi:schemaLocation 属性指定了元素文档的位置，以便可以进行验证。version属性指定了Servlet规范的版本。

可选的metadata-complete属性指定部署描述符是否是完整的，若值为True，则Servlet/JSP容器将忽略Servlet注解。若值为False或不存在该值，则容器必须检查类文件的Servlet注解

web-app元素是文档的根元素，并且可以包含的如下子元素：

• Servlet声明和映射
• ServletContext的初始化参数
• 会话配置
• 监听器类
• 过滤器声明和映射
• MIME类型映射
• 欢迎页面列表
• 错误页面
• JSP特定的设置
• JNDI设置

核心元素

在web-app的子元素可以以任何顺序出现。但某些元素，如session-config，jsp-config和login-config只能出现一次，而另一些元素，如Servlet,filter,welcome-file-list可以出现多次

context-param

context-param元素作为全局初始化参数配置，可以传值给ServletContext。这些值可以被任何Servlet/JSP页面读取。context-param元素由名称/值构成，并可以通过调用ServletContext的getInitParameter方法来读取。可以定义多个context-param元素，每个参数名在本应用中必须唯一。ServletContext.getInitParameterNames()方法会返回所有的参数名称。

每一个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>
      <param-name>port</param-name>
      <param-value>8080</param-value>
      <description>The port number userd</description>
    </context-param>

distributable

若定义了distributable元素，则表明应用程序已部署到分布式的Servlet/JSP容器。distributable元素属性为空：

<distributable/>

error-page

error-page元素包含一个HTTP错误代码与资源路径或Java异常类型与资源路径之间的映射关系。error-page元素定义容器在特定的HTTP错误或异常时应返回的资源路径。

error-page元素由以下成分构成：

• error-code，指定一个HTTP错误代码
• exception-type，指定Java的异常类型(全路径名称)
• location，指定要被显示的资源位置。该元素必须以“/”开始

<error-page>
 <error-code>404</error-code>
 <location>/error.html</location>
</error-page>
<error-page>
  <exception-type>javax.servlet.ServletException</exception-type>
  <location>/exception.html</location>
</error-page>

当出现HTTP404时，会显示位于应用程序目录下的error.html页面。发生ServletException会显示exception.html页面。

filter

filter指定一个Servlet的过滤器。该元素至少包括一个filter-name元素和一个filter-class元素。此外，它还可以包含以下元素：icon，display-name，discription，init-param以及async-supported。

filter-name元素定义了过滤器的名称。过滤器名称必须全局唯一。filter-class元素指定过滤器类的全路径名称。可由init-param元素来配置过滤器的初始化参数（类似于<context-param>），一个过滤器可以配置多个init-param。

<filter>
    <filter-name>UpperCaseFilter</filter-name>
    <filter-class>cn.lynu.filter.UpperCaseFilter</filter-class>
</filter>
<filter>
    <filter-name>IamgeFilter</filter-name>
    <filter-class>cn.lynu.filter.ImageFilter</filter-class>
    <init-param>
          <param-name>frequency</param-name>
          <param-value>2018</param-value>
    </init-param>      
    <init-param>
          <param-name>resolution</param-name>
          <param-value>1024</param-value>
    </init-param>    
</filter>

filter-mapping

过滤器映射元素时指定过滤器要被映射到的一个或多个资源。过滤器可以被映射到Servlet或者URL模式。过滤器映射元素中包含一个filter-name元素和一个url-pattern元素或者servlet-name元素。filter-name元素的值必须与filter元素声明的某一个过滤器名称相匹配。

<filter>
     <filter-name>LoggingFilter</filter-name>
     <filter-class>cn.lynu.filter.LoggingFilter</filter-class>
</filter>
<filter>
    <filter-name>SecondFilter</filter-name>
    <filter-class>cn.lynu.filter.SecondFilter</filter-class>
</filter>
<filter-mapping>
      <filter-name>LoggingFilter</filter-name>
      <servlet-name>FirstServlet</servlet-name>
</filter-mapping>
<filter-mapping>
      <filter-name>SecondFilter</filter-name>
      <servlet-name>/*</servlet-name>
</filter-mapping>

第一个过滤器分别用于映射到一个Servlet上，第二个filter用于过滤所有请求

listener

listener元素用于注册一个监听器。其子元素listener-class包含监听器类的全路径名

<listener>
        <listener-class>cn.lynu.listener.AppListener</filter-class>
</listener>

Servlet

Servlet元素当然是用于配置Servlet，包括如下子元素：

• 一个可选的icon元素
• 一个可选的description元素
• 可选的display-name元素
• 一个servlet-name元素
• 一个servlet-class元素或一个jsp-file元素
• 零个或更多的init-param元素
• 一个可选的load-on-startup元素
• 可选的run-as元素
• 可选的enabled元素
• 可选的async-supported元素
• 可选的multipart-config元素
• 零个或多个security-role-ref元素

一个Servlet元素至少必须包含一个servlet-name元素和一个servlet-class元素。或者一个servlet-name元素和一个jsp-file元素

servlet-name元素定义的Servlet名称在应用程序中必须是唯一的

servlet-class元素指定的类名为全路径名

jsp-file元素指定JSP页面的路径，该路径时应用程序的相对路径，必须以“/”开始

init-param的子元素可以用来传递一个初始化参数给Servlet。init-param结构同context-param

可以使用load-on-startup元素在当Servlet/JSP容器启动的时候自动加载Servlet。加载一个Servlet是指实例化Servlet和调用它的init方法。默认情况下，在第一次访问Servlet的时候才开始加载。load-on-startup可以指定一个整数值来指定加载顺序。多个Servlet都包含一个load-on-startup元素，则数值小的优先加载。如果两个Servlet具有相同的load-on-startup，则加载的顺序不能确定。

run-as用于覆盖调用EJB的安全标识。角色名是当前Web应用程序定义的安全角色之一

enabled元素也是一个可选的元素。它的值可以是True或False。设置子元素为False，则可以禁用这个Servlet

Servlet-mapping

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

    <servlet>
        <servlet-name>springDispatcherServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <!--使用默认配置  -->
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>springDispatcherServlet</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

locale-encoding-mapping-list和locale-encoding-mapping

locale-encoding-mapping-list元素包含一个或多个locale-encoding-mapping元素。每个locale-encoding-mapping定义了locale以及编码的映射，分别用locale以及encoding元素定义。locale元素的值必须在ISO639中定义的与语言编码，如zh。或者采用“语言编码_国家编码”格式，如zh_CN。其中，国家编码的值必须在ISO3166中定义。

<locale-encoding-mapping-list>
    <locale-encoding-mapping>
         <locale>zh_CN</locale>
         <encoding>UTF-8</encoding>
    </locale-encoding-mapping>
</locale-encoding-mapping-list>

login-config

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认证方式的登录页面和失败页面。如果没有采用FORM认证方式，则该元素被忽略。

form-login-config元素包括form-login-page和form-error-page两个子元素。form-login-page配置了显示登录页面的资源路径，路径为应用程序的相对路径，其必须以“/”开始。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-mapping元素用来把一个MIME类型映射到一个扩展名。该元素由一个extension元素和一个mime-type元素组成

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

session-config

session-config元素定义了javax.servlet.http.HttpSession实例的参数。此元素可以包括一个或多个以下内容：session-timeout，cookie-config或tracking-mode。

• session-timeout元素指定会话超时间隔（分钟），session默认是30分钟过时。该值必须为整数，如果该值为零或负数，这会话将永不超时
• cookie-config元素定义了会话创建的cookie配置
• tracking-mode元素定义了跟踪会话模式。其有效值是COOKIE，URL或SSL

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

welcome-file-list

welcome-file-list元素指定当前用户在浏览器中输入URL没有指定页面时，显示的默认的Servlet名或JSP页面或静态页面。welcome-file-list元素包含与一个或多个welcome-file元素。welcome-file元素包含默认的文件名，如果在第一个welcome-file元素知道那个的文件没有找到，则Web容器将尝试显示第二个，直到最后一个。

  <welcome-file-list>
    <welcome-file>login.jsp</welcome-file>
    <welcome-file>login.html</welcome-file>
  </welcome-file-list>

我们也可以将一个Servlet作为欢迎页

 <welcome-file-list>
    <welcome-file>login.jsp</welcome-file>
    <welcome-file>servlet/welcome</welcome-file>
  </welcome-file-list>

jsp-property-group

jsp-property-group中的元素可为一组JSP文件配置属性，使用这个元素可以做到一下几点：

• 指示是否忽略EL
• 指示是否忽视Java脚本
• 指明页面的编码方式

jsp-property-group可以有如下子元素：

• 一个或多个url-pattern元素
• 一个可选的el-ignored元素
• 一个可选的page-encoding元素
• 一个可选的scripting-invalid元素

url-pattern元素用来指定应用相对属性配置的URL模式

el-ignored元素值为true或false.true表示在匹配的JSP页面中忽略使用EL，该值默认是False

page-encoding元素指定JSP页面的编码方式，和页面的pageEncoding的有效值是一样的。如果page-encoding元素与匹配的JSP中的pageEncoding属性值不同时，则会产生一个转换时错误

scripting-invalid元素值为True或False。True值是指URl模式的JSP页面不再支持<% Java 脚本%>语法，默认值是False.

所有的JSP页面不执行EL表达式：

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

所有的JSP页面不支持<% scripting%>语法：

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