<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
    <header>
        <title>NetUI Control Container</title>
    </header>
    <body>
        <section id="introduction">
            <title>Introduction</title>
            <p> This document describes how the NetUI page flow runtime implements the container for hosting
	    controls.  Controls run within a runtime container which provides services to controls.  Within the page flow
	    runtime, the <a href="../apidocs/classref_controls/org/apache/beehive/controls/api/context/ControlBeanContext.html">
	    org.apache.beehive.controls.api.context.ControlBeanContext</a> is the base class that provides the extended
	    services to contained controls.  The container is managed by the page flow runtime.  This document describes the
	    details of the contract that is maintained for controls hosted in page flows by the implementation.
	    </p>
        </section>
        <section id="Description">
            <title>Description of the Control Container</title>
	    <p>This section describes the implementation of the Control container within the page flow runtime.
	    </p>
	    <section>
	    <title>Scope of the Control</title>
            <p> There are three scopes that the control container implementation provides for controls.  The first is
	    at the page flow level.  Each page flow, <code>PageFlowController</code>, provides its own
	    <code>ControlBeanContext</code> to the controls which are defined within the scope of that page flow.  The
	    second scope is the shared flows, <code>SharedFlowController</code>.  All shared flows and the
	    <code>GlobalApp</code>  share a single <code>ControlBeanContext</code>.  The final scope is for JSF Backing
	    Beans, <code>FacesBackingBean</code>.  Just as with page flows, faces backing beans have a
	    <code>ControlBeanContext</code> that is scoped to their life time.  The result is that the
	    <code>ControlBeanContext</code> containing controls has the same lifetime as the object that defines
	    and uses the control instances.  
            </p>
	    </section>
	    <section>
	    <title>Single Threaded Page Flow Code</title>
	    <p> There are three places in the handling of a request where page flow code provides synchronization of multiple
	    threads.  Page flows and shared flows are scoped into a <code>ServletSession</code>.  It is possible to have
	    multiple threads running.  This can happen if you have multiple browser windows sharing a session, or if you have
	    multiple requests from a single page containing frames.
	    Multiple requests can be generated through HTML frames or AJAX calls.  The
	    page flow runtime insures that multiple threads are not executing code inside of a page flow.  A shared flow can
	    potentially have multiple threads running through it which will be described below.
	    </p>
	    <p>
	    There are three synchronization points in the page flow runtime:
	    </p>
	    <ul>
	    <li><em>onCreate</em> -- The <code>onCreate</code> event is synchronized and only one thread will ever pass through
	    this method during the life of the page flow.
	    </li>
	    <li><em>beforeAction / action / afterAction</em> -- These three methods are run in a single synchronization block meaning
	    these method will run together within one thread, without another thread running through the page flow.  
	    </li>
	    <li><em>JSP Rendering</em> -- The page flow runtime synchronizes on the current page flow during JSP rendering.  This
	    prevents a thread from running and action on a page flow while another thread is rendering a JSP which may be
	    accessing page flow state.
	    </li>
	    </ul>
	    <p>  Each of these synchronization points will run the resource events on the controls contained inside
	    of the container.  This will cause the <code>onAcquire</code> and <code>onRelease</code> resources events
	    to be triggered on all of the controls within the container.  These events will be run on the current page
	    flow and also the shared flow.  In reality, the <code>onAcquire</code> method is run before the first
	    method invocation is done on a control.  <code>onRelease</code> will only be run if the <code>onAcquire</code>
	    mehtod has been run.  The shared flow <code>ControlBeanContext</code> has a lock associated with it that
	    must be obtained before user code can be run.
	    </p>
	    <p> The synchronization point result in the following, all access to a control is single threaded.  If a
	    control acquires a resource such as a JDBC connection, it will only be used for a single request.  This model
	    also ensures that shared flows are accessed in a single threaded model when there is an instance of a control
	    in any shared flow because of the lock associated with the shared flow <code>ControlBeanContext</code>.
	    Finally, if there is a shared flow <code>ControlBeanContext</code> we will serialize all threads within a session
	    when they run through user code.  This ensures a single threaded model for controls defined in shared flows.
	    </p>
	    </section>
	    <section>
	    <title>Programatic Creation of Controls</title>
	    <p> The ControlBeanContext is lazily created when possible.  When a page flow is created, the page flow is searched
	    for fields with <code>@control</code> annotations.  If any of these are found, the <code>ControlBeanContext</code>
	    is created.  The shared flow <code>ControlBeanContext</code> is created when the first shared flow containing a
	    control annotation is created.
	    </p>
	    <p> For page flows that want to create a control programmatically using <code>java.beans.Beans.instantiate</code>,
	    you must ensure that the context has been created.  The following two lines of code will create the
	    <code>ControlBeanContext</code> and make sure the <code>beginContext</code> method is called correctly.
	    </p>
	    <source>
PageFlowControlContainer pfcc =
    PageFlowControlContainerFactory.getControlContainer(getRequest(),getServletContext());
pfcc.createAndBeginControlBeanContext(this,getRequest(),getResponse(),getServletContext());
	   </source>
           </section>
        </section>
    </body>
    <footer>
        <legal>
            Java, J2EE, and JCP are trademarks or registered trademarks
            of Sun Microsystems, Inc. in the United States and other
            countries.
            <br />
            &copy; 2006, Apache Software Foundation
        </legal>
    </footer>
</document>
