<title>Filter Configuration</title>

Filter configuration follows the Servlet 2.3 deployment descriptors.
Filters generally belong in the <var/WEB-INF/classes/> directory of
the web application.

<p/>The mapping from url to filter is controlled by <a
href='#filter-mapping'>filter mapping</a> in the
application configuration.

<objsummary/>

<section name='web-app' title=web-app>

<defun name=filter title='filter' version="Servlet 2.3">
<sum>Defines a filter alias for later mapping.</sum>

<deftable>
<tr><td>filter-name<td>The filter's name (alias)
<tr><td>filter-class<td>The filter's class (defaults to servlet-name)
<tr><td>init-param<td>Initialization parameters
</deftable>

<p/>The following example defines a filter alias 'image'
<example>
&lt;web-app id='/'&gt;

&lt;filter-mapping url-pattern='/images/*'
                 filter-name='image'/&gt;

&lt;filter filter-name='image'
         filter-class='test.MyImage'&gt;
  &lt;init-param title='Hello, World'/&gt;
&lt;/servlet&gt;

&lt;/web-app&gt;
</example>
</defun>

</section>

<section name='filter' title='web-app/filter'>

<defun name=filter-name title='filter-name' version="Servlet 2.3">
<sum>Alias of the filter</sum>
</defun>

<defun name=filter-class title='filter-class' version="Servlet 2.3">
<sum>Class of the filter</sum>  The CLASSPATH for filters includes
the WEB-INF/classes directory and all jars in the WEB-INF/lib directory.
</defun>

<defun name=init-param title='init-param' version="Servlet 2.3">
<sum>Initializes filter variables.</sum>  <code/filter-param/>
defines initial values for <code/getFilterConfig().getInitParameter("foo")/>.

The full Servlet 2.3 syntax for init-param is supported and
allows a simple shortcut
<example>
&lt;web-app id='/'&gt;

&lt;filter filter-name='test.HelloWorld'&gt;
  &lt;init-param foo='bar'/&gt;

  &lt;init-param&gt;
    &lt;param-name&gt;baz&lt;/param-name&gt;
    &lt;param-value&gt;value&lt;/param-value&gt;
  &lt;/init-param&gt;
&lt;/servlet&gt;

&lt;/web-app>
</example>
</defun>

</section>

<section name='filter-mapping' title='web-app/filter-mapping'>

<defun title="filter-mapping" version="Servlet 2.3">
<sum>Maps url patterns to filters.</sum>  <code/filter-mapping/> has two
children, <ct:anchor/url-pattern/> and <code/filter-name/>.
<ct:anchor/url-pattern/> selects the urls which should execute the filter.

<p/><code/filter-name/> can either specify a servlet class directly or it
can specify a servlet alias defined by <code/filter/>.

<deftable>
<tr><td><ct:anchor/url-pattern/><td>A pattern matching the url:
<var//foo/*/>, <var//foo/>, or <var/*.foo/>
<tr><td>url-regexp<td>A regular expression matching the url
<tr><td>servlet-name<td>A servlet name to match.
<tr><td>filter-name<td>The filter name
<tr><td>filter-class<td>The filter class
<tr><td>init-param<td>Initialization parameters
</deftable>

<example>
&lt;caucho.com&gt;
&lt;web-app id='/'&gt;

&lt;servlet servlet-name='hello'
         servlet-class='test.HelloWorld'/&gt;

&lt;servlet-mapping url-pattern='/hello'
                 servlet-name='hello'/&gt;

&lt;filter filter-name='test-filter'
        filter-class='test.MyFilter'/>

&lt;filter-mapping url-pattern='/hello/*'
                 filter-name='test-filter'/&gt;

&lt;filter-mapping servlet-name='hello'
                 filter-name='test.SecondFilter'/&gt;

&lt;/web-app>
</example>
</defun>

</section>
