net.sf.ehcache.constructs.web.filter
Class SimplePageCachingFilter

java.lang.Object
  net.sf.ehcache.constructs.web.filter.Filter
      net.sf.ehcache.constructs.web.filter.CachingFilter
          net.sf.ehcache.constructs.web.filter.SimplePageCachingFilter

All Implemented Interfaces:

javax.servlet.Filter

Direct Known Subclasses:

SimpleCachingHeadersPageCachingFilter, SimplePageCachingFilterWithBlankPageProblem

public class SimplePageCachingFilter
extends CachingFilter

A simple page CachingFilter suitable for most uses.

It uses a Singleton CacheManager created with the default factory method. Override to use a different CacheManager

The meaning of page is:

• A complete response i.e. not a fragment.
• A content type suitable for gzipping. e.g. text or text/html

For jsp:included page fragments see SimplePageFragmentCachingFilter.

calculateKey

Pages are cached based on their key. The key for this cache is the URI followed by the query string. An example is /admin/SomePage.jsp?id=1234&name=Beagle.

This key technique is suitable for a wide range of uses. It is independent of hostname and port number, so will work well in situations where there are multiple domains which get the same content, or where users access based on different port numbers.

A problem can occur with tracking software such as Google AdWords, where unique ids are inserted into request query strings. Because each request generates a unique key, there will never be a cache hit. For these situations it is better to override calculateKey(javax.servlet.http.HttpServletRequest) with an implementation that takes account of only the significant parameters.

Configuring the cacheName

A cache entry in ehcache.xml should be configured with the name of the filter.

Names can be set using the init-param cacheName, or by sub-classing this class and overriding the name.

Concurent Cache Misses

A cache miss will cause the filter chain, upstream of the caching filter to be processed. To avoid threads requesting the same key to do useless duplicate work, these threads block behind the first thread.

The thead timeout can be set to fail after a certain wait by setting the init-param blockingTimeoutMillis. By default threads wait indefinitely. In the event upstream processing never returns, eventually the web server may get overwhelmed with connections it has not responded to. By setting a timeout, the waiting threads will only block for the set time, and then throw a LockTimeoutException. Under either scenario an upstream failure will still cause a failure.

Gzipping

Significant network efficiencies can be gained by gzipping responses.

Whether a response can be gzipped depends on:

• Whether the user agent can accept GZIP encoding. This feature is part of HTTP1.1. If a browser accepts GZIP encoding it will advertise this by including in its HTTP header: All common browsers except IE 5.2 on Macintosh are capable of accepting gzip encoding. Most search engine robots do not accept gzip encoding.
• Whether the user agent has advertised its acceptance of gzip encoding. This is on a per request basis. If they will accept a gzip response to their request they must include the following in the HTTP request header: Accept-Encoding: gzip

Responses are automatically gzipped and stored that way in the cache. For requests which do not accept gzip encoding the page is retrieved from the cache, ungzipped and returned to the user agent. The ungzipping is high performance.

Caching Headers

This filter does not set browser caching headers such as ETag, Last-Modified, Expires, and If-None-Match. If you wish to minimise browser requests, use SimpleCachingHeadersPageCachingFilter.

Init-Params

The following init-params are supported:

1. cacheName - the name in ehcache.xml used by the filter.
2. blockingTimeoutMillis - the time, in milliseconds, to wait for the filter chain to return with a response on a cache miss. This is useful to fail fast in the event of an infrastructure failure.

Reentrance

Care should be taken not to define a filter chain such that the same CachingFilter class is reentered. The CachingFilter uses the BlockingCache. It blocks until the thread which did a get which results in a null does a put. If reentry happens a second get happens before the first put. The second get could wait indefinitely. This situation is monitored and if it happens, an IllegalStateException will be thrown.

Author:

Greg Luck

See Also:

SimpleCachingHeadersPageCachingFilter

Field Summary

static java.lang.String

DEFAULT_CACHE_NAME The name of the filter.

Fields inherited from class net.sf.ehcache.constructs.web.filter.CachingFilter

blockingCache, cacheName

Fields inherited from class net.sf.ehcache.constructs.web.filter.Filter

exceptionsToLogDifferently, filterConfig, NO_FILTER, suppressStackTraces

Constructor Summary

SimplePageCachingFilter()

Method Summary

protected java.lang.String	calculateKey(javax.servlet.http.HttpServletRequest httpRequest) Pages are cached based on their key.
protected net.sf.ehcache.CacheManager	getCacheManager() Gets the CacheManager for this CachingFilter.
protected java.lang.String	getCacheName() A meaningful name representative of the page being cached.

Methods inherited from class net.sf.ehcache.constructs.web.filter.CachingFilter

buildPage, buildPageInfo, checkNoReentry, doDestroy, doFilter, doInit, setCacheNameIfAnyConfigured, setContentType, setCookies, setHeaders, setStatus, writeContent, writeResponse

Methods inherited from class net.sf.ehcache.constructs.web.filter.Filter

acceptsEncoding, acceptsGzipEncoding, destroy, doFilter, filterNotDisabled, getFilterConfig, init, logRequestHeaders, processInitParams

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CACHE_NAME

public static final java.lang.String DEFAULT_CACHE_NAME

The name of the filter. This should match a cache name in ehcache.xml

See Also:

Constant Field Values

Constructor Detail

SimplePageCachingFilter

public SimplePageCachingFilter()

Method Detail

getCacheName

protected java.lang.String getCacheName()

A meaningful name representative of the page being cached.

The name must match the name of a configured cache in ehcache.xml

Overrides:

getCacheName in class CachingFilter

Returns:

the name of the cache to use for this filter.

getCacheManager

protected net.sf.ehcache.CacheManager getCacheManager()

Gets the CacheManager for this CachingFilter. It is therefore up to subclasses what CacheManager to use.

This method was introduced in ehcache 1.2.1. Older versions used a singleton CacheManager instance created with the default factory method.

Specified by:

getCacheManager in class CachingFilter

Returns:

the CacheManager to be used

Since:

1.2.1

calculateKey

protected java.lang.String calculateKey(javax.servlet.http.HttpServletRequest httpRequest)

Pages are cached based on their key. The key for this cache is the URI followed by the query string. An example is /admin/SomePage.jsp?id=1234&name=Beagle.

This key technique is suitable for a wide range of uses. It is independent of hostname and port number, so will work well in situations where there are multiple domains which get the same content, or where users access based on different port numbers.

A problem can occur with tracking software, where unique ids are inserted into request query strings. Because each request generates a unique key, there will never be a cache hit. For these situations it is better to parse the request parameters and override calculateKey(javax.servlet.http.HttpServletRequest) with an implementation that takes account of only the significant ones.

The key should be unique. Implementers should differentiate between GET and HEAD requests otherwise blank pages can result.

Specified by:

calculateKey in class CachingFilter

Parameters:

httpRequest -

Returns:

the key, generally the URI plus request parameters