You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by ri...@apache.org on 2005/09/05 05:33:06 UTC
svn commit: r278668 - in
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs:
netui/lifecycleAndState.xml site.xml
Author: rich
Date: Sun Sep 4 20:32:59 2005
New Revision: 278668
URL: http://svn.apache.org/viewcvs?rev=278668&view=rev
Log:
Documentation on state and lifecycle.
tests: build.release in docs/forrest (WinXP)
Added:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/lifecycleAndState.xml (with props)
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
Added: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/lifecycleAndState.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/lifecycleAndState.xml?rev=278668&view=auto
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/lifecycleAndState.xml (added)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/lifecycleAndState.xml Sun Sep 4 20:32:59 2005
@@ -0,0 +1,231 @@
+<?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, the same instance
+ 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/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html#longLived()">
+ <code>longLived</code>
+ </a>
+ attribute to <code>true</code> on
+ <a href="../apidocs/classref_netui/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/classref_netui/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/classref_netui/org/apache/beehive/netui/pageflow/FlowController.html#remove">
+ <code>remove()</code>
+ </a>
+ method, or
+ <a href="../apidocs/classref_netui/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/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.FacesBacking.html">
+ <code>@Jpf.FacesBacking</code></a>, and extends
+ <a href="../apidocs/classref_netui/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 the same page.
+ </p>
+ <p>
+ See <a href="site:docs/pageflow/netuiBasic/pageflow_jsf">this document</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/classref_netui/org/apache/beehive/netui/pageflow/PageFlowManagedObject.html#onCreate"><code>onCreate</code></a>
+ or
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/PageFlowManagedObject.html#onDestroy"><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/classref_netui/org/apache/beehive/netui/pageflow/FlowController.html#beforeAction">
+ <code>beforeAction</code>
+ </a>
+ </strong>
+ - before any action is run.
+ </li>
+ <li>
+ <strong>
+ <a href="../apidocs/classref_netui/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/classref_netui/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/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#returnAction()">
+ <code>returnAction</code>
+ </a>
+ on
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
+ <code>@Jpf.Forward</code>
+ </a>
+ or
+ <a href="../apidocs/classref_netui/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/classref_netui/org/apache/beehive/netui/pageflow/FacesBackingBean.html">
+ <code>FacesBackingBean</code></a>)
+ have one additional lifecycle method:
+ </p>
+ <ul>
+ <li>
+ <strong>
+ <a href="../apidocs/classref_netui/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/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#navigateTo()">
+ <code>navigateTo</code></a><code>=</code><a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.NavigateTo#currentPage.html"><code>currentPage</code></a>
+ or
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#navigateTo()">
+ <code>navigateTo</code></a><code>=</code><a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.NavigateTo#previousPage.html"><code>previousPage</code></a>
+ on
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
+ <code>@Jpf.Forward</code>
+ </a>
+ or
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">
+ <code>@Jpf.SimpleAction</code></a>.
+ </li>
+ </ul>
+ </section>
+ </section>
+ </section>
+ </body>
+</document>
Propchange: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/lifecycleAndState.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml?rev=278668&r1=278667&r2=278668&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml Sun Sep 4 20:32:59 2005
@@ -35,6 +35,7 @@
</databinding>
<exceptionHandling label="Exception Handling" href="netui/exceptionHandling.html"/>
<validation label="Validation" href="netui/validation.html"/>
+ <ffdfdfdfd label="Lifecycle and State" href="netui/lifecycleAndState.html"/>
<nestedPageFlow label="Nested Page Flows" href="netui/nestedPageFlow.html"/>
<pageflow_jsf label="Java Server Faces" href="netui/jsf.html"/>
</netuiBasic>