<?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 State Management and Lifecycle</title>
	</header>
	<body>
		<section id="intro">
			<title>Introduction</title>

            <section id="stateManagement">
                <title>State Management</title>
                <section id="pageFlowStateManagement">
                    <title>Page Flow State Management</title>
                    <p>
                        When you hit the URL for a page flow (or any of its actions, or any of its pages) for the first
                        time, an instance of the controller class is created and stored in the user session. By default,
                        it stays in the session as the <em>current page flow</em> until you hit another page flow.  
                        This means that while you continue to hit URLs in the page flow's URL space, it
                        remains the current page flow.  When you do hit another page flow, the original controller
                        instance is destroyed. In other words, by default there is only a <em>single page flow
                        controller</em> stored in the session at one time.
                    </p>
                    <note>
                        <a href="site:docs/pageflow/netuiBasic/nestedPageFlow">Nested page flows</a> have special rules
                        associated with them: when you hit a nested page flow, the current page flow is pushed aside,
                        and it is restored when you return from the nested page flow. You can also <em>abnormally
                        exit</em> a nested page flow by hitting a "regular" (non-nested) page flow while you're still
                        in the nested flow. In that case, the original page flow (the one that was pushed aside) is
                        discarded.
                    </note>
                    <p>
                        The auto-cleanup of a controller instance is normally helpful in keeping your session small and
                        focused on the task at hand. In some cases, you may want to create a "long-lived" page flow
                        controller that <em>never</em> gets destroyed (until the session itself ends). In this case,
                        you simply set the
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html#longLived()">
                            <code>longLived</code>
                        </a>
                        attribute to <code>true</code> on
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
                            <code>@Jpf.Controller</code></a>:
                    </p>
                    <source>
@Jpf.Controller(longLived=true)
public class MyLongLivedPageFlow extends PageFlowController
{
    ...
}                   </source>
                    <p>
                        Now, whenever this page flow is hit for the first time, it is stored in the session, and is not
                        removed even when another page flow becomes the current page flow. Each time you hit the URL for
                        this page flow (or any of its actions, or any of its pages), the <em>same instance</em> is
                        restored.
                    </p>
                    <p>
                        You can remove this long-lived controller instance explicitly by calling its
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/FlowController.html#remove()">
                            <code>remove()</code>
                        </a>
                        method.
                    </p>
                </section>
                <section id="sharedFlowStateManagement">
                    <title>Shared Flow State Management</title>
                    <p>
                        Whenever you hit a page flow, each of its referenced
                        <a href="site:docs/pageflow/pageflow_advanced/pageflow_sharedFlow">shared flow controllers</a>
                        is created and stored in the session.  If a shared flow controller of the right type already
                        exists in the session, that instance is used instead.  Once one is created, it is not removed
                        unless you call its
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/FlowController.html#remove()">
                            <code>remove()</code>
                        </a>
                        method, or
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/PageFlowUtils.html#removeSharedFlow(java.lang.String, javax.servlet.http.HttpServletRequest, javax.servlet.ServletContext)">
                            <code>PageFlowUtils.removeSharedFlow()</code></a>.
                    </p>
                </section>
                <section id="jsfBackingBeanStateManagement">
                    <title>State Management for JavaServer Faces "Backing Beans"</title>
                    <p>
                        When you hit a JSF page (e.g., "/mydir/mypage.faces"), the NetUI runtime looks for a class 
                        with the same name and package (e.g., <code>mydir.mypage</code>). If this class exists, is
                        annotated with
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.FacesBacking.html">
                            <code>@Jpf.FacesBacking</code></a>, and extends
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/FacesBackingBean.html">
                            <code>FacesBackingBean</code></a>, then an instance is created and stored in the session.
                        It is removed from the session on the next request that is not for the same page.
                    </p>
                    <p>
                        See <a href="site:docs/pageflow/netuiBasic/pageflow_jsf">Java Server Faces</a> for more details on JSF
                        integration with NetUI.
                    </p>
                </section>
            </section>

            <section id="lifecycle">
                <title>Lifecycle</title>
                <p>
                    All NetUI-managed objects (page flow controllers, shared flow controllers, JavaServer Faces
                    "backing beans") are driven through a lifecycle, with callbacks in the appropriate places.
                    This lifecycle always includes:
                </p>
                <ul>
                    <li>
                        <strong><code>onCreate</code></strong> - when the object is created by the runtime.
                    </li>
                    <li>
                        <strong><code>onDestroy</code></strong> - when the object is "destroyed" (removed) by the
                        runtime.
                    </li>
                </ul>
                <p>
                    To run code at either of these points in the lifecycle, you simply override the appropriate method
                    (<a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/PageFlowManagedObject.html#onCreate()"><code>onCreate</code></a>
                    or
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/PageFlowManagedObject.html#onDestroy(javax.servlet.http.HttpSession)"><code>onDestroy</code></a>), e.g.,
                </p>
                <source>
@Jpf.Controller
public class MyPageFlow extends PageFlowController
{
    protected void onCreate()
    {
        // do something to initialize this page flow controller
    }

    ...
}               </source>
                <section id="controllerLifecycle">
                    <title>Controller Lifecycle</title>
                    <p>
                        Flow controllers (page flow controllers and shared flow controllers) have additional methods as
                        part of their lifecycle:
                    </p>
                    <ul>
                        <li>
                            <strong> 
                                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/FlowController.html#beforeAction()">
                                    <code>beforeAction</code>
                                </a>
                            </strong>
                            - before any action is run.
                        </li>
                        <li>
                            <strong> 
                                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/FlowController.html#afterAction()">
                                    <code>afterAction</code>
                                </a>
                            </strong>
                            - after any action is run.
                        </li>
                    </ul>
                    <p>
                        Again, to run code at either of these points, override the appropriate method, e.g.,
                    </p>
                    <source>
@Jpf.Controller
public class MyPageFlow extends PageFlowController
{
    protected void beforeAction()
    {
        log.debug("before action " + getCurrentActionName() + ", request " + getRequest().getRequestURI());
    }

    ...
}                   </source>
                    <p>
                        Additionally, <a href="site:docs/pageflow/netuiBasic/nestedPageFlow">nested page flows</a> have
                        an additional lifecycle method:
                    </p>
                    <ul>
                        <li>
                            <strong>
                                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/PageFlowController.html#onExitNesting()">
                                    <code>onExitNesting</code>
                                </a>
                            </strong>
                            - when the page flow is exiting nesting (through a
                            <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#returnAction()">
                                <code>returnAction</code>
                            </a>
                            on
                            <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
                                <code>@Jpf.Forward</code>
                            </a>
                            or
                            <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">
                                <code>@Jpf.SimpleAction</code>
                            </a>).
                        </li>
                    </ul>
                </section>
                <section id="jsfBackingBeanLifecycle">
                    <title>JavaServer Faces "Backing Bean" Lifecycle</title>
                    <p>
                        JSF backing beans (extended from
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/FacesBackingBean.html">
                            <code>FacesBackingBean</code></a>)
                        have one additional lifecycle method:
                    </p>
                    <ul>
                        <li>
                            <strong>
                                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/FacesBackingBean.html#onRestore()">
                                    <code>onRestore</code>
                                </a>
                            </strong>
                            - when the backing bean is being restored (along with the page itself) through
                            <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#navigateTo()">
                                <code>navigateTo</code></a><code>=</code><a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.NavigateTo.html#currentPage"><code>currentPage</code></a>
                            or
                            <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#navigateTo()">
                                <code>navigateTo</code></a><code>=</code><a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.NavigateTo.html#previousPage"><code>previousPage</code></a>
                            on
                            <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
                                <code>@Jpf.Forward</code>
                            </a>
                            or
                            <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">
                                <code>@Jpf.SimpleAction</code></a>.
                        </li>
                    </ul>
                </section>
            </section>
        </section>
    </body>
</document>
