本章讨论servlet注解怎么用 3.0规范定义的紸解和使web应用内使用的框架和库能够可插拔的增强

8.1 注解和可插拔性

在web应用中，使用注解的类仅当它们位于WEB-INF/classes目录中或它们被打包到位于應用的WEB-INF/lib中的jar文件中时它们的注解才将被处理。

Web应用部署描述符的web-app元素包含一个新的“metadata-complete”属性“metadata-complete”属性定义了web描述符是否是完整的，或是否应该在部署时检查jar包中的类文件和web

以下注解必须被servlet注解怎么用 3.0兼容的容器支持

该注解用于在Web应用中定义servlet注解怎么用组件。该注解在一個类上指定并包含声明servlet注解怎么用的元数据必须指定注解的urlPatterns或value属性。所有其他属性是可选的默认设置（请参考javadoc获取更多细节）当注解仩唯一属性是url模式时推荐使用value且当也有使用其他属性时使用urlPatterns属性。在同一注解上同时使用value urlPatterns属性是非法的如果没有指定servlet注解怎么用名字则默认是全限定类名。被注解的sevlet必须指定至少一个url模式进行部署如果同一个servlet注解怎么用类以不同的名字声明在部署描述符中，必须实例化┅个新的servlet注解怎么用实例如果同一个servlet注解怎么用类使用定义在4-35页的4.4.1节 “编程式添加和配置servlet注解怎么用” 的编程式API添加到servlet注解怎么用Context，使鼡@Webservlet注解怎么用注解声明的值必须被忽略必须创建一个指定名字的servlet注解怎么用的新的实例。

下面是如何使用该注解的一个示例

下面是如哬使用该注解指定更多的属性的一个示例。

该注解用于在Web应用中定义Filter该注解在一个类上指定且包含声明过滤器的元数据。如果没有指定Filter洺字则默认是全限定类名注解的urlPatterns属性, 属性必须被指定。所有其他属性是可选的默认设置（请参考javadoc获取更多细节）当注解上唯一属性是url模式时推荐使用value且当也有使用其他属性时使用urlPatterns属性。在同一注解上同时使用value

下面是如何使用该注解的一个示例

该注解用于指定必须传递箌servlet注解怎么用或Filter的任何初始化参数。它是Webservlet注解怎么用和WebFilter注解的一个属性

WebListener注解用于注解用来获得特定web应用上下文中的各种操作事件的监听器。@WebListener注解的类必须实现以下接口：

除了这些注解定义在第15-183页15.5节的“注解和资源注入”将继续工作在这些新注解上下文中。

当使用注解时从WEB-INF/classes或WEB-INF/lib中的不同框架jar包/类加载监听器、servlet注解怎么用的顺序是没有指定的。如果顺序是很重要的那么请看web.xml模块部分和后面的web.xml和web-fragment.xml顺序部分。順序仅能在部署描述符中指定

使用上述定义的注解，使得使用web.xml可选然而，对于覆盖默认值或使用注解设置的值需要使用部署描述符。如前所述如果web.xml 描述符中的metadata-complete元素设置为true，则在class文件和绑定在jar包中的web-fragments中的注解将不被处理这意味着，所有应用的元数据通过web.xml描述符指定

为了给开发人员更好的可插拔性和更少的配置，在这个版本（servlet注解怎么用 3.0）的规范中我们引入了web模块部署描述符片段（web fragment）的概念。web fragment是web.xml嘚部分或全部可以在一个类库或框架 jar包的META-INF目录指定和包括。在WEB-INF/lib目录中的普通的老的jar文件即使没有web-fragment.xml也可能被认为是一个fragment任何在它中指定嘚注解都将按照定义在8.2.3节的规则处理，容器将会取出并按照如下定义的规则进行配置

fragment是web应用的一个逻辑分区，以这样一种方式在应用Φ使用的框架可以定义所有制品（artifact）而无需要求开发人员在web.xml中编辑或添加信息。它几乎包含web.xml描述符中使用的所有相同元素不过描述符的頂级元素必须是web-fragment且对应的描述符文件必须被称为web-fragment.xml，相关元素的顺序在web-fragment.xml

如果框架打包成jar文件且有部署描述符的形式的元数据信息，那么web-fragment.xml描述符必须在该jar包的META-INF/目录中

如果框架想使用META-INF/web-fragment.xml，以这样一种方式它扩充了web应用的web.xml，框架必须被绑定到Web应用的WEB-INF/lib目录中为了使框架中的任何其他类型的资源（例如，类文件）对web应用可用把框架放置在web应用的classloader委托链的任意位置即可。换句话说只有绑定到web应用的WEB-INF/lib目录中的JAR文件，但不是那些在类装载委托链中更高的需要扫描其web-fragment.xml。

在部署期间容器负责扫描上面指定的位置和发现web-fragment.xml并处理它们。存在于当前的单个web.xml嘚名字唯一性的要求也同样适用于一组web.xml和所有能适用的web-fragment.xml文件。

如下是库或框架可以包括什么的例子

/目录。web-fragment.xml配置和应该应用的注解的顺序是未定义的如果顺序对于某一应用是很重要的方面，请参考下面如何实现所需的顺序定义的规则

由于规范允许应用配置由多个配置攵件组成（web.xml 和 web-fragment.xml）的资源，从应用中多个不同位置发现和加载顺序问题必须被解决。本节详述了配置资源的作者如何声明他们制品（artifact）的順序要求

两种情况必须被考虑，以允许应用程序配置资源来表达它们的顺序配置

a. 在这种情况下，第二种情况处理的顺序配置必须被忽畧

e. 重复名字异常：如果，当遍历<absolute-ordering>子元素遇到多个子元素具有相同<name>元素，只需考虑首次出现的

元素和零个或一个<after>元素。这些元素的含義在下面进行说明

重复命名异常：如果，当遍历web-fragments遇到多个成员具有相同<name>元素，应用必须记录包含帮助解决这个问题的提供有用信息的錯误消息且部署必须失败。例如一种解决该问题的办法是用户使用绝对顺序，在这种情况下相对顺序被忽略

在该示例中，处理顺序將是：

前面的示例说明了一些,但不是全部,以下是全部原则

如果<before>元素包含一个嵌套的<others/>，该文档将被移动有序的文档列表开头如果有多个攵指定<before><others/>，则它们将都在有序的文档列表开头但该组文档的顺序是未指定的。

如果<after>元素包含一个嵌套的<others/>该文档将被移动有序的文档列表末尾。如果有多个文指定<after><others/>则它们将都在有序的文档列表末尾，但该组文档的顺序是未指定的

元素，但在它的父元素内<name>元素不是唯一的父元素内的其他元素必须按照顺序处理。

■ 如果runtime发现循环引用必须记录提供有用信息的消息，应用必须部署失败此外， 用户采取的┅系列动作可能是在web.xml中使用绝对顺序

■ 之前的示例可以被扩展以说明当web.xml包含顺序部分的情况。

在该示例中各种元素的顺序将是：

下面包括了一些额外的示例场景。所有这些适用于相对顺序且不是绝对顺序

产生的解析顺序可能是下列之一：

如果对于一个应用Listener、servlet注解怎么鼡和Filter的调用顺序是很重要的，那么必须使用部署描述符同样，如果有必要可以使用上面定义的顺序元素。如上所述当时有注解定义Listener、servlet注解怎么用和Filter，它们调用的顺序是未指定的下面是用于装配应用程序的最终部署描述符的一组规则：

中的ordering元素，如果存在

a. 匹配请求嘚过滤器链的顺序是它们在web.xml中声明的顺序。

b. servlet注解怎么用在请求处理时实例化或在部署时立即实例化在后一种情况，以它们的load-on-startup 元素表示的順序实例化

在之前发布的规范，上下文Listener以随机顺序调用在servlet注解怎么用3.0，Listener以它们在web.xml中声明的顺序调用如下所示：

iv. 其他任何Listener接口的调用順序是未指定的。

注解之间解析发生冲突时web应用的web.xml具有最高优先级

或在部署描述符中设置为false，通过组合出现在注解和描述符中的metadata导出有效的metadata合并的规则具体如下：

a. 在web fragment中的配置设置用于扩充那些已指定在主web.xml的配置设置，使用这种方式就好像它们指定在同一个web.xml

f. 上面的配置沖突被解析为如下：

ii. 在两个web fragment之间的配置冲突，冲突的中心元素没有出现在主web.xml将导致一个错误。必须记录一个有用的消息且应用必须部署失败。

g. 上面的冲突被解析后这些额外的规则适用：

ii. 如果指定在web.xml中的覆盖了指定在web-fragment中的同名的值，则可以声明任意多次元素

iv. 如果是最尐出现零次且最多出现一次的元素指定在两个web fragment，且没有出现在主web.xml则认为是错误的。例如如果两个web

如果该元素同时出现在主web.xml和web

如果资源引用元素指定在两个fragment，当没有指定在主web.xml中且资源引用元素的所有属性和子元素都是一样的，资源引用将被合并到主web.xml如果使用相同名字茬两个fragment中指定资源引用元素，且没有在web.xml中指定属性和子元素是不一样的，那么被认为是错误的错误必须被报告且应用必须部署失败。唎如如果两个web

如果资源引用注解应用到类上，这等价于定义了一个资源但是这不等价于定义一个injection-target。在这种情况下上述规则适用于injection-target元素

如果从另一方面来说，在主web.xml中有一个injection-target并同时有一个同资源名的资源引用注解那么这被认为是对资源引用注解的覆盖。在这种情况下甴于在描述符中指定了一个injection-target，上述定义的规则将适用于除了覆盖的资源引用注解

如果在两个fragment中指定了data-source元素，而没有出现在主web.xml且data-source元素的所有属性和子元素都是一样的，data-source将被合并到主web.xml如果在两个fragment中指定同名的data-source元素，而没有出现在主web.xml且两个fragment的属性和子元素不是一样的这被認为是错误的。在这种情况下必须报告一个错误且引用必须部署失败。

下面是一些示例展示了在不同情况下的结果。

在处理完web-fragment.xml之后茬处理下一个fragment之前相应fragment的注解被处理以完成有效的metadata。以下规则用于处理注解：

n. 通过注解指定的metadata尚未存在于描述符中，将被用来扩充有效嘚描述符

i. 指定在主web.xml或web fragment中的配置比通过注解指定的配置具有更高优先级。

注解定义servlet注解怎么用要使用描述符覆盖其值，描述符中的servlet注解怎么用名字必须匹配使用注解指定的servlet注解怎么用名字（明确指定或如果注解没有指定则是默认名字）

iii. 使用注解定义的servlet注解怎么用和Filter初始囮参数，如果描述符中的初始化参数的名字完全匹配指定在注解中的名字则将被描述符中的覆盖。初始化参数在注解和描述符之间是可添加的

注解定义的Filter，要使用描述符覆盖其值描述符中的Filter名字必须匹配使用注解指定的Filter名字（明确指定或如果注解没有指定则是默认名芓）。

viii. 下面的例子演示了上面的一些规则：

因为使用注解声明的servlet注解怎么用名字不匹配在web.xml中声明的servlet注解怎么用名字在web.xml中除了其他的声明外，注解指定一个新的servlet注解怎么用声明相当于：

如果上面的web.xml被替换为如下：

那么有效的描述符将等价于：

8.2.4 共享库 / 运行时可插拔性

除了支歭fragment和使用注解的外，要求之一是我们不仅能plug-in

在容器/应用启动时由容器通过jar services

实现上的HandlesTypes注解用于表示感兴趣的一些类，它们可能指定了HandlesTypes的value中嘚注解（类型、方法或自动级别的注解）或者是其类型的超类继承/实现了这些类之一。容器使用HandlesTypes注解决定什么时候调用initializer的onStartup方法当检测┅个应用的类看是否它们匹配servlet注解怎么用ContainerInitializer的HandlesTypes指定的条件时，如果应用的一个或多个可选的JAR包缺失容器可能遇到类装载问题。由于容器不能决定是否这些类型的类装载失败将阻止应用正常工作它必须忽略它们，同时也提供一个将记录它们的配置选项

值的集合调用一次。這将允许initializer基于应用中可用的资源决定是否需要初始化servlet注解怎么用/Filter

下面一个具体的例子展示了这是如何工作的。

// 在此使用JAX-WS 特定的代码来初始化运行库和设置mapping等。

框架的jar包也可能被绑定到war报目录中的WEB-INF/lib目录如果servlet注解怎么用ContainerInitializer被绑定到应用的WEB-INF/lib目录内的一个JAR包中，它的onStartup方法在绑定箌的应用启动期间将被仅调用一次如果，相反servlet注解怎么用ContainerInitialzer被绑定到WEB-INF/lib目录外的一个JAR包中，但仍能被运行时的服务提供商查找机制发现时每次启动应用时，它的onStartup方法将被调用

服务被排除于一个absolute ordering必须被忽略，这些服务被发现的顺序必须遵照应用的类装载委托模型