Orchestra dokumentation [was Re: svn commit: r567017 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/filter/OrchestraServletFilter.java]

[Mario Ivankovits <ma...@ops.co.at>]

Hi Simon!

Thanks for all the hard work you put into documentation and cleanup of
the Orchestra API.
This really brings the project even further!

Have a nice Weekend!

Ciao,
Mario


skitching@apache.org schrieb:
> Author: skitching
> Date: Fri Aug 17 04:19:22 2007
> New Revision: 567017
>
> URL: http://svn.apache.org/viewvc?view=rev&rev=567017
> Log:
> Add javadoc only.
>
> Modified:
>     myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/filter/OrchestraServletFilter.java
>
> Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/filter/OrchestraServletFilter.java
> URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/filter/OrchestraServletFilter.java?view=diff&rev=567017&r1=567016&r2=567017
> ==============================================================================
> --- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/filter/OrchestraServletFilter.java (original)
> +++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/filter/OrchestraServletFilter.java Fri Aug 17 04:19:22 2007
> @@ -33,14 +33,46 @@
>  import javax.servlet.http.HttpServletResponse;
>  import java.io.IOException;
>  
> +/**
> + * Ensures that only one request per conversationContext can be processed at a time,
> + * and also ensure all JDBC connections are returned to the pool.
> + * <p>
> + * <h2>Request Synchronization</h2>
> + * It is possible for multiple requests associated with the same http session to be
> + * received concurrently. In particular, ajax pages can cause this.
> + * <p> 
> + * By default, the servlet engine simply processes all requests concurrently
> + * in different threads. However that can cause all sorts of unexpected problems with 
> + * session-scoped objects.
> + * <p>
> + * The usual solution is to apply a filter to all requests which uses standard java
> + * synchronisation on a session-scoped object, taking the lock on request entry and
> + * releasing it on request exit. This ensures that only one request for that session
> + * runs at a time, with the others waiting until they can obtain a lock on the
> + * appropriate object.
> + * <p>
> + * When using an Orchestra conversationContext, session-scoped data should be avoided and
> + * conversation-scoped beans used instead. If there is no session-scoped data in use by
> + * an application then it is possible to allow concurrent requests to the same http session,
> + * but NOT concurrent access to the same orchestra conversationContext. This filter 
> + * implements that, by holding a lock on a mutex object held by the appropriate
> + * conversationContext.
> + * <p>
> + * This filter can be enabled or disabled via a filter init parameter; setting
> + * "serializeRequests" to "false" disables this filter. Default value: true (enabled).
> + * <p>
> + * <h2>JDBC Connection Management</h2>
> + * Orchestra provides a special DataSource wrapper that can be configured for any
> + * datasource used by the application. The datasource simply wraps all real Connection
> + * objects it returns in a proxy, and keeps track of them. Here in this servlet it
> + * checks whether all connections borrowed by this thread have been returned, and if
> + * not returns the real connection nulls out the connection held by the proxy. See
> + * ConnectionManagerDataSource for more details.
> + */
>  public class OrchestraServletFilter implements Filter
>  {
>  	/**
> -	 * true|false
> -	 * Allows to configure if Orchestra should serialize each request against the conversationContext.
> -	 * This means, that e.g. if multiple threads (in an ajax environment) concurrently access the
> -	 * conversationContext would not bother each other.
> -	 * Default: true
> +	 * This filter init property can be set to "true" or "false". Default: "true".
>  	 */
>  	public final static String SERIALIZE_REQUESTS = "serializeRequests"; // NON-NLS
>  	private final static String CONTEXT_MUTEXT_OBJECT = OrchestraServletFilter.class.getName() + ".SER_MUTEX";
>
>
>