Servlet 3.0 新特

《Servlet3.1规范》
Servlet 3.0 新特性详解

异步处理的支持

详见SpringMVC-异步请求

注解支持

Servlet 3.0 的部署描述文件 web.xml 的顶层标签 <web-app> 有一个 metadata-complete 属性，该属性指定当前的部署描述文件是否是完全的(默认为false)。如果设置为 true，则容器在部署时将只依赖部署描述文件，忽略所有的注解（同时也会跳过 web-fragment.xml 的扫描，亦即禁用可插性支持，具体请看后文关于 可插性支持的讲解）；如果不配置该属性，或者将其设置为 false，则表示启用注解支持（和可插性支持）。
web.xml 头文件

<?xml version="1.0" encoding="UTF-8"?>
<web-app 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-app_3_0.xsd" 
         version="3.0"
        metadata-complete="false">
</web-app>

@WebInitParam

该注解通常不单独使用，而是配合 @WebServlet 或者 @WebFilter使用。它的作用是为 Servlet 或者过滤器指定初始化参数，这等价于 web.xml 中
<servlet>和 <filter>的 <init-param> 子标签。

//javax.servlet.annotation.WebInitParam 
public @interface WebInitParam {
   //指定参数的名字，等价于 <param-name>。
    String name();
    //指定参数的值，等价于 <param-value>。
    String value();
    //关于参数的描述，等价于 <description>。
    String description() default "";
}

@WebServlet

@WebServlet 用于将一个类声明为 Servlet(该类需继承HttpServlet)，该注解将会在部署时被容器处理，容器将根据具体的属性配置将相应的类部署为 Servlet。大部分属性可以通过属性名称可以理解，只针对少部分进行说明：

//javax.servlet.annotation.WebServlet 
public @interface WebServlet {
    String name() default "";
 
  //等同于urlPatterns， 二者不能同时使用。如果同时指定，通常是忽略 value 的取值
    String[] value() default {};
    String[] urlPatterns() default {};
    
  /**
   * 表示servlet加载的优先级。
   * 若为正数，表示启动时加载，且越小优先级越高
   * 若为负数，则表示在该servlet处理请求时，才加载。
   * /
    int loadOnStartup() default -1;
    
  //初始化参数,结合@WebInitParam使用
    WebInitParam [] initParams() default {};
    
  //是否支持异步
    boolean asyncSupported() default false;
    
    String description() default "";
    String displayName() default "";
}

@WebServlet Demo

@WebServlet(name = "webServlet",urlPatterns = {"/web"},loadOnStartup = 1,
		initParams = {@WebInitParam(name = "username",value = "trump"),@WebInitParam(name = "age",value = "73")})
public class MyWebServlet extends HttpServlet {

	@Override
	public void init(ServletConfig config) throws ServletException {
		String username = config.getInitParameter("username");
		String age = config.getInitParameter("age");
		System.out.println("============="+ LocalDateTime.now()+" "+this.getClass().getName()+"初始化,{age:"+age+",username:"+username+"}");
	}

	@Override
	protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
		this.doPost(req, resp);
	}

	@Override
	protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
		System.out.println("============="+ LocalDateTime.now()+" "+this.getClass().getName()+"被调用");
	}
}

@WebFilter

@WebFilter 用于将一个类(需实现Filter接口)声明为过滤器,同上， 只针对部分属性进行说明：

//javax.servlet.annotation.WebFilter 
public @interface WebFilter {
    String description() default "";
    String displayName() default "";
    WebInitParam[] initParams() default {};
    String filterName() default "";
   //指定过滤器将应用于哪些 Servlet。
    String[] servletNames() default {};
    
   // value 和 urlPatterns 不能共存，如果同时指定，通常忽略 value 的取值
    String[] value() default {};
    String[] urlPatterns() default {};

 //指定过滤器的转发模式。具体取值包括： ASYNC、ERROR、FORWARD、INCLUDE、REQUEST。
    DispatcherType[] dispatcherTypes() default {DispatcherType.REQUEST};
    
    boolean asyncSupported() default false;
}

<dispatcher>有四个值：REQUEST,FORWARD,INCLUDE和ERROR。在一个<filter-mapping>配置任意个<dispatcher>(默认值是REQUEST)，使得filter将会作用不同类型的request请求：

• REQUEST ：直接从客户端过来的request
• FORWARD ：过滤forward请求request
• INCLUDE： 通过include过来的request
• ERROR ：通过<error-page>过来的request

需要注意的是：

1. Value、urlPatterns、servletNames为可选属性，但 三者必需至少包含一个，且 value 和 urlPatterns 不能共存，如果同时指定，通常忽略 value 的取值.
2. 如果拦截的Servlet为异步的，则filter也要开启异步。

@WebFilter Demo

@WebFilter(filterName = "myFilter",urlPatterns = {"/*"},initParams = {@WebInitParam(name = "encoding",value = "utf-8")})
public class MyFilter implements Filter {
	private String encoding ;

	@Override
	public void init(FilterConfig filterConfig) throws ServletException {
		this.encoding = filterConfig.getInitParameter("encoding");
		System.out.println("============="+ LocalDateTime.now()+" "+this.getClass().getName()+"init():{encoding："+encoding+"}");
	}

	@Override
	public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
		System.out.println("============="+ LocalDateTime.now()+" "+this.getClass().getName()+"拦截调用");
		chain.doFilter(request,response);
	}

	@Override
	public void destroy() {
	}
}

@WebListener

该注解用于将类声明为监听器，被 @WebListener 标注的类必须实现以下至少一个接口：

• ServletContextListener
• ServletContextAttributeListener
• ServletRequestListener
• ServletRequestAttributeListener
• HttpSessionListener
• HttpSessionAttributeListener

@WebListener只有一个value属性，用来标明Listener的描述信息。

@WebListener Demo

@WebListener
public class MyServletContextListener implements ServletContextListener {
	@Override
	public void contextInitialized(ServletContextEvent sce) {
		System.out.println(this+"inited.....");
	}	
	
	@Override
	public void contextDestroyed(ServletContextEvent sce) {
	}
}

@MultipartConfig

该注解主要是为了辅助 Servlet 3.0 中 HttpServletRequest 提供的对上传文件的支持。该注解标注在 Servlet 上面，以表示该 Servlet 希望处理的请求的 MIME 类型是 multipart/form-data。

//javax.servlet.annotation.MultipartConfig
public @interface MultipartConfig {
	//存放生成的文件地址。-- 若生成文件的地址是绝对路径，则忽略此属性。
	 String location() default "";
	 
	//允许上传的文件最大值。默认值为 -1，表示没有限制。
	 long maxFileSize() default -1L;
	 
	 //针对该 multipart/form-data 请求的最大数量，默认值为 -1，表示没有限制。
	 long maxRequestSize() default -1L;
	 
	//当数据量大于该值时，内容将被写入文件。
	 int fileSizeThreshold() default 0;
}

@MultipartConfig Demo

@WebServlet(urlPatterns = {"/file"})
@MultipartConfig
public class MyMultiServlet extends HttpServlet {
	@Override
	public void init(ServletConfig config) throws ServletException {
		System.out.println("============="+ LocalDateTime.now()+" "+this.getClass().getName()+"初始化");
	}
	@Override
	protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
		this.doPost(req, resp);
	}

	@Override
	protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
		//servlet3.0 HttpServletRequest增强，新增方法 getParts(),和getPart(String name)
		Collection<Part> parts = req.getParts();
		parts.forEach(part -> {
			System.out.print(part.getName()+"   "+part.getSize());
			String disposition = part.getHeader("content-disposition");
			if(disposition.toLowerCase().contains("filename")){
				Arrays.asList(disposition.split(";")).stream().forEach(desp ->{
					if(desp.toLowerCase().contains("filename")){
						System.out.println(desp);
						return;
					}
				});
			}
		});
	}
}

可插性支持

如果说 3.0 版本新增的注解支持是为了简化 Servlet/ 过滤器 / 监听器的声明，从而使得 web.xml 变为可选配置， 那么新增的可插性 (pluggability) 支持则将 Servlet 配置的灵活性提升到了新的高度。

文件存放路径

web fragment 是 web.xml 的部分或全部，可以在一个类库或框架jar 包 的 META-INF 目 录 指 定 和 包 括 。 在 WEB-INF/lib 目 录 中 的 普 通 的 老 的 jar 文 件 即 使 没 有web-fragment.xml 也可能被认为是一个 fragment。

文件配置

web-fragment.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-fragment 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-fragment_3_0.xsd"
              id="WebAppFragment_ID" version="3.0" metadata-complete ="true">

    <!-- web-fragment 中， 将属性metadata-complete 设置为true,则就只会处理自己JAR文件中的标注信息。-->
    <name>fragment_1</name>

    <servlet>
        <servlet-name>fragmentXmlServletB</servlet-name>
        <servlet-class>cn.jhs.servlet3.fragment.xml.FragmentXmlServletB</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>fragmentXmlServletB</servlet-name>
        <url-pattern>/fragment/b</url-pattern>
    </servlet-mapping>

</web-fragment>

web.xml
web,xml 中， 将属性metadata-complete 设置为true,则就只会处理自己JAR文件中的标注信息和web-fragment.xml中的插件信息。

web.xml 和 web-fragment.xml 顺序

由于规范允许应用配置由多个配置文件组成（web.xml 和 web-fragment.xml）的资源，从应用中多个不同位置发现和加载，顺序问题必须被解决。
web-fragment.xml 可以有且仅有一个顶级<name>元素，可以用作id来标识该fragment.

绝对顺序
在 web.xml 中的<absolute-ordering>元素。在一个 web.xml 中仅能有一个<absolute-ordering>元素。

• a. 在这种情况下，第2种情况(相对排序)处理的顺序配置必须被忽略。
• b. web.xml 和 WEB-INF/classes 必须在列在 absolute-ordering 元素中的所有 web-fragment 之前处理。
• c. <absolute-ordering>的任何直接子<name>元素必须被解释为在这些被指定的 web-fragment 中表示绝对顺序，不管它存不存在，必须被处理。
• d. <absolute-ordering>可以包含零个或一个<others />元素。如果<absolute-ordering>元素没有包含<others/>元素， 没有在<name />明确提到的 web-fragment 必须被忽略。
• e. 重复名字异常：如果，当遍历<absolute-ordering>子元素，遇到多个子元素具有相同<name>元素，只需考虑首次出现的。

相对顺序
在 web-fragment.xml 中的<ordering>元素，一个 web-fragment.xml 只能有一个<ordering>元素。

• a. web-fragment.xml 可以有一个<ordering>元素。如果是这样，该元素必须包含零个或一个<before>元素和零个或一个<after>元素。
• b. web.xml 和 WEB-INF/classes 必须在列在 ordering 元素中的所有 web-fragment 之前处理。
• c.重复命名异常：如果，当遍历 web-fragments，遇到多个成员具有相同<name>元素，应用必须记录包含帮助解决这个问题的提供有用信息的错误消息，且部署必须失败。

---

关于Filter,Listener执行顺序的总结

!!!!(与官方说法有出入，可能是测试用例不足，需再次确认)

Listener
Listener 定义的来源有四个地方：

• web.xml定义
• web-fragment.xml 定义
• @WebListener 注解定义
• ServletContextListener的contextInitialized(ServletContextEvent sce)中addListener

使用同一类型的Listener的执行顺序：

• 在web.xml中定义的执行顺序高于@WebListener,
• web.xml 中按照在xml中定义的顺序执行
• @WebListener 定义的优先级为中,按照类名的顺序排序。
• addListener 添加的优先级最低,按照添加的顺序。

---

Filter
同Listener的执行顺序。唯一的区别是，在addFilter时，可以设置排序的属性isMatchAfter字段：

FilterRegistration.Dynamic filterDynamic3 =servletContext.addFilter("filter3",new BaseFilter("filter3"));
filterDynamic3.addMappingForUrlPatterns(EnumSet.allOf(DispatcherType.class),true,new String[]{"/*"});

//javax.servlet.FilterRegistration.$ Dynamic
public void addMappingForUrlPatterns(EnumSet<DispatcherType> dispatcherTypes, boolean isMatchAfter, String... urlPatterns);

如果isMatchAfter为false,则addFilter的优先级最高;
如果为true,则按照上述Listener执行顺序执行。

---

其他特性

ServletContext 的性能增强

除了以上的新特性之外，ServletContext 对象的功能在新版本中也得到了增强。现在，该对象支持在运行时动态部署 Servlet、Filter、Listener，以及为 Servlet 和过滤器增加 URL 映射等。

//javax.servlet.ServletContext 
public interface ServletContext {
   //多种方式addServlet
    public ServletRegistration.Dynamic addServlet( String servletName, String className);
    public ServletRegistration.Dynamic addServlet( String servletName, Servlet servlet);
      
      //多种方式addFilter
    public FilterRegistration.Dynamic addFilter(String filterName, String className);
    public FilterRegistration.Dynamic addFilter(String filterName, Filter filter);
   public FilterRegistration.Dynamic addFilter(String filterName, Class <? extends Filter> filterClass);   
      
     //多种方式addListener
     public void addListener(String className);
     public <T extends EventListener> void addListener(T t);
}

ServletContext 新增的方法

• 要么是在 ServletContextListener 的 contexInitialized 方法中调用，
• 要么是在 ServletContainerInitializer 的 onStartup() 方法中调用。

Demo

public class MyServletContextListener implements ServletContextListener {
	@Override
	public void contextInitialized(ServletContextEvent sce) {
		System.out.println(this+"inited.....");

		ServletContext servletContext = sce.getServletContext();
		ServletRegistration.Dynamic dynamic = servletContext.addServlet("dynamic", "cn.jhs.servlet.listeners.MyDynamicServlet");
		dynamic.addMapping( new String[] { "/dynamic" });
		dynamic.setInitParameter("gender", "M");
		dynamic.setLoadOnStartup(1);

		FilterRegistration.Dynamic filterDynamic3 =servletContext.addFilter("filter3",new BaseFilter("filter3"));
		//isMatchAfter:
		filterDynamic3.addMappingForUrlPatterns(EnumSet.allOf(DispatcherType.class),false,new String[]{"/*"});

		FilterRegistration.Dynamic filterDynamic4 =servletContext.addFilter("filter4",new BaseFilter("filter4"));
		//isMatchAfter:
		filterDynamic4.addMappingForUrlPatterns(EnumSet.allOf(DispatcherType.class),false,new String[]{"/*"});
	}
}

需要注意的是：此时添加的Listener必须为如下几种的一种或多种：

• javax.servlet.ServletContextAttributeListener
• javax.servlet.ServletRequestListener
• javax.servlet.ServletRequestAttributeListener
• javax.servlet.http.HttpSessionListener
• javax.servlet.http.HttpSessionAttributeListener
• javax.servlet.http.HttpSessionIdListener

HttpServletRequest性能增强

//javax.servlet.http.HttpServletRequest
public interface HttpServletRequest extends ServletRequest {
	//安全相关的增强
	public boolean authenticate(HttpServletResponse response) ;
	public void login(String username, String password) ;
	public void logout() throws ServletException;
	
	//对文件上传的增强
	public Collection<Part> getParts() throws IOException, ServletException;
	public Part getPart(String name) throws IOException, ServletException;
}

web.xml

error-page 元素
error-page 包含一个错误代码或异常类型到 Web 应用程序中资源的路径之间的映射。 servlet3.0以前 error-code(如404,500) 或exception-type(子元素 exception-type 包含了一个 Java 异常类型的完全限定名称。) 元素必填。
servlet3.0以后，可以省略来指定一个默认的错误页面。

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