Understanding and Using Servlet Filters

Overview of How Filters Work

This section provides an overview of the following topics:

• How
  the Servlet Container Invokes Filters


• Typical
  Filter Actions

How the Servlet Container Invokes
Filters

Figure
5-1 shows, on the left, a scenario in which no filters are configured
for the servlet being requested. On the right, several filters (1, 2, ..., N)
have been configured.

Figure 5-1 Servlet Invocation with and without
Filters

 
Description of the illustration
invfilt.gif

Each filter implements
the javax.servlet.Filter interface, which includes
a doFilter() method that takes as input a request and
response pair along with a filter chain, which is an instance of a class
(provided by the servlet container) that implements
the javax.servlet.FilterChain interface. The filter chain
reflects the order of the filters. The servlet container, based on the
configuration order in the web.xml file, constructs the
chain of filters for any servlet or other resource that has filters mapped to
it. For each filter in the chain, the filter chain object passed to it
represents the remaining filters to be called, in order, followed by the target
servlet.

The FilterChain interface also specifies
a doFilter() method, which takes a request and response
pair as input and is used by each filter to invoke the next entity in the
chain.

Also see "Standard
Filter Interfaces".

If there are two filters, for example, the key steps of this mechanism would
be as follows:

1. The target servlet is requested. The container detects that there are two
   filters and creates the filter chain.


2. The first filter in the chain is invoked by
   its doFilter() method.


3. The first filter completes any preprocessing, then calls
   the doFilter() method of the filter chain. This results
   in the second filter being invoked by
   its doFilter() method.


4. The second filter completes any preprocessing, then calls
   the doFilter() method of the filter chain. This results
   in the target servlet being invoked by
   its service() method.


5. When the target servlet is finished, the
   chain doFilter() call in the second filter returns, and
   the second filter can do any postprocessing.


6. When the second filter is finished, the
   chain doFilter() call in the first filter returns, and
   the first filter can do any postprocessing.


7. When the first filter is finished, execution is complete.

None of the filters are aware of their order. Ordering is handled entirely
through the filter chain, according to the order in which filters are configured
in web.xml.

Typical Filter Actions

The following are among the possible actions of
the doFilter() method of a filter:

• Create a wrapper for the request object to allow input filtering. Process
  the content or headers of the request wrapper as desired.


• Create a wrapper for the response object to allow output filtering. Process
  the content or headers of the response wrapper as desired.


• Pass the request and response pair (or wrappers) to the next entity in the
  chain, using the chain doFilter() method.
  Alternatively, to block request processing, do not call the
  chain doFilter() method.

Any processing you want to occur before the target resource is invoked must
be prior to the chain doFilter() call. Any processing you
want to occur after the completion of the target resource must be after the
chain doFilter() call. This can include directly setting
headers on the response.

Note that if you want to preprocess the request object or postprocess the
response object, you cannot directly manipulate the original request or response
object. You must use wrappers. When postprocessing a response, for example, the
target servlet has already completed and the response could already be committed
by the time a filter would have a chance to do anything with the response. You
must pass a response wrapper instead of the original response in the
chain doFilter() call. See "Using
a Filter to Wrap and Alter the Request or Response".

Standard Filter Interfaces

A servlet filter implements
the javax.servlet.Filter interface. The main method of
this interface, doFilter(), takes
a javax.servlet.FilterChain instance, created by the
servlet container to represent the entire chain of filters, as input. The
initialization method of
the Filter interface, init(), takes a
filter configuration object, which is an instance
of javax.servlet.FilterConfig, as input. This section briefly
describes the methods specified in these interfaces.

For additional information about the interfaces and methods discussed here,
refer to the Sun Microsystems Javadoc for
the javax.servlet package, at:

http://java.sun.com/j2ee/1.4/docs/api/index.html

Methods of the Filter Interface

The Filter interface specifies the following methods
to implement in your filters:

• void init(FilterConfig filterConfig)

  The servlet container calls init() as a filter is
  first instantiated and placed into service. This method takes
  a javax.servlet.FilterConfig instance as input, which
  the servlet container uses to pass information to the filter during the
  initialization. Include any special initialization requirements in your
  implementation. Also see "Methods
  of the FilterConfig Interface".



• void doFilter(ServletRequest request, ServletResponse response,
FilterChain chain)

  This is where your filter processing occurs. Each time a target resource
  (such as a servlet or JSP page) is requested, where the target resource is
  mapped to a chain of one or more filters, the servlet container calls
  the doFilter() method of each filter in the chain, in
  order according to web.xml filter configurations.
  (See "Construction
  of the Filter Chain".) Within
  the doFilter() processing of a filter, invoke
  the doFilter() method on the filter chain object that
  is passed in to the doFilter() method of the filter.
  (An exception to this is if you want to block request processing.) This is
  what leads to invocation of the next entity in the chain (either the next
  filter, or the target servlet if this is the last filter in the chain) after a
  filter has completed.



• destroy(): The servlet container
  calls destroy() after all execution of the filter has
  completed (all threads of the doFilter() method have
  completed, or a timeout has occurred) and the filter is being taken out of
  service. Include any special cleanup requirements in your implementation.

Configure the Filter

This section lists the steps in configuring a servlet filter. Do the
following in web.xml for each filter:

1. Declare the filter through a <filter> element
   and its subelements, which maps the filter class (including package) to a
   filter name. For example:

   <filter>
   
       <filter-name>timer</filter-name>
   
       <filter-class>filter.TimerFilter</filter-class>
   
   </filter>
   
   

   
   

   You can optionally specify initialization parameters here, similarly to how
   you would for a servlet:

   <filter>
   
       <filter-name>timer</filter-name>
   
       <filter-class>filter.TimerFilter</filter-class>
   
       <init-param>
   
           <param-name>name</param-name>
   
           <param-value>value</param-value>
   
       <init-param>
   
   </filter>
   
   




2. Using a <filter-mapping> element and its
   subelements, map the filter name to a servlet name or URL pattern to associate
   the filter with the corresponding resource (such as a servlet or JSP page) or
   resources. For example, to have the filter invoked whenever the servlet of
   name myservlet is invoked:

   <filter-mapping>
   
       <filter-name>timer</filter-name>
   
       <servlet-name>myservlet</servlet-name>
   
   </filter-mapping>
   
   

   
   

   Or, to have the filter invoked
   whenever sleepy.jsp is requested, according to URL
   pattern:

   <filter-mapping>
   
       <filter-name>timer</filter-name>
   
       <url-pattern>/sleepy.jsp</url-pattern>
   
   </filter-mapping>
   
   

   
   

   Note that instead of specifying a particular resource in
   the <url-pattern> element, you can use wild card
   characters to match multiple resources, such as in the following example:

   <url-pattern>/mypath/*</url-pattern>
   
   

The filter name can be arbitrary, but preferably is meaningful. It is simply
used as the linkage in mapping a filter class to a servlet name or URL
pattern.

If you configure multiple filters that apply to a resource, they will be
entered in the servlet chain according to their declaration order
in web.xml, and they will be invoked in that order when the
target servlet is requested. See the next section, "Construction
of the Filter Chain".

Construction of the Filter Chain

When you declare and map filters in web.xml, the servlet
container determines which filters apply to each servlet or other resource (such
as a JSP page or static page) in the Web application. Then, for each servlet or
resource, the servlet container builds a chain of applicable filters, according
to your web.xmlconfiguration order, as follows:

1. First, any filters that match a servlet or resource according to
   a <url-pattern> element are placed in the
   chain, in the order in which the filters are declared
   in web.xml.


2. Next, any filters that match a servlet or resource according to
   a <servlet-name> element are placed in the
   chain, with the first <servlet-name> match
   following the
   last <url-pattern> match.


3. Finally, the target servlet or other resource is placed at the end of the
   chain, following the last filter with
   a <servlet-name> match.

Java servlet filter chain order

The servlet API allows servlet filters to be inserted into the
processing cycle to form a Filter Chain. How is a chain defined, and what is the
ordering of filters in the chain? 

The servlet filter
chain is formed by defining multiple filters for the same servlet or URL pattern
in web.xml. The order in which the filters are
invoked is the same order
as <filter-mapping>s appear in
the web.xml file. 

For
example, if this is defined
in web.xml:

<!-- Filter mapping -->

<filter-mapping>

        <filter-name>servletFilter2</filter-name>

        <servlet-name>filterdemo</servlet-name>

</filter-mapping>

<filter-mapping>

        <filter-name>servletFilter</filter-name>

        <servlet-name>filterdemo</servlet-name>

</filter-mapping>

then servletFilter2 will be
applied
before servletFilter. 

Actually,
it‘s more accurate to imagine these filters as layers or wraps instead of
chains. In the above
example, servletFilter2 wraps servletFilter.

Using a Filter to Wrap and Alter the Request or
Response

Particularly useful functions for a filter are to manipulate a request, or
manipulate the response to a request. To manipulate a request or response, you
must create a wrapper. You can use the following general steps:

1. To manipulate requests, create a class that extends the
   standard javax.servlet.http.HttpServletRequestWrapper class.
   This class will be your request wrapper, allowing you to modify a request as
   desired.


2. To manipulate responses, create a class that extends the
   standard javax.servlet.http.HttpServletResponseWrapper class.
   This class will be your response wrapper, allowing you to modify a response
   after the target servlet or other resource has delivered and possibly
   committed it.


3. Optionally create a class that extends the
   standard javax.servlet.ServletOutputStream class, if
   you want to add custom functionality to an output stream for the response.


4. Create a filter that uses instances of your custom classes to alter the
   request or response as desired.

The next section, "Response
Filter Example", provides an example of a filter that alters the
response.

Response Filter Example

This example employs an HTTP servlet response wrapper that uses a custom
servlet output stream. This functionality allows the wrapper to manipulate the
response data after the target HTML page is finished writing it out. Without
using a wrapper, you cannot change the response data after the servlet output
stream has been closed (essentially, after the servlet has committed the
response). That is the reason for implementing a filter-specific extension to
the ServletOutputStream class in this example.

This example uses the following custom classes:

• GenericResponseWrapper:
  Extends HttpServletResponseWrapper for custom
  functionality in manipulating an HTTP response.


• FilterServletOutputStream:
  Extends ServletOutputStream to provide custom
  functionality for use in the response wrapper.


• MyGenericFilter: This class is for a generic, empty
  ("pass-through") filter that is used as a base class.


• PrePostFilter:
  Extends MyGenericFilter and
  implements doFilter() code to alter the HTTP response,
  inserting a line before the HTML page output and a line after the HTML page
  output.

Understanding and Using Servlet Filters,布布扣,bubuko.com