Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

filters


Filter Configuration

Filter configuration follows the Servlet 3.0 deployment descriptors. Creating and using a filter has three steps:

  1. Create a filter class which extends javax.servlet.Filter
  2. Use <filter> in the web.xml to configure the filter.
  3. Use <filter-mapping> to select URLs and servlets for the filter.

filter

Defines a filter alias for later mapping.

TAGMEANING
filter-nameThe filter's name (alias)
filter-classThe filter's class (defaults to servlet-name)
init-paramInitialization parameters

The following example defines a filter alias 'image'

<web-app id='/'>

<filter-mapping url-pattern='/images/*'
                 filter-name='image'/>

<filter filter-name='image'
         filter-class='test.MyImage'>
  <init-param title='Hello, World'/>
</filter>

</web-app>

filter-name

Alias of the filter.

filter-class

Class of the filter. The CLASSPATH for filters includes the WEB-INF/classes directory and all jars in the WEB-INF/lib directory.

init-param

Initializes filter variables. filter-param defines initial values for getFilterConfig().getInitParameter("foo").

The full Servlet 3.0 syntax for init-param is supported and allows a simple shortcut

<web-app id='/'>

<filter filter-name='test.HelloWorld'>
  <init-param foo='bar'/>

  <init-param>
    <param-name>baz</param-name>
    <param-value>value</param-value>
  </init-param>
</filter>

</web-app>

filter-mapping

Maps url patterns to filters. filter-mapping has two children, url-pattern and filter-name. url-pattern selects the urls which should execute the filter.

filter-name can either specify a servlet class directly or it can specify a servlet alias defined by filter.

CONFIGURATIONDESCRIPTION
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
servlet-nameA servlet name to match.
filter-nameThe filter name
filter-classThe filter class
init-paramInitialization parameters
<caucho.com>
<web-app id='/'>

<servlet servlet-name='hello'
         servlet-class='test.HelloWorld'/>

<servlet-mapping url-pattern='/hello'
                 servlet-name='hello'/>

<filter filter-name='test-filter'
        filter-class='test.MyFilter'/>

<filter-mapping url-pattern='/hello/*'
                 filter-name='test-filter'/>

<filter-mapping servlet-name='hello'
                 filter-name='test.SecondFilter'/>

</web-app>

GzipFilter

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.

GzipFilter is available in Resin-Professional.

ATTRIBUTEDESCRIPTIONDEFAULT
use-varySet 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.true
no-cacheForbid 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.false
embed-error-in-outputEmbed the stack trace of any exception into the output stream that is being sent to the browser.false
<web-app xmlns="http://caucho.com/ns/resin">
  <filter filter-name="gzip"
          filter-class="com.caucho.filters.GzipFilter"/>

  <filter-mapping url-pattern="/*" filter-name="gzip"/>
</web-app>

See com.caucho.filters.GzipFilter.

XsltFilter

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

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

  <filter-mapping url-pattern="/*.jsp" filter-name="xslt"/>
</web-app>
ATTRIBUTEDESCRIPTIONDEFAULT
unconditionalalways do a transformation, regardless of the content type.false

See com.caucho.servlets.XsltFilter.

A request attribute or xml processing directive specifies the stylesheet

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

  1. The value of request.getAttribute("caucho.xsl.stylesheet")
  2. A stylesheet specified in the source document with <?xml-stylesheet href='...'?>
  3. default.xsl

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

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

  ...
</web-app>


WEB-INF/xsl/default.xsl

In a JSP the request attribute can be set with the following:

request attribute to indicate the stylesheet
<% request.setAttribute("caucho.xsl.stylesheet","transform.xsl"); %>

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

processing instruction to indicate the stylesheet
<?xml-stylesheet type="text/xsl" href="transform.xsl"?>

The stylesheet is applied only for certain content types

The filter by default will only transform responses that have a content type of one of the following:

  • x-application/xslt
  • x-application/xsl
  • x-application/stylescript

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

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

  <filter-mapping url-pattern='/xslt/*' filter-name='xslt'/>
</web-app>

TransactionFilter

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".

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

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

  <filter-mapping url-pattern='/DatabaseServlet/*'
                  filter-name='transaction-filter'/>
</web-app>

See com.caucho.servlets.TransactionFilter.

ExpiresFilter

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

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

ATTRIBUTEDESCRIPTIONDEFAULT
cache-timeThe amount of time before the servlet output will be requested again. In seconds (2s), minutes (2m), hours (2h), or days (2D).2s
Caching stock quotes for 60 seconds
<web-app xmlns="http://caucho.com/ns/resin">
  <filter filter-name='expires-60s'
          filter-class='com.caucho.filters.ExpiresFilter'>
    <init>
      <cache-time>60s</cache-time>
    </init>
  </filter>

  <filter-mapping servlet-name='StockQuoteServlet'
                  filter-name='expires-60s'/>
</web-app>

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).

See com.caucho.servlets.ExpiresFilter.

AnonymousExpiresFilter

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.

The benefits of using this filter are similar to those described in ExpiresFilter.

ATTRIBUTEDESCRIPTIONDEFAULT
cache-timeThe amount of time before the servlet output will be requested again. In seconds (2s), minutes (2m), hours (2h), or days (2D).2s

Servlets should call request.getSession(false) 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 <jsp:directive.page session='false'/> for all pages that do not need a session.

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

  <filter-mapping url-pattern='*.jsp'
                  filter-name='anonymous-expires'/>
</web-app>

See com.caucho.servlets.AnonymousExpiresFilter.

RewriteFilter

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.

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

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

<filter-mapping url-pattern='/*' filter-name='rewrite'/>

See com.caucho.servlets.RewriteFilter.

ThrottleFilter

The ThrottleFilter filter 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.

ATTRIBUTEDESCRIPTIONDEFAULT
max-concurrent-requestsmaximum number of concurrent requests allowed per IP2
max-total-requestsmaximum number of requests allowed per IP within timeoutunlimited
timeoutinterval for max-total-requests120s
delaydelay to add to the beginning of every request0
poisoned-ipimmediately send a HTTP/503 error response back to this client
<filter filter-name="throttle"
        filter-class="com.caucho.filters.ThrottleFilter">
  <init>
    <max-concurrent-requests>2</max-concurrent-requests>
  </init>
</filter>

<filter-mapping url-pattern="/*" filter-name="throttle"/>

See com.caucho.filters.ThrottleFilter.


Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.