org.apache.click.extras.cayenne
Class DataContextFilter

java.lang.Object
  org.apache.click.extras.cayenne.DataContextFilter

All Implemented Interfaces:

Filter

public class DataContextFilter
extends Object
implements Filter

Provides a servlet filter which binds DataContext objects to the current request thread and optionally the users HttpSession. This filter will automatically rollback any uncommitted changes at the end of each request.

When the click application is in debug or trace mode this filter will log any uncommitted data objects at the end of each request.

For units of work spanning multiple requests, such as a multi-page work flow, it is recommended that you add a separate DataContext to the session for the unit of work.

Session vs Request Scope

By default DataContext objects will be associated with the users HttpSession allowing objects to be cached in the users DataContext. Alternatively the filter can be configured to create a new DataContext object for each request.

Using session scope DataObjects is a good option for web applications which have exclusive access to the underlying database. However when web applications share a database you should probably disable this option by setting the session-scope init parameter to false.

Shared Cache

By default DataContext objects will be created which use the Cayenne shared cache. This is a good option for web applications which have exclusive access to the underlying database.

However when web applications which share a database you should probably disable this option by setting the shared-cache init parameter to false.

OSCache Enabled

This option enables you to specify whether OSCache should be used as the query cache for the DataDomain. By default OSCache is not enabled.

OSCache enables you to significantly increase the performance of your applications with in-memory query caching. OSCache provides fine grain control over query caching, expiry and supports clustered cache invalidation.

See Cayenne Query Result Caching for more details.

Lifecycle Listener

You can register a data domain LifecycleListener class to listen to persistent object lifecycle events. Please see the Cayenne Lifecycle Callbacks documentation for more details.

To configure a Lifecycle Listener simply specify the class name of the listener class as a filter init parameter. For example:

   <filter>
     <filter-name>DataContextFilter</filter-name>
     <filter-class>org.apache.click.extras.cayenne.DataContextFilter</filter-class>
     <init-param>
       <param-name>lifecycle-listener</param-name>
       <param-value>com.mycorp.service.AuditListener</param-value>
     </init-param>
   </filter> 

Configuration Examples

An example data context filter configuration in the web application's /WEB-INF/web.xml file is provided below. This example stores the DataContext in the users session and uses the Cayenne shared cache when creating DataContext objects.

This configuration is particularly useful when the web application is the only application making changes to the database.

 <web-app>

   <filter>
     <filter-name>DataContextFilter</filter-name>
     <filter-class>org.apache.click.extras.cayenne.DataContextFilter</filter-class>
   </filter>

   <filter-mapping>
     <filter-name>DataContextFilter</filter-name>
     <servlet-name>ClickServlet</servlet-name>
   </filter-mapping>

   <servlet>
     <servlet-name>ClickServlet</servlet-name>
     <servlet-class>org.apache.click.ClickServlet</servlet-class>
     ..

 </web-app> 

An example data context filter configuration in the web application's /WEB-INF/web.xml file is provided below. This example creates a new DataContext object for each request and does not use the Cayenne shared cache when creating DataContext objects.

This configuration is useful when multiple applications are making changes to the database.

 <web-app>

   <filter>
     <filter-name>DataContextFilter</filter-name>
     <filter-class>org.apache.click.extras.cayenne.DataContextFilter</filter-class>
     <init-param>
       <param-name>session-scope</param-name>
       <param-value>false</param-value>
     </init-param>
     <init-param>
       <param-name>shared-cache</param-name>
       <param-value>false</param-value>
     </init-param>
   </filter>

   <filter-mapping>
     <filter-name>DataContextFilter</filter-name>
     <servlet-name>ClickServlet</servlet-name>
   </filter-mapping>

   <servlet>
     <servlet-name>ClickServlet</servlet-name>
     <servlet-class>org.apache.click.ClickServlet</servlet-class>
     ..

 </web-app> 

Examples

Please see the Click Examples application for a demonstration of Cayenne integration.

This class is adapted from the Cayenne WebApplicationContextFilter.

Field Summary

protected boolean	autoRollback Automatically rollback any changes to the DataContext at the end of each request, the default value is true.
protected org.apache.cayenne.access.DataDomain	dataDomain The Cayenne DataDomain.
protected FilterConfig	filterConfig The filter configuration object we are associated with.
protected LogService	logger The Click log service.
protected boolean	sessionScope Maintain user DataContext object in their HttpSession, the default value is false.
protected Boolean	sharedCache Create DataContext objects using the shared cache.

Constructor Summary

DataContextFilter()

Method Summary

protected org.apache.cayenne.access.DataContext	createDataContext() Return a new DataContext instance using a shared cache if the filter is configured with use-shared-cache, otherwise the DataContext will not use a shared cache.
void	destroy() Destroy the DataContextFilter.
void	doFilter(ServletRequest request, ServletResponse response, FilterChain chain) This filter binds the session DataContext to the current thread, and removes the DataContext from the thread once the chained request has completed.
protected org.apache.cayenne.access.DataContext	getDataContext(HttpServletRequest request) Return a DataContext instance.
FilterConfig	getFilterConfig() Return filter config.
void	init(FilterConfig config) Initialize the shared Cayenne configuration.
void	setFilterConfig(FilterConfig filterConfig) Set filter configuration.

Methods inherited from class java.lang.Object

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

Field Detail

autoRollback

protected boolean autoRollback

Automatically rollback any changes to the DataContext at the end of each request, the default value is true.

This option is only useful for sessionScope DataObjects.

dataDomain

protected org.apache.cayenne.access.DataDomain dataDomain

The Cayenne DataDomain.

filterConfig

protected FilterConfig filterConfig

The filter configuration object we are associated with. If this value is null, this filter instance is not currently configured.

sessionScope

protected boolean sessionScope

Maintain user DataContext object in their HttpSession, the default value is false. If sessionScope is false then a new DataContext object will be created for each request.

sharedCache

protected Boolean sharedCache

Create DataContext objects using the shared cache.

logger

protected LogService logger

The Click log service.

Constructor Detail

DataContextFilter

public DataContextFilter()

Method Detail

init

public void init(FilterConfig config)

Initialize the shared Cayenne configuration. If the use-shared-cache init parameter is defined

Specified by:

init in interface Filter

Parameters:

config - the filter configuration

Throws:

RuntimeException - if an initialization error occurs

See Also:

Filter.init(FilterConfig)

destroy

public void destroy()

Destroy the DataContextFilter.

Specified by:

destroy in interface Filter

doFilter

public void doFilter(ServletRequest request,
                     ServletResponse response,
                     FilterChain chain)
              throws IOException,
                     ServletException

This filter binds the session DataContext to the current thread, and removes the DataContext from the thread once the chained request has completed.

Specified by:

doFilter in interface Filter

Parameters:

request - the servlet request

response - the servlet response

chain - the filter chain

Throws:

IOException - if an I/O error occurs

ServletException - if a servlet error occurs

setFilterConfig

public void setFilterConfig(FilterConfig filterConfig)

Set filter configuration. This function is equivalent to init and is required by Weblogic 6.1.

Parameters:

filterConfig - the filter configuration object

getFilterConfig

public FilterConfig getFilterConfig()

Return filter config. This is required by Weblogic 6.1

Returns:

the filter configuration

getDataContext

protected org.apache.cayenne.access.DataContext getDataContext(HttpServletRequest request)

Return a DataContext instance. If the DataContextFilter is configured to associate the DataContext with the session (which is the default behaviour), the DataContext will be bound to the users session. If the DataContext is already available, the existing DataContext will be used otherwise a new DataContext object will be created.

If this filter is configured with create-each-request to be true then a new DataContext will be created for each request and the DataContext will not be bound to the session.

Parameters:

request - the page request

Returns:

the DataContext object

createDataContext

protected org.apache.cayenne.access.DataContext createDataContext()

Return a new DataContext instance using a shared cache if the filter is configured with use-shared-cache, otherwise the DataContext will not use a shared cache.

Returns:

the DataContext object