Servlet注释与部署描述符

值得注意的是，部署描述符优先于注释。换句话说，部署描述符覆盖通过注释机制所规定的配置信息。Web 部署描述符的 3.0 版本在 web-app 元素上包含一种名为 metadata-complete 的新属性。该属性定义了 web 描述符是否完整，或者 web 应用程序的类文件是否针对指定部署信息的注释而进行检查。如果该属性被设置为 true，则部署工具必须忽略类文件中所存在的任何 servlet注释，并只使用描述符中所提及的配置细节。否则，如果没有指定该值或者该值被设置为 false，容器必须针对注释而扫描应用程序的所有类文件。这个属性提供了在应用程序启动阶段启用或者禁用注释扫描以及对注释的处理。

在 Servlet 3.0 中所引入的所有注释都可以在 javax.servlet.http.annotation 和 javax.servlet.http.annotation.jaxrs 软件包中找到。以下章节阐述 Servlet注释的完整集合：

@Servlet：javax.servlet.http.annotation.Servlet 是一个类级别的注释，确认经过注释的类为一个 servlet 并保存关于所声明的 servlet 的元数据。urlMappings 属性是指定 URL 模式(调用该 servlet)的 @Servlet 的强制属性。当接收到了一个请求时，容器将请求中的 URL 与 servlet 的 urlMappings 进行匹配，且如果 URL 模式匹配，则调用相应的 servlet 以响应该项请求。该注释的所有其他属性都是可选的，并带有合理的默认值。Servlet 类中必须有一种使用像 GET、PUT、POST、HEAD 或者 DELETE 这样的 HttpMethod 注释进行注释的方法。这些方法应将 HttpServletRequest 和 HttpServletResponse 作为方法参数。与以前的版本相反，servlets 3.0 的版本可以作为简单传统 Java 对象(Plain Old Java Objects，POJOs)而实现;也就是 servlets 不必再扩展像 HTTPServlet 或者 GenericServlet 这样的基础 servlet 实现类。

为了进行比较，在此给出了使用传统 Servlet 2.5 API 编写的 Java servlet 代码片段，如下所示。在 Servlet 2.5 中，只要在部署描述符中配置了 servlet 的详细信息，web 容器就将初始化 servlet。

1. public class MyServlet extends HttpServlet {
2. public void doGet (HttpServletRequest req,
3. HttpServletResponse res) {
4. ....
5. }
6. }

Deployment descriptor (web.xml)

1. <web-app>
2. <servlet>
3. <servlet-name>MyServlet</servlet-name>
4. <servlet-class>samples.MyServlet</servlet-class>
5. </servlet>
6. <servlet-mapping>
7. <servlet-name>MyServlet</servlet-name>
8. <url-pattern>/MyApp</url-pattern>
9. </servlet-mapping>
10. ...
11. </web-app>

这里给出的是使用 Servlet 3.0 API 编写的较为简化的版本。当 MyServlet 使用 @Servlet注释而被注释为一个 servlet 时，则在 web 容器的启动期间对其初始化。注意，在这种情况下部署描述符是可选的。

1. @Servlet(urlMappings={"/MyApp"})
2. public class MyServlet {
3. @GET
4. public void handleGet(HttpServletRequest req,
5. HttpServletResponse res) {
6. ....
7. }
8. }
9. Deployment descriptor (web.xml)
10. optional

@ServletFilter 和 @FilterMapping：您可以使用 javax.servlet.http.annotation.ServletFilter 注释来注释过滤器类，从而轻松创建一个 servlet 过滤器。该注释封装正被声明的过滤器的有关元数据。在过滤器类上具有 @FilterMapping 注释也是强制性的。@FilterMapping 注释定义用于过滤器的 URL 模式。@ServletFilter 的所有其他属性都是可选的，并带有合理的默认值。V3.0 过滤器类现在类似 POJO 类，并且没有用于这些类所需的 Filter 接口或者非参数公用构造器。以下给出了使用 Servlet v2.5 API 的过滤器类的代码片段：

1. public class MyFilter implements Filter {
2. public void doFilter(ServletRequest req,
3. ServletResponse res,
4. FilterChain chain)
5. throws IOException, ServletException {
6. ......
7. }
8. }
9. Deployment descriptor (web.xml)
10. <web-app>
11. <filter>
12. <filter-name>My Filter</filter-name>
13. <filter-class>samples.MyFilter</filter-class>
14. </filter>
15. <filter-mapping>
16. <filter-name>My Filter</filter-name>
17. <url-pattern>/foo</url-pattern>
18. </filter-mapping>
19. ...
20. </web-app>

使用 Servlet 3.0 编写的一个示例过滤器类如下所示。因为该类使用 ServletFilter 注释，所以容器将 MyFilter 标记为一个过滤器类。MyFilter 截取所有收到的请求，其中该请求的 URL 匹配模式 /foo。Servlet 3.0 为过滤器配置提供了可选的部署描述符。

1. @ServletFilter
2. @FilterMapping("/foo")
3. public class MyFilter {
4. public void doFilter(HttpServletRequest req,
5. HttpServletResponse res) {
6. .....
7. }
8. }
9. Deployment descriptor (web.xml)
10. optional

@InitParam：该注释可以用来定义必须传递给 servlet 或者过滤器类的任意初始化参数。它是 @Servlet 和 @ServletFilter 注释的一个属性。以下代码示例解释了如何将具有 english 值、称作 lang 的初始化参数传递给一个 servlet 类。

1. @Servlet(urlMappings={"/MyApp"}, initParams ={@InitParam
   (name="lang", value="english")})
2. public class MyServlet {
3. @GET
4. public void handleGet(HttpServletRequest req,
5. HttpServletResponse res) {
6. ....
7. }
8. }

@ServletContextListener：javax.servlet.http.annotation.ServletContextListener 注释将该类声明为一个 servlet 上下文侦听器。当 web 容器创建或者销毁 ServletContext 时，该上下文侦听器接收注释。上下文侦听器是一个 POJO 类，且不必实现 ServletContextListener 接口。使用 Servlet 2.5 API 编写的侦听器类如下所示。当且仅当您在部署描述符中配置了该侦听器类，容器才识别它。

1. public class MyListener implements ServletContextListener {
2. public void contextInitialized(ServletContextEvent sce) {
3. }
4. .....
5. }
6. Deployment Descriptor (web.xml)
7. <web-app>
8. <listener>
9. <listener-class>samples.MyListener</listener-class>
10. </listener>
11. ....
12. </web-app>

使用 Servlet 3.0 API 编写的一个得到极大简化的侦听器类，如下所示。

1. @ServletContextListener
2. public class MyListener {
3. public void contextInitialized (ServletContextEvent sce) {
4. }
5. .....
6. }
7. Deployment Descriptor (web.xml)
8. optional