5.6. Declaring Filters
Servlet version 2.3 introduced the concept of filters. Although filters are supported by all servers that support version 2.3 of the servlet API, you must use the version 2.3 DTD in web.xml in order to use the filter-related elements. For details on the DTD, see Section 5.1 (Defining the Header and Root Elements).
|
Filters are discussed in detail in Chapter 9, but the basic idea is that filters can intercept and modify the request coming into or the response going out of a servlet or JSP page. Before a servlet or JSP page is executed, the doFilter method of the first associated filter is executed. When that filter calls doFilter on its FilterChain object, the next filter in the chain is executed. If there is no other filter, the servlet or JSP page itself is executed. Filters have full access to the incoming ServletRequest object, so they can check the client’s hostname, look for incoming cookies, and so forth. To access the output of the servlet or JSP page, a filter can wrap the response object inside a stand-in object that, for example, accumulates the output into a buffer. After the call to the doFilter method of the FilterChain object, the filter can examine the buffer, modify it if necessary, and then pass it on to the client.
For example, Listing 5.11 defines a simple filter that intercepts requests and prints a report on the standard output (available with most servers when you run them on your desktop during development) whenever the associated servlet or JSP page is accessed.
Listing 5.11. ReportFilter.java
package moreservlets;
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import java.util.*;
/** Simple filter that prints a report on the standard output
* whenever the associated servlet or JSP page is accessed.
*/
public class ReportFilter implements Filter {
public void doFilter(ServletRequest request,
ServletResponse response,
FilterChain chain)
throws ServletException, IOException {
HttpServletRequest req = (HttpServletRequest)request;
System.out.println(req.getRemoteHost() +
" tried to access " +
req.getRequestURL() +
" on " + new Date() + ".");
chain.doFilter(request,response);
}
public void init(FilterConfig config)
throws ServletException {
}
public void destroy() {}
} |
Once you have created a filter, you declare it in the web.xml file by using the filter element along with the filter-name (arbitrary name), filter-class (fully qualified class name), and, optionally, init-params subelements. Remember that the order in which elements appear within the web-app element of web.xml is not arbitrary; servers are allowed (but not required) to enforce the expected ordering, and in practice some servers do so. Complete ordering requirements are given in Section 5.2 (The Order of Elements within the Deployment Descriptor), but note here that all filter elements must come before any filter-mapping elements, which in turn must come before any servlet or servlet-mapping elements.
|
For instance, given the ReportFilter class just shown, you could make the following filter declaration in web.xml. It associates the name Reporter with the actual class ReportFilter (which is in the moreservlets package).
<filter> <filter-name>Reporter</filter-name> <filter-class>moreservlets.ReportFilter</filter-class> </filter>
Once you have named a filter, you associate it with one or more servlets or JSP pages by means of the filter-mapping element. You have two choices in this regard.
First, you can use filter-name and servlet-name subelements to associate the filter with a specific servlet name (which must be declared with a servlet element later in the same web.xml file). For example, the following snippet instructs the system to run the filter named Reporter whenever the servlet or JSP page named SomeServletName is accessed by means of a custom URL.
<filter-mapping>
<filter-name>Reporter</filter-name>
<servlet-name>SomeServletName</servlet-name>
</filter-mapping> Second, you can use the filter-name and url-pattern subelements to associate the filter with groups of servlets, JSP pages, or static content. For example, the following snippet instructs the system to run the filter named Reporter when any URL in the Web application is accessed.
<filter-mapping>
<filter-name>Reporter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping> For example, Listing 5.12 shows a portion of a web.xml file that associates the ReportFilter filter with the servlet named PageName. The name PageName, in turn, is associated with a JSP file named TestPage.jsp and URLs that begin with the pattern http://host/webAppPrefix/UrlTest2/. The source code for TestPage.jsp and a discussion of the naming of JSP pages were given earlier in Section 5.3 (Assigning Names and Custom URLs). In fact, the servlet and servlet-name entries in Listing 5.12 are taken unchanged from that section. Given these web.xml entries, you see debugging reports in the standard output of the following sort (line breaks added for readability).
audit.irs.gov tried to access http://mycompany.com/deployDemo/UrlTest2/business/tax-plan.html on Tue Dec 25 13:12:29 EDT 2001.
Listing 5.12. web.xml (Excerpt showing filter usage)
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<filter>
<filter-name>Reporter</filter-name>
<filter-class>moreservlets.ReportFilter</filter-class>
</filter>
<!-- ... -->
<filter-mapping>
<filter-name>Reporter</filter-name>
<servlet-name>PageName</servlet-name>
</filter-mapping>
<!-- ... -->
<servlet>
<servlet-name>PageName</servlet-name>
<jsp-file>/TestPage.jsp</jsp-file>
</servlet>
<!-- ... -->
<servlet-mapping>
<servlet-name>PageName</servlet-name>
<url-pattern>/UrlTest2/*</url-pattern>
</servlet-mapping>
<!-- ... -->
</web-app> |