<document>
  <header>
    <product>resin</product>
    <title>Filters</title>
    <type>contents</type>
  </header>

  <body>

<localtoc/>

<s1 title="Filter Configuration">
<p>Filter configuration follows the Servlet 2.3 deployment descriptors.
Creating and using a filter has three steps:</p>

<ol>
<li>Create a filter class which extends javax.servlet.Filter
</li><li>Use <a href="#filter">&lt;filter&gt;</a> in the web.xml to configure the filter.
</li><li>Use <a href="#filter-mapping">&lt;filter-mapping&gt;</a> to select URLs and servlets for the filter.
</li></ol>

<p>Some other pages which discuss filters include:</p>

<ul>
<li>Resin's <a href="filter-library.xtp">filter library</a>
</li></ul>

<s2 title="filter" version="Servlet 2.3" type="defun">
<p>Defines a filter alias for later mapping.</p>

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

<p>The following example defines a filter alias 'image'</p>
<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;/filter&gt;

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

<s2 title="filter-name" version="Servlet 2.3" type="defun">
<p>Alias of the filter.</p>
</s2>

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

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

<p>The full Servlet 2.3 syntax for init-param is supported and
allows a simple shortcut</p>
<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;/filter&gt;

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

<s2 title="filter-mapping" version="Servlet 2.3" type="defun">
<p>Maps url patterns to filters.  <var>filter-mapping</var> has two
children, <var>url-pattern</var> and <var>filter-name</var>.
<var>url-pattern</var> selects the urls which should execute the filter.
</p>

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

<deftable>
<tr><th>Configuration</th><th>Description
</th></tr><tr><td>url-pattern</td><td>A pattern matching the url:
<var>/foo/*</var>, <var>/foo</var>, or <var>*.foo</var>
</td></tr><tr><td>url-regexp</td><td>A regular expression matching the url
</td></tr><tr><td>servlet-name</td><td>A servlet name to match.
</td></tr><tr><td>filter-name</td><td>The filter name
</td></tr><tr><td>filter-class</td><td>The filter class
</td></tr><tr><td>init-param</td><td>Initialization parameters
</td></tr></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'/&gt;

&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&gt;
</example>
</s2>

</s1>

<s1 title="GzipFilter">

<p>The GzipFilter compresses the output of pages for browsers which understand
compression, and leaves the output unchanged if the browser does not support
compression.  A browser indicates to the server that it supports gzip
compression by including "gzip" in the "Accept-Encoding" request header.</p>

<p>GzipFilter is available in Resin-Professional.</p>

<deftable-parameters>
<tr><td>use-vary</td><td>Set the standard HTTP "Vary" response header to "Accept-Encoding". This indicates to the browser and any intervening cache that the response from this url might be different depending on the Accept-Encoding provided by the browser.</td><td>true
</td></tr><tr><td>no-cache</td><td>Forbid the browser and any intervening cache from caching the results of this request. Sets the "Cache-Control" response header to "no-cache".  If use-vary is false then this is always true.</td><td>false
</td></tr><tr><td>embed-error-in-output</td><td>Embed the stack trace of any exception into the output stream that is being sent to the browser.</td><td>false
</td></tr></deftable-parameters>

<example>
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;filter filter-name="gzip"
          filter-class="com.caucho.filters.GzipFilter"/&gt;

  &lt;filter-mapping url-pattern="/*" filter-name="gzip"/&gt;
&lt;/web-app&gt;
</example>

<p>See <a href="javadoc|com.caucho.filters.GzipFilter|"/>.</p>
</s1>

<s1 title="XsltFilter">

<p>The XsltFilter transforms the response using xslt.  A Servlet or a JSP can
produce XML results which are transformed using xslt.</p>

<example>
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;filter filter-name="xslt"
          filter-class="com.caucho.filters.XsltFilter"/&gt;

  &lt;filter-mapping url-pattern="/*.jsp" filter-name="xslt"/&gt;
&lt;/web-app&gt;
</example>

<deftable-parameters>
<tr><td>unconditional</td><td>always do a transformation, regardless of the content type.</td><td>false
</td></tr></deftable-parameters>

<p>
See <a href="javadoc|com.caucho.servlets.XsltFilter|"/>.
</p>

<s2 name="specify-stylesheet" title="A request attribute or xml processing directive specifies the stylesheet">

<p>
Resin's XsltFilter determines the stylesheet (*.xsl file) to apply from the
first of:
</p>

<ol>
<li>The value of <code>request.getAttribute("caucho.xsl.stylesheet")</code>
</li><li>A stylesheet specified in the source document with <code>&lt;?xml-stylesheet href='...'?&gt;</code>
</li><li><code>default.xsl</code>
</li></ol>

<p>
The classpath is used to find the stylesheet.  A stylesheet can be placed in
<code>WEB-INF/classes/</code>, or a specific <code>xsl</code> directory can be
indicated: 
</p>

<example title="Classpath for xsl stylesheets">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;class-loader&gt;
    &lt;simple-loader path="WEB-INF/xsl"/&gt;
  &lt;/class-loader&gt;

  ...
&lt;/web-app&gt;


WEB-INF/xsl/default.xsl
</example>

<p>In a JSP the request attribute can be set with the following:</p>

<example title="request attribute to indicate the stylesheet">
&lt;% request.setAttribute("caucho.xsl.stylesheet","transform.xsl"); %&gt;
</example>

<p>Specifying a processing instruction is another way to indicate the stylesheet (but a bit slower for performance considerations):</p>

<example title="processing instruction to indicate the stylesheet">
&lt;?xml-stylesheet type="text/xsl" href="transform.xsl"?&gt;
</example>

</s2>

<s2 name="content-type" title="The stylesheet is applied only for certain content types">

<p>The filter by default will only transform responses that have a content type
of one of the following:</p> 
<ul>
<li>x-application/xslt
</li><li>x-application/xsl
</li><li>x-application/stylescript
</li></ul>

<p>The filter can also be configured to unconditionally do a transformation
regardless of the content type:</p> 

<example>
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;filter filter-name='xslt' filter-class='com.caucho.filters.XsltFilter'&gt;
    &lt;init&gt;
      &lt;unconditional&gt;true&lt;/unconditional&gt;
    &lt;/init&gt;
  &lt;/filter&gt;

  &lt;filter-mapping url-pattern='/xslt/*' filter-name='xslt'/&gt;
&lt;/web-app&gt;
</example>

</s2> <!-- content-type -->

</s1>  <!-- XsltFilter -->

<s1 title="TransactionFilter">

<p>The TransactionFilter wraps the request in a UserTransaction and
commits the transaction when the servlet completes. All database calls for
the request will either succeed together or fail.  The UserTransaction is obtained by doing a jndi lookup with the name "java:comp/UserTransaction".</p>

<p>This filter will gracefully handle any exceptions that occur during the
request by doing a rollback on the transaction.</p>

<example>
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;filter filter-name='transaction-filter'
          filter-class='com.caucho.filters.TransactionFilter'/&gt;

  &lt;filter-mapping url-pattern='/DatabaseServlet/*'
                  filter-name='transaction-filter'/&gt;
&lt;/web-app&gt;
</example>

<p>
See <a href="javadoc|com.caucho.servlets.TransactionFilter|"/>.
</p>
</s1>

<s1 title="ExpiresFilter">

<p>The ExpiresFilter sets the Expires cache control header, allowing
servlet output and jsp results to be cached for a short time.</p>

<p>This is useful for indicating an Expires time to the browser, and it is even
more useful when used in conjunction with <a href="proxy-cache.xtp">Resin's HTTP proxy cache</a>.  If Resin's HTTP proxy cache is in use, even a short Expires time (like 2s) can result in performance gains.</p>

<deftable-parameters>
<tr><td>cache-time</td><td>The amount of time before the servlet output will be requested again. In seconds (2s), minutes (2m), hours (2h), or days (2D).</td><td>2s
</td></tr></deftable-parameters>

<example title="Caching stock quotes for 60 seconds">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;filter filter-name='expires-60s'
          filter-class='com.caucho.filters.ExpiresFilter'&gt;
    &lt;init&gt;
      &lt;cache-time&gt;60s&lt;/cache-time&gt;
    &lt;/init&gt;
  &lt;/filter&gt;

  &lt;filter-mapping servlet-name='StockQuoteServlet'
                  filter-name='expires-60s'/&gt;
&lt;/web-app&gt;
</example>

<p>In this example, the StockQuoteServlet will be only called once every 60
seconds.  This indicates to a browser that it should refresh it's local cache
of the url after 60 seconds have passed.  If Resin's HTTP proxy cache is being
used, the first request from any browser will cause execution of the
StockQuoteServlet, any requests from any browser for the next 60 seconds will
be served from the proxy cache (the servlet will not be called). </p>

<p>
See <a href="javadoc|com.caucho.servlets.ExpiresFilter|"/>.
</p>
</s1>

<s1 title="AnonymousExpiresFilter">

<p>The AnonymousExpiresFilter caches the response for anonymous users.  A user
is anonymous if the do not have a session.   When a page has custom formatting
for logged in users, it may still want to cache the results for non-logged in
users saving time and database access.</p>

<p>The benefits of using this filter are similar to those described in <a href="#ExpiresFilter">ExpiresFilter</a>.</p>

<deftable-parameters>
<tr><td>cache-time</td><td>The amount of time before the servlet output will be requested again. In seconds (2s), minutes (2m), hours (2h), or days (2D).</td><td>2s
</td></tr></deftable-parameters>

<p>Servlets should call <code>request.getSession(false)</code> to get their
sessions, because once a session is created the response will no longer be
cached.  For the same reason, JSP pages should set <code>&lt;jsp:directive.page
session='false'/&gt;</code> for all pages that do not need a session.</p>


<example title="Caching all anonymouse users *.jsp pages for 15 minutes">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;filter filter-name='anonymous-expires'
          filter-class='com.caucho.filters.AnonymousExpiresFilter'&gt;
    &lt;init&gt;
      &lt;cache-time&gt;15m&lt;/cache-time&gt;
    &lt;/init&gt;
  &lt;/filter&gt;

  &lt;filter-mapping url-pattern='*.jsp'
                  filter-name='anonymous-expires'/&gt;
&lt;/web-app&gt;
</example>

<p>
See <a href="javadoc|com.caucho.servlets.AnonymousExpiresFilter|"/>.
</p>
</s1>

<s1 title="RewriteFilter">

<p>The RewriteFilter rewrites and forwards URLs matching a
regular expression.  It is useful either when URLs change during a site
redesign or when a site might want to hide its JSP structure.  The
functionality is similar to mod_rewrite in the Apache web server.</p>

<p>The RewriteFilter is configured with a list of &lt;rewrite&gt; tags.  Each
tag has a <var>pattern</var> which matches against the URL and a <var>target</var>
which specifies the new URL to be forwarded to.  Multiple &lt;rewrite&gt; tags are allowed.</p>

<example title="RewriteFilter example">
&lt;filter filter-name='rewrite'
        filter-class='com.caucho.filters.RewriteFilter'&gt;
  &lt;init&gt;
    &lt;rewrite pattern="/a/([^/]*)/([^?]*)" target="/$2/$1.jsp"/&gt;
    &lt;rewrite pattern="/b/([^/]*)/([^?]*)" target="/$2/$1.html"/&gt;
  &lt;/init&gt;
&lt;/filter&gt;

&lt;filter-mapping url-pattern='/*' filter-name='rewrite'/&gt;
</example>

<p>
See <a href="javadoc|com.caucho.servlets.RewriteFilter|"/>.
</p>
</s1>
<!--
<section title='PasswordFilter'>

<p>Store a password that the user submits as the session attribute
<var/java.naming.security.credentials/>.  This is useful in situations where
the web application needs the user's password to authenticate with some backend
server, for example a mail server.</p>

<example title="PasswordFilter configuration">
&lt;filter  filter-name='password' 
         filter-class='com.caucho.filters.PasswordFilter'/&gt;

&lt;filter-mapping url-pattern='j_security_check'
                filter-name='password'/&gt;
</example>

<example title="Using the password stored by PasswordFilter">
String password = null;
if (request.getUserPrincipal() != null)
  password = request.getSession().getAttribute("java.naming.security.credentials");
</example>

See <a href="javadoc|com.caucho.servlets.PasswordFilter|"></a>.
</section>
-->

<s1 title="ThrottleFilter">

<p>
The ThrottleFilter filter implemented with 
<a href="javadoc|com.caucho.filters.ThrottleFilter|"/> restricts the number of
requests from the same IP, defaulting to 2 (the HTTP spec limit.) The
ThrottleFilter is useful to limit some parallel download programs
that can use more threads than they should.
</p>

<example>
&lt;filter filter-name="throttle"
        filter-class="com.caucho.filters.ThrottleFilter"&gt;
  &lt;init&gt;
    &lt;max-concurrent-requests&gt;2&lt;/max-concurrent-requests&gt;
  &lt;/init&gt;
&lt;/filter&gt;

&lt;filter-mapping url-pattern="/*" filter-name="throttle"/&gt;
</example>


</s1>

  </body>
</document>