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。

public class MyServlet extends HttpServlet {
public void doGet (HttpServletRequest req,
HttpServletResponse res) {
....
}
}

Deployment descriptor (web.xml)

<web-app>
<servlet>
<servlet-name>MyServlet</servlet-name>
<servlet-class>samples.MyServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>MyServlet</servlet-name>
<url-pattern>/MyApp</url-pattern>
</servlet-mapping>
...

</web-app>

這裏給出的是使用 Servlet 3.0 API 編寫的較爲簡化的版本。當 MyServlet 使用 @Servlet註釋而被註釋爲一個 servlet 時，則在 web 容器的啓動期間對其初始化。注意，在這種狀況下部署描述符是可選的。

@Servlet(urlMappings={"/MyApp"})
public class MyServlet {
@GET
public void handleGet(HttpServletRequest req,
HttpServletResponse res) {
....
}
}
Deployment descriptor (web.xml)

optional

@ServletFilter 和 @FilterMapping：您可使用 javax.servlet.http.annotation.ServletFilter 註釋來註釋過濾器類，從而輕鬆建立一個 servlet 過濾器。該註釋封裝正被聲明的過濾器的有關元數據。在過濾器類上具備 @FilterMapping 註釋也是強制性的。@FilterMapping 註釋定義用於過濾器的 URL 模式。@ServletFilter 的全部其餘屬性都是可選的，並帶有合理的默認值。V3.0 過濾器類如今相似 POJO 類，而且沒有用於這些類所需的 Filter 接口或者非參數公用構造器。如下給出了使用 Servlet v2.5 API 的過濾器類的代碼片斷：

public class MyFilter implements Filter {
public void doFilter(ServletRequest req,
ServletResponse res,
FilterChain chain)
throws IOException, ServletException {
......
}
}

Deployment descriptor (web.xml)

<web-app>
<filter>
<filter-name>My Filter</filter-name>
<filter-class>samples.MyFilter</filter-class>
</filter>

<filter-mapping>
<filter-name>My Filter</filter-name>
<url-pattern>/foo</url-pattern>
</filter-mapping>
...
</web-app>

使用 Servlet 3.0 編寫的一個示例過濾器類以下所示。由於該類使用 ServletFilter 註釋，因此容器將 MyFilter 標記爲一個過濾器類。MyFilter 截取全部收到的請求，其中該請求的 URL 匹配模式 /foo。Servlet 3.0 爲過濾器配置提供了可選的部署描述符。

@ServletFilter
@FilterMapping("/foo")
public class MyFilter {
public void doFilter(HttpServletRequest req,
HttpServletResponse res) {
.....
}
}

Deployment descriptor (web.xml)

optional

@InitParam：該註釋能夠用來定義必須傳遞給 servlet 或者過濾器類的任意初始化參數。它是 @Servlet 和 @ServletFilter 註釋的一個屬性。如下代碼示例解釋瞭如何將具備 english 值、稱做 lang 的初始化參數傳遞給一個 servlet 類。

@Servlet(urlMappings={"/MyApp"}, initParams ={@InitParam(name="lang", value="english")})
public class MyServlet {
@GET
public void handleGet(HttpServletRequest req,
HttpServletResponse res) {
....
}
}

@ServletContextListener：javax.servlet.http.annotation.ServletContextListener 註釋將該類聲明爲一個 servlet 上下文偵聽器。當 web 容器建立或者銷燬 ServletContext 時，該上下文偵聽器接收註釋。上下文偵聽器是一個 POJO 類，且沒必要實現 ServletContextListener 接口。使用 Servlet 2.5 API 編寫的偵聽器類以下所示。當且僅當您在部署描述符中配置了該偵聽器類，容器才識別它。

public class MyListener implements ServletContextListener {
public void contextInitialized(ServletContextEvent sce) {

}
.....
}

Deployment Descriptor (web.xml)

<web-app>
<listener>
<listener-class>samples.MyListener</listener-class>
</listener>
....
</web-app>

使用 Servlet 3.0 API 編寫的一個獲得極大簡化的偵聽器類，以下所示。