net.sf.click.extras.cayenne
Class DataContextFilter

java.lang.Object
  extended bynet.sf.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 request. This filter will automatically rollback any uncommitted changes at which binds the user's session scope DataContext to the current thread. 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.

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>data-context-filter</filter-name>
     <filter-class>net.sf.click.extras.cayenne.DataContextFilter</filter-class>
   </filter>

   <filter-mapping>
     <filter-name>data-context-filter</filter-name>
     <servlet-name>click-servlet</servlet-name>
   </filter-mapping>

   <servlet>
     <servlet-name>click-servlet</servlet-name>
     ..

 </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>data-context-filter</filter-name>
     <filter-class>net.sf.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>data-context-filter</filter-name>
     <servlet-name>click-servlet</servlet-name>
   </filter-mapping>

   <servlet>
     <servlet-name>click-servlet</servlet-name>
     ..

 </web-app> 

Examples

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

This class is adapted from the Cayenne WebApplicationContextFilter.

Author:
Malcolm Edgar

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.log4j.Logger logger
          The DataContextFilter logger.
protected  boolean sessionScope
          Maintain user HttpSession scope DataContext object, the default value is true.
protected  boolean sharedCache
          Create DataContext objects using the shared cache.
 
Constructor Summary
DataContextFilter()
           
 
Method Summary
 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.
 void init(FilterConfig config)
          Initialize the shared Cayenne 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.


sessionScope

protected boolean sessionScope
Maintain user HttpSession scope DataContext object, the default value is true. 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 org.apache.log4j.Logger logger
The DataContextFilter logger.

Constructor Detail

DataContextFilter

public DataContextFilter()
Method Detail

init

public void init(FilterConfig config)
          throws ServletException
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:
ServletException - 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

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

If this filter is configured with use-shared-cache to be true (which is the default behaviour) this method will create DataContext objects using the Cayenne shared cache, otherwise they will not use the shared cache.

Parameters:
request - the page request
Returns:
the DataContext object