Servlet 3.1 行为更改

Servlet 3.1 实现包含的行为更改可能导致为 Servlet 3.0 编写的应用程序在您使用 Servlet 3.1 功能部件时以不同方式运行或失败。

对于每个服务器实例,可在 Servlet 3.0 与 Servlet 3.1 功能部件实现之间进行选择并考虑行为更改。如果只有 Servlet 3.1 功能部件包含所需行为,那么必须使用 Servlet 3.1 功能部件。如果 Servlet 3.1 功能部件中的行为更改对现有应用程序产生负面影响,那么使用 Servlet 3.0 功能部件会保留该应用程序的现有行为。不能在同一服务器中同时使用 Servlet 3.0 和 Servlet 3.1 功能部件。同时配置这两个功能部件是错误行为。如果同时配置这两个功能部件,那么不会装入任一 servlet。

引入这些行为更改是基于以下原因:
  • Servlet 3.1 规范中的说明所需的更改。
  • 为使 Servlet 3.1 实现通过 Servlet 3.1 Technology Compatibility Kit (TCK) 而需要的更改。
  • 为改进 servlet 实现而进行的更改。

通过程序添加的 servlet、过滤器和侦听器

Servlet 3.1 规范中的说明现在指示,如果 ServletContextListener 未在 web.xml 文件或 web-fragment.xml 文件中声明或未使用 @WebListener 进行注释,那么 ServletContextListener 通过程序配置 servlet 是非法操作。因此,为执行这类程序配置而对 ServletContext 进行的任何调用会导致 UnsupportedOperationException。

启动异步处理后转发

在 Servlet 3.0 实现中,响应始终在 RequestDispatcher 接口的转发方法返回前关闭。但是,因为 Servlet 3.1 规范中的声明,如果请求置于异步方式,那么 Servlet 3.1 实现不会在 RequestDispatcher 接口的转发方法返回前关闭或清仓响应。此更改可能会影响现有 3.0 应用程序,这些应用程序会在从转发返回时添加响应输出,因为现在会发送这类响应数据,而在 Servlet 3.0 中不会发送这类响应数据。

URL 模式冲突

在 Servlet 3.0 中,即使 URL 模式映射至多个 servlet,应用程序也应成功启动。但是,因为 Servlet 3.1 规范中的说明,应用程序必定启动失败。在 Liberty 概要文件 Servlet 3.1 实现中,消息为输出,应用程序启动失败:
SRVE9016E: 无法针对名为 [{1}] 的 servlet 插入映射 [{0}]。已对名为 [{2}] 的 servlet 定义 URL 模式。

说明:存在应用程序错误。servlet 映射 URL 模式不应映射至多个 servlet。

用户操作:更改 servlet 映射的 URL 模式。

ServletContext.getServerInfo()

在 Servlet 3.0 功能部件实现中,此 API 返回 SMF WebContainer

在 Servlet 3.1 功能部件中,此 API 现在返回 IBM WebSphere Liberty/8.5.5.<x>,其中 <x> 是 WebSphere® Application Server 修订包编号。

ServletResponse.reset()

如果响应未落实,那么您可使用 ServletResponse.reset() 清除所有缓存响应数据、状态码和响应头。如果正在使用 Servlet 3.1 功能部件,那么此方法还会清除先前调用的 ServletResonse.getWriter() 或 ServletResponse.getOutputStream() 的任何记录。

X-Powered-By 头

在 Servlet 3.0 功能部件实现中,X-Powered-By 头设置为 Servlet/3.0。在 Servlet 3.1 功能部件实现中,X-Powered-By 头设置为 Servlet/3.1

资源引用注入目标合并

在 Servlet 3.0 规范中,如果同名 web.xml 资源引用定义没有 <injection-target> 元素,那么 web-fragment.xml 文件中定义的资源引用的 <injection-target> 元素仅添加至父 web.xml 文件。在 Servlet 3.1 规范中,已说明 web-fragment.xml 描述符中的所有<injection-target> 元素将添加至同名资源引用的 <injection-target> 元素的父 web.xml 描述符列表。如果正在使用 Servlet 3.1 功能部件,那么此功能部件可能通过激活先前在 web.xml 文件中排除的注入目标来更改现有应用程序功能。

Web 描述符中对重复元素的容忍度

在 Servlet 3.1 规范中,已说明 web.xml 文件不能包含两个 <absolute-ordering> 元素。部署带有多个 <absolute-ordering> 元素的应用程序将失败。此外,web-fragment.xml 描述符不能包含两个 <ordering> 元素。部署带有多个 <ordering> 元素的应用程序将失败。以前此部署不会失败,但元素的功能可能无法确定。

metadata-complete 用例中的 Web 片段排序更改

如果 web.xml 描述符标记为 metadata-complete=“true",那么 <absolute-ordering> 元素的处理会更改。以前在 metadata-complete="true" 用例中,会使用所有 Web 片段归档。使用 Servlet-3.1 功能部件时,metadata-complete 用例中的 <absolute-ordering> 元素被视为完整。此更改导致处理时排除 <absolute-ordering> 元素中未列示的片段。

AsyncContext.dispatch()

如果正在使用 AsyncContext.dispatch(),例如,不带任何参数,那么请求被分派至原始 URL。如果正在使用 Servlet-3.0 功能部件,那么原始请求未附带查询字符串时,该查询字符串会提供给所分派资源。但是,如果正在使用 Servlet 3.1 功能部件,那么查询字符串提供给分派资源时,该查询字符串会提供给所分派资源。例如:
Request for /FirstResource?param=One
First Resource:
    getParameter("param") returns “One”
           forward request to /SecondResource?param=Two
SecondResource
           getParameter(param) returns “Two”
           ac.start()
           ac.dispacth() dispatches to /FirstResource
First Resource
           Servlet-3.0 feature : getParamter(“param") returns “One”
           Servlet-3.1 feature : getParameter(“param”) returns “Two”

This change was required by the Servlet 3.1 TCK.

SessionCookieConfig.setComment()

根据 Java™ Servlet 3.1 规范,如果在 ServletContext 完成初始化后调用此 API,那么此 API 返回 illegalStateException,并且 Servlet-3.1 功能部件遵循此必需行为。但是,初始化上下文后,Servlet-3.0 功能部件不会阻止使用此 API,因此,依赖于 Servlet-3.0 功能部件行为的应用程序不会与 Servlet-3.1 功能部件配合工作。

sendRedirect(java.lang.String location) API

sendRedirect(java.lang.String location) API 接受相对 URL;但是,servlet 容器必须先将相对 URL 转换为绝对 URL,才能将响应发送至客户机。如果该位置是相对位置且没有前导“/” (folder/default.jsp),那么该容器将其解释为相对于当前请求 URI。如果该位置是相对位置且带有前导“/”,那么容器会将其解释为相对于 servlet 容器根。

例如,如果应用程序提供的重定向位置为 folder/default.jsp 且没有前导“/”,并且入站请求 URL 为 http://host:port/context_root/folderhttp://host:port/context_root/folder/,那么该请求将重定向至 http://host:port/context_root/folder/folder/default.jsp,它相对于当前请求 URI。

com.ibm.ws.webcontainer.redirectwithpathinfo 属性设置为 true 时,会在 Servlet 3.0 功能部件中发现此行为。此属性在 Servlet 3.1 功能部件中被忽略,按描述所言,此行为是缺省行为。

缺省错误页

IBM® 扩展功能允许指定带有 Web 扩展的缺省错误页,例如,ibm-web-ext.xml

作为 Servlet 3.0 及更高版本的功能,缺省错误页是对指定错误页功能的修改。与常规(非缺省)错误页一样,缺省错误页是在 Web 模块描述符 (web.xml) 和 Web 片段描述符 (web-fragment.xml) 中指定的。

常规(非缺省)错误页指定 exception-type 或 error-code。缺省错误页省略 exception-type 和 error-code。如果 servlet 抛出异常或设置错误代码结果,并且没有与异常类型或错误代码相匹配的已配置错误页,那么系统使用缺省错误页。

Servlet 3.0 规范允许定义缺省错误页,Servlet 3.0 模式也支持此功能。根据 Servlet 3.1 规范,缺省错误页不包含 exception-typeerror-code 元素。

错误页和缺省错误页的示例如下所示。

缺省错误页优先顺序规则
确定 web.xmlweb-fragment.xmlibm-web-ext.xml 文件中的缺省错误页的优先顺序时,有三个规则适用。
  • 规则 1:web.xmlweb-fragment.xml 文件。

    如果在 web.xml 文件中指定了缺省错误页,那么该错误页会覆盖(屏蔽)web-fragment.xml 文件中指定的任何缺省错误页。而且,如果除此之外还有多个 web-fragment.xml 文件指定了缺省错误页,也不会发生任何错误。

  • 规则 2:web-fragment.xmlweb-fragment.xml

    如果未在 web.xml 文件中指定缺省错误页,并且两个或更多 web-fragment.xml 文件指定了不同缺省错误页,那么会发生错误。

  • 规则 3:ibm-web-ext.xmlweb.xmlweb-fragment.xml 文件。

    ibm-web-ext.xml 文件与 web.xmlweb-fragment.xml 文件之间的优先顺序规则依赖于 Web 容器功能部件级别。

如果 Web 容器功能部件级别为 3.0,那么 ibm-web-ext.xml 文件定义的缺省错误页优先于 web.xmlweb-fragment.xml 文件中定义的缺省错误页。
注: 如果 Web 容器使用功能部件级别 3.0,那么您不能使用 Servlet 3.1 模式。请参阅有关对 servlet 3.0 模式使用缺省错误页的规则。

如果 Web 容器功能部件级别为 3.1 或更高,那么 web.xmlweb-fragment.xml 文件指定的缺省错误页优先于 ibm-web-ext.xml 文件中指定的缺省错误页。

模式规则

确定缺省错误页是在 web.xml 文件中还是在 web-fragment.xml 文件中处理时,有两个规则适用。这些规则依赖于 Web 容器功能部件版本、所使用的 servlet 模式以及 Java 定制属性的设置。

这些规则的产生原因是 IBM WebSphere Application Server V8.0 完整概要文件不支持在 V8.0 一般可用性发行版中使用缺省错误页。对于 Application Server 完整概要文件,对缺省错误页的支持由 APAR PM94199 通过 service pack 添加。对于 Application Server Liberty 概要文件,对缺省错误页的支持由 APAR PI05845 通过 service pack 添加。因为这些更新是外部可视功能的更改,所以缺省情况下新功能被禁用,必须由 Java 系统属性启用。

  • 规则 1:使用 Servlet 3.0 模式和使用 Web 容器功能部件 V3.0 的缺省错误页。

    如果 Web 容器功能部件版本为 3.0 且在使用 Servlet 3.0 模式的 web.xmlweb-fragment.xml 文件中指定了缺省错误页,那么仅当 com.ibm.ws.webcontainer.allowdefaulterrorpage Java 系统属性设置为 true 时,才会处理这些缺省错误页。如果未设置 Java 系统属性或此属性未设置为 true,那么系统会忽略缺省错误页。将使用通过 ibm-web-ext.xml 文件指定的缺省错误页。

  • 用例 2:使用 Web 容器功能部件 V3.1 的缺省错误页。

    如果 Web 容器功能部件版本为 3.1 或更高,那么始终处理 web.xmlweb-fragment.xml 文件中指定的缺省错误页,无论使用何种版本的 servlet 模式以及不管是否设置 Java 定制属性都是如此。

    如果描述符使用 Servlet 3.1 模式,那么会出现这种情况,因为使用 Servlet 3.1 模式的描述符的处理需要 Web 容器功能部件 V3.1。

注意: 直到 Servlet 3.0 才添加了 Web 片段。web-fragment.xml 文件没有来自 Servlet 2.5 的模式。
错误页和缺省错误页示例
ibm-web-ext.xml 文件中定义的缺省错误页:
<?xml version="1.0" encoding="UTF-8"?>
<web-ext xmlns="http://websphere.ibm.com/xml/ns/javaee"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
    						version="1.0">

	<default-error-page uri="/ExtErrorPage.html"/>
</web-ext>
error-code 错误页元素,它是在 web.xml 文件或 web-fragment.xml 文件中定义的:
<error-page>
		<error-code>404</error-code>
			<location>/ErrorCodeErrorPage.html</location>
</error-page>
exception-type 错误页元素,它是在 web.xml 文件或 web-fragment.xml 文件中定义的:
<error-page>
		<exception-type>javax.servlet.ServletException</exception-type>
		<location>/ExceptionTypeErrorPage.html</location>
</error-page>
缺省错误页元素,它是在 web.xml 文件或 web-fragment.xml 文件中定义的:
<error-page>
		<location>/DefaultErrorPage.html</location>
</error-page>
模式示例
使用 Servlet 2.5 模式的 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_2_5.xsd"
      version="2.5">
使用 Servlet 3.0 模式的 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">
使用 Servlet 3.1 模式的 web.xml 文件的示例头:
<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
    version="3.1">
使用 Servlet 3.0 模式的 web-fragment.xml 文件的示例头:
<?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 3.1 模式的 web-fragment.xml 文件的示例头:
<?xml version="1.0" encoding="utf-8"?>
<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns="http://xmlns.jcp.org/xml/ns/javaee"
      xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-fragment_3_1.xsd"
      version="3.1">

用于指示主题类型的图标 概念主题

信息中心的条款和条件 | 反馈


时间戳记图标 最近一次更新时间: Wednesday, 2 September 2015
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=cwlp_servlet31_behavior
文件名:cwlp_servlet31_behavior.html