Specifying Filter Mappings

A
web container uses filter mappings to decide how to apply filters to web resources.
A filter mapping matches a filter to a web component by name, or to web resources
by URL pattern. The filters are invoked in the order in which filter mappings
appear in the filter mapping list of a WAR. You specify a filter mapping list
for a WAR in its deployment descriptor, either with NetBeans IDE or by
coding the list by hand with XML.

To declare the filter and map it to a web resource using NetBeans IDE,
do the following:

Expand the application’s project node in the Project
pane.

Expand the Web Pages and WEB-INF nodes under the project node.

Double-click web.xml.

Click Filters at the top of the editor pane.

Expand the Servlet Filters node in the editor pane.

Click Add Filter Element to map the filter to a web resource
by name or by URL pattern.

In the Add Servlet Filter dialog, enter the name of the filter
in the Filter Name field.

Click Browse to locate the servlet class to which the filter
applies. You can include wildcard characters so that you can apply the filter
to more than one servlet.

Click OK.

To constrain how the filter is applied to requests, do the following:

Expand the Filter Mappings node in the Filters tab of the
editor pane.

Select the filter from the list of filters.

Click Add.

In the Add Filter Mapping dialog, select one of the following
dispatcher types:

You can direct the filter to be applied to any
combination of the preceding situations by selecting multiple dispatcher types.
If no types are specified, the default option is REQUEST.

You can declare, map, and constrain the filter by editing the XML in
the web application deployment descriptor directly by following these steps:

While in the web.xml editor pane in NetBeans IDE,
click XML at the top of the editor pane.

Declare the filter by adding a filter element
right after the display-name element. The filter element
creates a name for the filter and declares the filter’s implementation
class and initialization parameters.

Map the filter to a web resource by name or by URL pattern
using the filter-mapping element:

Include a filter-name element that specifies
the name of the filter as defined by the filter element.

Include a servlet-name element that specifies
to which servlet the filter applies. The servlet-name element
can include wildcard characters so that you can apply the filter to more than
one servlet.

Constrain how the filter will be applied to requests by specifying
one of the enumerated dispatcher options (described in step 4 of the preceding
set of steps) with the dispatcher element and adding the dispatcher element to the filter-mapping element.

You can direct the filter to be applied to any combination of the preceding
situations by including multiple dispatcher elements. If
no elements are specified, the default option is REQUEST.

If you want to log every request to a web application, you map the hit
counter filter to the URL pattern /*. Table 4–6 summarizes the filter definition and mapping
list for the Duke’s Bookstore application. The filters are matched by
servlet name, and each filter chain contains only one filter.

Table 4–6 Duke’s Bookstore Filter Definition
and Mapping List

Filter

Class

Servlet

HitCounterFilter

filters.HitCounterFilter

BookStoreServlet

OrderFilter

filters.OrderFilter

ReceiptServlet

You can map a filter to one or more web
resources and you can map more than one filter to a web resource. This is
illustrated in Figure 4–4, where
filter F1 is mapped to servlets S1, S2, and S3, filter F2 is mapped to servlet
S2, and filter F3 is mapped to servlets S1 and S2.

Figure 4–4 Filter-to-Servlet Mapping

Recall that
a filter chain is one of the objects passed to the doFilter method
of a filter. This chain is formed indirectly by means of filter mappings.
The order of the filters in the chain is the same as the order in which filter
mappings appear in the web application deployment descriptor.

When a filter is mapped to servlet S1, the
web container invokes the doFilter method of F1. The doFilter method of each filter in S1’s filter chain is invoked
by the preceding filter in the chain by means of the chain.doFilter method.
Because S1’s filter chain contains filters F1 and F3, F1’s call
to chain.doFilter invokes the doFilter method
of filter F3. When F3’s doFilter method completes,
control returns to F1’s doFilter method.