com.opensymphony.oscache.web.filter
Class CacheFilter

java.lang.Object
  extended by com.opensymphony.oscache.web.filter.CacheFilter
All Implemented Interfaces:
ICacheGroupsProvider, ICacheKeyProvider, Filter

public class CacheFilter
extends Object
implements Filter, ICacheKeyProvider, ICacheGroupsProvider

CacheFilter is a filter that allows for server-side caching of post-processed servlet content.

It also gives great programatic control over refreshing, flushing and updating the cache.

Version:
$Revision: 434 $
Author:
Serge Knystautas, Mike Cannon-Brookes, Lars Torunski

Field Summary
static long EXPIRES_OFF
           
static long EXPIRES_ON
           
static long EXPIRES_TIME
           
static int FRAGMENT_AUTODETECT
           
static int FRAGMENT_NO
           
static int FRAGMENT_YES
           
static String HEADER_ACCEPT_ENCODING
           
static String HEADER_CACHE_CONTROL
           
static String HEADER_CONTENT_ENCODING
           
static String HEADER_CONTENT_TYPE
           
static String HEADER_EXPIRES
           
static String HEADER_IF_MODIFIED_SINCE
           
static String HEADER_LAST_MODIFIED
           
static long LAST_MODIFIED_INITIAL
           
static long LAST_MODIFIED_OFF
           
static long LAST_MODIFIED_ON
           
static long MAX_AGE_NO_INIT
           
static long MAX_AGE_TIME
           
static int NOCACHE_OFF
           
static int NOCACHE_SESSION_ID_IN_URL
           
 
Constructor Summary
CacheFilter()
           
 
Method Summary
 boolean acceptsGZipEncoding(HttpServletRequest request)
          Check if the client browser support gzip compression.
 String[] createCacheGroups(HttpServletRequest httpRequest, ServletCacheAdministrator scAdmin, Cache cache)
          ICacheGroupsProvider
 String createCacheKey(HttpServletRequest httpRequest, ServletCacheAdministrator scAdmin, Cache cache)
          ICacheKeyProvider
 void destroy()
          Filter clean-up
 void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
          The doFilter call caches the response by wrapping the HttpServletResponse object so that the output stream can be caught.
 long getCacheControlMaxAge()
           
 ICacheGroupsProvider getCacheGroupsProvider()
           
 ICacheKeyProvider getCacheKeyProvider()
           
 int getCacheScope()
          Returns PageContext.APPLICATION_SCOPE or PageContext.SESSION_SCOPE.
 String getCron()
           
 List getDisableCacheOnMethods()
           
 long getExpires()
           
 EntryRefreshPolicy getExpiresRefreshPolicy()
           
 int getFragment()
           
 long getLastModified()
           
 int getNocache()
           
 int getTime()
           
 void init(FilterConfig filterConfig)
          Initialize the filter.
 boolean isCacheable(CacheHttpServletResponseWrapper cacheResponse)
          isCacheable is a method allowing subclass to decide if a response is cachable or not.
 boolean isCacheable(ServletRequest request)
          isCacheable is a method allowing a subclass to decide if a request is cachable or not.
 boolean isFilteredBefore(ServletRequest request)
          Checks if the request was filtered before, so guarantees to be executed once per request.
 boolean isFragment(HttpServletRequest request)
          Checks if the request is a fragment in a page.
 void setCacheControlMaxAge(long cacheControlMaxAge)
          max-age - defines the cache control response header max-age.
 void setCacheGroupsProvider(ICacheGroupsProvider cacheGroupsProvider)
          ICacheGroupsProvider - Class implementing the interface ICacheGroupsProvider.
 void setCacheKeyProvider(ICacheKeyProvider cacheKeyProvider)
          ICacheKeyProvider - Class implementing the interface ICacheKeyProvider.
 void setCacheScope(int cacheScope)
          scope - the default scope to cache content.
 void setCron(String cron)
          cron - defines an expression that determines when the page content will expire.
 void setDisableCacheOnMethods(List disableCacheOnMethods)
          disableCacheOnMethods - Defines the http method name for which cacheing should be disabled.
 void setExpires(long expires)
          expires - defines if the expires header will be sent in the response.
 void setExpiresRefreshPolicy(EntryRefreshPolicy expiresRefreshPolicy)
          EntryRefreshPolicy - Class implementing the interface EntryRefreshPolicy.
 void setFragment(int fragment)
          fragment - defines if this filter handles fragments of a page.
 void setLastModified(long lastModified)
          lastModified - defines if the last modified header will be sent in the response.
 void setNocache(int nocache)
          nocache - defines which objects shouldn't be cached.
 void setTime(int time)
          time - the default time (in seconds) to cache content for.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HEADER_LAST_MODIFIED

public static final String HEADER_LAST_MODIFIED
See Also:
Constant Field Values

HEADER_CONTENT_TYPE

public static final String HEADER_CONTENT_TYPE
See Also:
Constant Field Values

HEADER_CONTENT_ENCODING

public static final String HEADER_CONTENT_ENCODING
See Also:
Constant Field Values

HEADER_EXPIRES

public static final String HEADER_EXPIRES
See Also:
Constant Field Values

HEADER_IF_MODIFIED_SINCE

public static final String HEADER_IF_MODIFIED_SINCE
See Also:
Constant Field Values

HEADER_CACHE_CONTROL

public static final String HEADER_CACHE_CONTROL
See Also:
Constant Field Values

HEADER_ACCEPT_ENCODING

public static final String HEADER_ACCEPT_ENCODING
See Also:
Constant Field Values

FRAGMENT_AUTODETECT

public static final int FRAGMENT_AUTODETECT
See Also:
Constant Field Values

FRAGMENT_NO

public static final int FRAGMENT_NO
See Also:
Constant Field Values

FRAGMENT_YES

public static final int FRAGMENT_YES
See Also:
Constant Field Values

NOCACHE_OFF

public static final int NOCACHE_OFF
See Also:
Constant Field Values

NOCACHE_SESSION_ID_IN_URL

public static final int NOCACHE_SESSION_ID_IN_URL
See Also:
Constant Field Values

LAST_MODIFIED_OFF

public static final long LAST_MODIFIED_OFF
See Also:
Constant Field Values

LAST_MODIFIED_ON

public static final long LAST_MODIFIED_ON
See Also:
Constant Field Values

LAST_MODIFIED_INITIAL

public static final long LAST_MODIFIED_INITIAL
See Also:
Constant Field Values

EXPIRES_OFF

public static final long EXPIRES_OFF
See Also:
Constant Field Values

EXPIRES_ON

public static final long EXPIRES_ON
See Also:
Constant Field Values

EXPIRES_TIME

public static final long EXPIRES_TIME
See Also:
Constant Field Values

MAX_AGE_NO_INIT

public static final long MAX_AGE_NO_INIT
See Also:
Constant Field Values

MAX_AGE_TIME

public static final long MAX_AGE_TIME
See Also:
Constant Field Values
Constructor Detail

CacheFilter

public CacheFilter()
Method Detail

destroy

public void destroy()
Filter clean-up

Specified by:
destroy in interface Filter

doFilter

public void doFilter(ServletRequest request,
                     ServletResponse response,
                     FilterChain chain)
              throws ServletException,
                     IOException
The doFilter call caches the response by wrapping the HttpServletResponse object so that the output stream can be caught. This works by splitting off the output stream into two with the SplitServletOutputStream class. One stream gets written out to the response as normal, the other is fed into a byte array inside a ResponseContent object.

Specified by:
doFilter in interface Filter
Parameters:
request - The servlet request
response - The servlet response
chain - The filter chain
Throws:
ServletException - IOException
IOException

init

public void init(FilterConfig filterConfig)
Initialize the filter. This retrieves a ServletCacheAdministrator instance and configures the filter based on any initialization parameters.

The supported initialization parameters are:


createCacheKey

public String createCacheKey(HttpServletRequest httpRequest,
                             ServletCacheAdministrator scAdmin,
                             Cache cache)
ICacheKeyProvider

Specified by:
createCacheKey in interface ICacheKeyProvider
Parameters:
httpRequest - the http request.
scAdmin - the ServletCacheAdministrator of the cache
cache - the cache of the ServletCacheAdministrator
Returns:
the cache key
See Also:
ICacheKeyProvider.createCacheKey(javax.servlet.http.HttpServletRequest, ServletCacheAdministrator, Cache)

createCacheGroups

public String[] createCacheGroups(HttpServletRequest httpRequest,
                                  ServletCacheAdministrator scAdmin,
                                  Cache cache)
ICacheGroupsProvider

Specified by:
createCacheGroups in interface ICacheGroupsProvider
Parameters:
httpRequest - the http request.
scAdmin - the ServletCacheAdministrator of the cache
cache - the cache of the ServletCacheAdministrator
Returns:
the cache key
See Also:
ICacheGroupsProvider.createCacheGroups(javax.servlet.http.HttpServletRequest, ServletCacheAdministrator, Cache)

isFragment

public boolean isFragment(HttpServletRequest request)
Checks if the request is a fragment in a page. According to Java Servlet API 2.2 (8.2.1 Dispatching Requests, Included Request Parameters), when a servlet is being used from within an include, the attribute javax.servlet.include.request_uri is set. According to Java Servlet API 2.3 this is excepted for servlets obtained by using the getNamedDispatcher method.

Parameters:
request - the to be handled request
Returns:
true if the request is a fragment in a page

isFilteredBefore

public boolean isFilteredBefore(ServletRequest request)
Checks if the request was filtered before, so guarantees to be executed once per request. You can override this methods to define a more specific behaviour.

Parameters:
request - checks if the request was filtered before.
Returns:
true if it is the first execution

isCacheable

public boolean isCacheable(ServletRequest request)
isCacheable is a method allowing a subclass to decide if a request is cachable or not.

Parameters:
request - The servlet request
Returns:
Returns a boolean indicating if the request can be cached or not.

isCacheable

public boolean isCacheable(CacheHttpServletResponseWrapper cacheResponse)
isCacheable is a method allowing subclass to decide if a response is cachable or not.

Parameters:
cacheResponse - the HTTP servlet response
Returns:
Returns a boolean indicating if the response can be cached or not.

acceptsGZipEncoding

public boolean acceptsGZipEncoding(HttpServletRequest request)
Check if the client browser support gzip compression.

Parameters:
request - the http request
Returns:
true if client browser supports GZIP

getCacheControlMaxAge

public long getCacheControlMaxAge()
Returns:
the max-age of the cache control
Since:
2.4

setCacheControlMaxAge

public void setCacheControlMaxAge(long cacheControlMaxAge)
max-age - defines the cache control response header max-age. Acceptable values are MAX_AGE_NO_INIT for don't initializing the max-age cache control, MAX_AGE_TIME the max-age information will be based on the time parameter and creation time of the content (expiration timestamp minus current timestamp), and [positive integer] value constant in seconds to be set in every response, the default value is 60.

Parameters:
cacheControlMaxAge - the cacheControlMaxAge to set
Since:
2.4

getCacheGroupsProvider

public ICacheGroupsProvider getCacheGroupsProvider()
Returns:
the cacheGroupsProvider
Since:
2.4

setCacheGroupsProvider

public void setCacheGroupsProvider(ICacheGroupsProvider cacheGroupsProvider)
ICacheGroupsProvider - Class implementing the interface ICacheGroupsProvider. A developer can implement a method which provides cache groups based on the request, the servlect cache administrator and cache. The parameter has to be not null.

Parameters:
cacheGroupsProvider - the cacheGroupsProvider to set
Since:
2.4

getCacheKeyProvider

public ICacheKeyProvider getCacheKeyProvider()
Returns:
the cacheKeyProvider
Since:
2.4

setCacheKeyProvider

public void setCacheKeyProvider(ICacheKeyProvider cacheKeyProvider)
ICacheKeyProvider - Class implementing the interface ICacheKeyProvider. A developer can implement a method which provides cache keys based on the request, the servlect cache administrator and cache. The parameter has to be not null.

Parameters:
cacheKeyProvider - the cacheKeyProvider to set
Since:
2.4

getCacheScope

public int getCacheScope()
Returns PageContext.APPLICATION_SCOPE or PageContext.SESSION_SCOPE.

Returns:
the cache scope
Since:
2.4

setCacheScope

public void setCacheScope(int cacheScope)
scope - the default scope to cache content. Acceptable values are PageContext.APPLICATION_SCOPE (default) and PageContext.SESSION_SCOPE.

Parameters:
cacheScope - the cacheScope to set
Since:
2.4

getCron

public String getCron()
Returns:
the cron
Since:
2.4

setCron

public void setCron(String cron)
cron - defines an expression that determines when the page content will expire. This allows content to be expired at particular dates and/or times, rather than once a cache entry reaches a certain age.

Parameters:
cron - the cron to set
Since:
2.4

getExpires

public long getExpires()
Returns:
the expires header
Since:
2.4

setExpires

public void setExpires(long expires)
expires - defines if the expires header will be sent in the response. Acceptable values are EXPIRES_OFF for don't sending the header, even it is set in the filter chain, EXPIRES_ON (default) for sending it if it is set in the filter chain and EXPIRES_TIME the expires information will be intialized based on the time parameter and creation time of the content.

Parameters:
expires - the expires to set
Since:
2.4

getExpiresRefreshPolicy

public EntryRefreshPolicy getExpiresRefreshPolicy()
Returns:
the expiresRefreshPolicy
Since:
2.4

setExpiresRefreshPolicy

public void setExpiresRefreshPolicy(EntryRefreshPolicy expiresRefreshPolicy)
EntryRefreshPolicy - Class implementing the interface EntryRefreshPolicy. A developer can implement a class which provides a different custom cache invalidation policy for a specific cache entry. If not specified, the default policy is timed entry expiry as specified with the time parameter described above.

Parameters:
expiresRefreshPolicy - the expiresRefreshPolicy to set
Since:
2.4

getFragment

public int getFragment()
Returns:
the fragment
Since:
2.4

setFragment

public void setFragment(int fragment)
fragment - defines if this filter handles fragments of a page. Acceptable values are FRAGMENT_AUTODETECT (default) for auto detect, FRAGMENT_NO and FRAGMENT_YES.

Parameters:
fragment - the fragment to set
Since:
2.4

getLastModified

public long getLastModified()
Returns:
the lastModified
Since:
2.4

setLastModified

public void setLastModified(long lastModified)
lastModified - defines if the last modified header will be sent in the response. Acceptable values are LAST_MODIFIED_OFF for don't sending the header, even it is set in the filter chain, LAST_MODIFIED_ON for sending it if it is set in the filter chain and LAST_MODIFIED_INITIAL (default) the last modified information will be set based on the current time and changes are allowed.

Parameters:
lastModified - the lastModified to set
Since:
2.4

getNocache

public int getNocache()
Returns:
the nocache
Since:
2.4

setNocache

public void setNocache(int nocache)
nocache - defines which objects shouldn't be cached. Acceptable values are NOCACHE_OFF (default) and NOCACHE_SESSION_ID_IN_URL if the session id is contained in the URL.

Parameters:
nocache - the nocache to set
Since:
2.4

getTime

public int getTime()
Returns:
the time
Since:
2.4

setTime

public void setTime(int time)
time - the default time (in seconds) to cache content for. The default value is 3600 seconds (one hour). Specifying -1 (indefinite expiry) as the cache time will ensure a content does not become stale until it is either explicitly flushed or the expires refresh policy causes the entry to expire.

Parameters:
time - the time to set
Since:
2.4

getDisableCacheOnMethods

public List getDisableCacheOnMethods()
Returns:
the list of http method names for which cacheing should be disabled
Since:
2.4

setDisableCacheOnMethods

public void setDisableCacheOnMethods(List disableCacheOnMethods)
disableCacheOnMethods - Defines the http method name for which cacheing should be disabled. The default value is null for cacheing all requests without regarding the method name.

Parameters:
disableCacheOnMethods - the list of http method names for which cacheing should be disabled
Since:
2.4

OSCache Project Page