Configuring Filters

---

A web service deployer can control how the container loads and applies filters via the deployment descriptor. Just as we use <servlet> and <servlet-mapping> elements to configure servlets, we can use <filter> and <filter-mapping> elements to configure filters.

Defining Filters

A filter definition associates a filter name with a particular class. The association is specified using the <filter-name> and <filter-class> elements. For example, this filter instance is named Logger and the class used is filters.LoggerFilter:

    <filter>      <filter-name>Logger</filter-name>      <filter-class>filters.LoggerFilter</filter-class>    </filter> 

A filter definition can also be used to specify initialization parameters. Parameters are specified using the <init-param> element, and pairs of <param-name> and <param-value> elements. For example:

      <filter>        <filter-name>XSLTFilter</filter-name>        <filter-class>filters.SmartXSLFilter</filter-class>        <init-param>          <param-name>xsltfile</param-name>          <param-value>/xsl/stockquotes.xsl</param-value>         </init-param>      </filter> 

Each occurrence of a filter definition in the web.xml file specifies a unique instance of a filter that will be loaded by the container. If n filter definitions refer to the same underlying Java class, the container will create n distinct instances of this class.

When the web application starts up, the container creates instances of filters according to the definitions within the deployment descriptor. Instances are created and their init() methods are called according to the order that they are defined within the deployment descriptor. As a container will create a single instance of a filter per filter definition (per Java VM managed by the container), it is imperative that the filter code is thread-safe, as many requests might be processed simultaneously by the same instance.

Mapping Filters

A filter mapping specifies the web resource that a filter instance should be applied to. Filter mappings must be specified after the filter definitions. Mapping filters is very similar to how we map servlets using the <servlet-mapping> element

Filter mappings are specified via the <filter-mapping> element. This element must have a <filter-name> element inside, in order to specify the filter that is to be mapped. The filter that is referred to must have been named in an earlier filter definition.

In addition to the <filter-name> element, a filter mapping should also contain either a <url-pattern> element or a <servlet-name> element. Using the <url-pattern> element, we can specify wild card symbols to define the range of web resources that the filter will apply to. For example, the following Logger filter will be applied to every web resource in the web application:

    <filter-mapping>      <filter-name>Logger</filter-name>      <url-pattern>/*</url-pattern>    </filter-mapping> 

To apply the same filter to just the servlets in the application, we can use this mapping:

    <filter-mapping>      <filter-name>Logger</filter-name>      <url-pattern>/servlet/*</url-pattern>    </filter-mapping> 

In order to obtain even finer-grained control over the web resource that is associated with a filter, we can use the <servlet-name> element to specify a specific servlet within the application. For example, the following filter mapping specifies that the XSLTFilter filter will only be applied to the XMLOutServlet servlet. No other request will trigger this filter:

    <filter-mapping>      <filter-name>XSLTFilter</filter-name>      <servlet-name>XMLOutServlet</servlet-name>    </filter-mapping> 

Chaining Filters

It is possible to specify that multiple filters should be applied to a specific resource. For example, the following set of filter mappings will apply both the XSLTFilter and AuditFilter filters to all the resources in an application:

      <filter-mapping>          <filter-name>XSLTFilter</filter-name>          <url-pattern>/*</url-pattern>      </filter-mapping>      <filter-mapping>          <filter-name>AuditFilter</filter-name>          <url-pattern>/*</url-pattern>      </filter-mapping> 

Such filter chaining can be used as a 'construction set' by a web application deployer, allowing them to build versatile services. For example, an XML to HTML conversion filter, an encryption filter, and a compression filter could be chained together to produce an encrypted, compressed stream of HTML output - all from a servlet that only outputs XML.

The container will construct filter chains based on the order of appearance of the filter mappings within the deployment descriptor.

The order of filters within a chain is very important for the proper operation of an application because filter chaining is not transitive.

Applying filter A, and then applying filter B is not necessarily equal to applying filter B and then filter A.

---