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/02 18:50:49 UTC
svn commit: r267229 - in
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui:
overview.xml pageFlowInheritance.xml
Author: rich
Date: Fri Sep 2 09:50:42 2005
New Revision: 267229
URL: http://svn.apache.org/viewcvs?rev=267229&view=rev
Log:
Some updates. Also, replaced tabs with spaces in overview.xml.
tests: build.release in docs/forrest (WinXP)
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowInheritance.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml?rev=267229&r1=267228&r2=267229&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml Fri Sep 2 09:50:42 2005
@@ -1,583 +1,583 @@
<?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 Overview</title>
- </header>
- <body>
- <section id="introduction">
- <title>Introduction</title>
- <p>
- NetUI is the piece of Beehive used to build the
- front-end of a web application. It contains two pieces:
- Page Flow and a powerful set of JSP tags.
- </p>
- </section>
- <section id="why">
- <title>Why Use NetUI?</title>
- <p>
- Simply put, NetUI (Page Flow and a powerful set of JSP
- tags) helps you build a well-structured web application
- using a simple programming model.
- </p>
- <p>
- First, because NetUI is an MVC framework (built on
- <a href="http://struts.apache.org">Apache Struts</a>
- ), it separates navigational control from presentation.
- This avoids:
- </p>
- <ul>
- <li>Limited reuse of navigational/flow logic.</li>
- <li>Cluttered, hard-to-maintain JSP source code.</li>
- <li>
- Difficulty in understanding the flow of an
- application.
- </li>
- <li>
- Unintended exposure of controller-logic code to team
- members who focus on other aspects of web
- development, such as content writers and visual
- designers.
- </li>
- </ul>
- <p>
- Second, NetUI provides the Page Flow programming model
- which allows you to create
- <em>modular</em>
- "page flows" that can be inserted (and reused) inside of
- other flows. At its heart, it unifies the controller
- logic, state, and metadata for a piece of your
- application into a single class. On the View side, it
- offers a rich set of tags, such as the
- <a href="site:pageflow_tag_tree">Tree</a>
- and the
- <a href="site:datagrid">Datagrid</a>
- .
- </p>
- </section>
- <section id="Page_Flow_Features">
- <title>NetUI Features</title>
- <p>
- NetUI makes building Java web applications easy and
- intuitive. When building applications with NetUI, the
- developer writes Java classes and pages --that's it.
- There is very little occasion to work with configuration
- files, or other components. NetUI also excels at
- separating presentation logic from data processing
- logic, resulting in uncluttered JSP code which is easy
- to understand and edit. Data processing and the web
- application configurables are handled in a single Java
- class using a simple declarative programming model.
- </p>
- <p>
- <strong>Declarative Programming</strong>
- </p>
- <p>
- Many common web app programming tasks are accomplished
- through a declarative programming model using
- "annotations", a new feature in Java 5. Annotations put
- configuration information (in general, "metadata") right
- alongside your code, alleviating the need for
- independent configuration files. Navigation, exception
- handling, validation, and other tasks are all defined in
- a single Java class: the Page Flow "controller" class
- that drives a piece of your web application.
- </p>
- <p>
- <strong>Stateful Page Flows</strong>
- </p>
- <p>
- When a user enters a page flow (by hitting an URL in the
- page flow's URL space), an instance of the page flow's
- controller class is created. While the user is in the
- page flow, the controller instance simply stores the
- flow-related state in member variables. Methods within
- the class -- particularly action methods and exception
- handlers -- have access to the member state. By default,
- the state is
- <em>automatically cleaned up</em>
- when the user leaves the page flow to enter another one.
- This behavior can be configured per-page flow, but
- auto-cleanup helps keep your session small, and focused
- on the task at hand.
- </p>
- <p>
- <strong>Modular Page Flows</strong>
- </p>
- <p>
- A single web application can have multiple page flows
- within it, allowing you to break up the application into
- separate, self-contained chunks of functionality. For an
- example, see the
- <a class="fork" href="site:samples/petstore">
- Petstore Sample
- </a>
- , which has different page flows for browsing the
- Petstore, buying products, and handling user accounts.
- </p>
- <p>
- <strong>Inheritance and Shared Flow</strong>
- </p>
- <p>
- <a href="site:pageflow_inheritance">Page Flow inheritance</a> provides a way to share actions,
- exception handlers, state, etc. among controller
- classes. This is just normal Java inheritance used to
- share pieces of controller classes.
- </p>
- <p>
- <a href="site:pageflow_sharedFlow">Shared Flow</a> provides an alternative way to make actions
- and exception handlers available to multiple page flows.
- </p>
- <p>
- <strong>Nested Page Flows</strong>
- </p>
- <p>
- An entire page flow can be inserted, or "nested", inside
- of another page flow. At its heart, nesting is a way of
- pushing aside the current page flow temporarily and
- transferring control to another (nested) page flow with
- the intention of coming back to the original one.
- Nesting is useful when you want to do one of the
- following tasks:
- </p>
- <ul>
- <li>
- gather data from the user, for use in the current
- page flow;
- </li>
- <li>
- allow the user to correct errors or supply
- additional information en route to executing a
- desired action;
- </li>
- <li>
- show an alternate view of data represented in the
- current page flow;
- </li>
- <li>bring the user through a "wizard";</li>
- <li>
- show the user information that will be useful in the
- current page flow (e.g., help screens can be easily
- implemented as nested page flows); and
- </li>
- <li>
- in general, to further break up your application
- into separate (and in many cases reusable) pieces.
- </li>
- </ul>
- <p>
- NetUI also offers special integration between nested
- page flows and
- <a href="site:pageflow_popups">popup windows</a>.
- </p>
- <p>
- <strong>
- Declarative Exception Handling and Validation
- </strong>
- </p>
- <p>
+ <header>
+ <title>NetUI Overview</title>
+ </header>
+ <body>
+ <section id="introduction">
+ <title>Introduction</title>
+ <p>
+ NetUI is the piece of Beehive used to build the
+ front-end of a web application. It contains two pieces:
+ Page Flow and a powerful set of JSP tags.
+ </p>
+ </section>
+ <section id="why">
+ <title>Why Use NetUI?</title>
+ <p>
+ Simply put, NetUI (Page Flow and a powerful set of JSP
+ tags) helps you build a well-structured web application
+ using a simple programming model.
+ </p>
+ <p>
+ First, because NetUI is an MVC framework (built on
+ <a href="http://struts.apache.org">Apache Struts</a>
+ ), it separates navigational control from presentation.
+ This avoids:
+ </p>
+ <ul>
+ <li>Limited reuse of navigational/flow logic.</li>
+ <li>Cluttered, hard-to-maintain JSP source code.</li>
+ <li>
+ Difficulty in understanding the flow of an
+ application.
+ </li>
+ <li>
+ Unintended exposure of controller-logic code to team
+ members who focus on other aspects of web
+ development, such as content writers and visual
+ designers.
+ </li>
+ </ul>
+ <p>
+ Second, NetUI provides the Page Flow programming model
+ which allows you to create
+ <em>modular</em>
+ "page flows" that can be inserted (and reused) inside of
+ other flows. At its heart, it unifies the controller
+ logic, state, and metadata for a piece of your
+ application into a single class. On the View side, it
+ offers a rich set of tags, such as the
+ <a href="site:pageflow_tag_tree">Tree</a>
+ and the
+ <a href="site:datagrid">Datagrid</a>
+ .
+ </p>
+ </section>
+ <section id="Page_Flow_Features">
+ <title>NetUI Features</title>
+ <p>
+ NetUI makes building Java web applications easy and
+ intuitive. When building applications with NetUI, the
+ developer writes Java classes and pages --that's it.
+ There is very little occasion to work with configuration
+ files, or other components. NetUI also excels at
+ separating presentation logic from data processing
+ logic, resulting in uncluttered JSP code which is easy
+ to understand and edit. Data processing and the web
+ application configurables are handled in a single Java
+ class using a simple declarative programming model.
+ </p>
+ <p>
+ <strong>Declarative Programming</strong>
+ </p>
+ <p>
+ Many common web app programming tasks are accomplished
+ through a declarative programming model using
+ "annotations", a new feature in Java 5. Annotations put
+ configuration information (in general, "metadata") right
+ alongside your code, alleviating the need for
+ independent configuration files. Navigation, exception
+ handling, validation, and other tasks are all defined in
+ a single Java class: the Page Flow "controller" class
+ that drives a piece of your web application.
+ </p>
+ <p>
+ <strong>Stateful Page Flows</strong>
+ </p>
+ <p>
+ When a user enters a page flow (by hitting an URL in the
+ page flow's URL space), an instance of the page flow's
+ controller class is created. While the user is in the
+ page flow, the controller instance simply stores the
+ flow-related state in member variables. Methods within
+ the class -- particularly action methods and exception
+ handlers -- have access to the member state. By default,
+ the state is
+ <em>automatically cleaned up</em>
+ when the user leaves the page flow to enter another one.
+ This behavior can be configured per-page flow, but
+ auto-cleanup helps keep your session small, and focused
+ on the task at hand.
+ </p>
+ <p>
+ <strong>Modular Page Flows</strong>
+ </p>
+ <p>
+ A single web application can have multiple page flows
+ within it, allowing you to break up the application into
+ separate, self-contained chunks of functionality. For an
+ example, see the
+ <a class="fork" href="site:samples/petstore">
+ Petstore Sample
+ </a>
+ , which has different page flows for browsing the
+ Petstore, buying products, and handling user accounts.
+ </p>
+ <p>
+ <strong>Inheritance and Shared Flow</strong>
+ </p>
+ <p>
+ <a href="site:pageflow_inheritance">Page Flow inheritance</a> is a powerful way to share actions,
+ exception handlers, configuration, etc. among controller classes. It is normal Java inheritance,
+ plus the ability to inherit/merge <em>annotations</em>.
+ </p>
+ <p>
+ <a href="site:pageflow_sharedFlow">Shared Flow</a> provides an alternative way to make actions and
+ exception handlers available to multiple page flows. The feature is useful for accessing shared state,
+ for shared/templated user interface, and when you cannot change your controller class hierarchy.
+ </p>
+ <p>
+ <strong>Nested Page Flows</strong>
+ </p>
+ <p>
+ An entire page flow can be inserted, or "nested", inside
+ of another page flow. At its heart, nesting is a way of
+ pushing aside the current page flow temporarily and
+ transferring control to another (nested) page flow with
+ the intention of coming back to the original one.
+ Nesting is useful when you want to do one of the
+ following tasks:
+ </p>
+ <ul>
+ <li>
+ gather data from the user, for use in the current
+ page flow;
+ </li>
+ <li>
+ allow the user to correct errors or supply
+ additional information en route to executing a
+ desired action;
+ </li>
+ <li>
+ show an alternate view of data represented in the
+ current page flow;
+ </li>
+ <li>bring the user through a "wizard";</li>
+ <li>
+ show the user information that will be useful in the
+ current page flow (e.g., help screens can be easily
+ implemented as nested page flows); and
+ </li>
+ <li>
+ in general, to further break up your application
+ into separate (and in many cases reusable) pieces.
+ </li>
+ </ul>
+ <p>
+ NetUI also offers special integration between nested
+ page flows and
+ <a href="site:pageflow_popups">popup windows</a>.
+ </p>
+ <p>
+ <strong>
+ Declarative Exception Handling and Validation
+ </strong>
+ </p>
+ <p>
<a href="site:docs/pageflow/netuiBasic/actions">Exception handling</a> and
- <a href="site:pageflow_valid">data validation</a>
- are accomplished through a declarative programming
- model. The desired exception handling and validation
- behaviors are declared in the "controller" class
- alongside your Java code in the form of metadata
- annotations. This allows for single file editing and
- eliminates the need for separate configuration files.
- </p>
- <p>
- <strong>Powerful JSP Tags</strong>
- </p>
- <p>
- NetUI provides three <a href="site:pageflow_tag_overview">tag libraries</a>: (1) one library
- represents the core HTML tags, (2) another renders data
- grids and complex data sets as HTML, and (3) a third
- library provides page templating functionality.
- </p>
- <p>
- The NetUI tags also support <a href="site:databinding">data binding</a> (1) to JSP
- implicit objects (through the JSP 2.0 Expression
- Language) and (2) to other NetUI implicit objects. Note
- that many tags possess read-write access to these
- implicit objects.
- </p>
- <p>
- <strong>
- First-class Integration with JavaServer Faces
- </strong>
- </p>
- <p>
- NetUI can co-exist with all <a href="site:pageflow_jsf">JavaServer
- Faces</a> tags and features.
- And NetUI and JSF are deeply integrated. For example, JSF pages can raise NetUI actions
- directly, JSF pages can databind to NetUI implicit objects, etc.
- </p>
- <p>
- <strong>Struts Integration</strong>
- </p>
- <p>
- Page Flow is built on top of Apache Struts 1.1. Each
- Page Flow controller is compiled into a Struts module.
- As a result, NetUI and Struts applications can work
- closely together.
- </p>
- <p>
- Struts modules and page flows can co-habitate and
- interact with one another inside a web app. To forward
- from a page flow to a (pure) Struts module, simply
- reference the desired action within the Struts module.
- The same goes for the reverse direction: from a Struts
- module, simply configure an action to point to the
- desired method in the page flow.
- <!--[todo: detailed doc based on R. Feit's: http://dev2dev.bea.com/products/wlworkshop81/articles/Feit.jsp]-->
- </p>
- <p>
- You can also use the Struts merge feature to read
- configuration data from a pure Struts app into your Page
- Flow app's configuration files. Ordinarily, your Page
- Flow's configuration files are generated entirely from
- your application's JAVA source files (specifically from
- the
- <em>metadata annotations</em>
- that decorate the controller classs). But, in cases
- where you want to integrate a Struts module into your
- application, you can specify that the configuration
- files be generated from
- <em>both</em>
- the JAVA source files
- <em>and</em>
- the Struts module's configuration files, allowing you to
- change or add
- <em>any tag</em>
- in the generated configuration file. For example,
- suppose you want to override an action form's default
- scoping from request-scoping to session-scoping. To do
- this, you simply create a Struts configuration file that
- overrides the appropriate parts of the Page Flow's
- configuration file, and then refer to this override file
- from within the Page Flow's JAVA source file (= the
- controller class) using a special annotation. In
- particular, you would specify the override file to state
- that such-and-such an action form should have
- session-scope rather then request-scope (so that the
- action form can now be shared with the Struts app).
- </p>
- </section>
- <section id="logical_flow">
- <title>The Logical Flow</title>
-
- <p>
- Writing traditional web applications without a Page Flow
- controller class requires a fair amount of logic to be
- applied within the application's pages. For example, a
- site that provides a "My Page" functionality for logged
- in users would have to include logic on the home page to
- determine if the "My Page" link should take the user to
- the login form or directly to their customized page.
- </p>
-
- <p>
- Using a page flow, the home page of the application
- would not link directly to either the login page
- <strong>or</strong>
- the user's "My Page" location, but rather would point
- back into Java code that makes the decision.
- </p>
-
- <p>
- For the rest of this overview, the following
- <strong>logical page flow</strong>
- will be used:
- </p>
-
- <p>
- <img src="images/logical-flow-1.png"
- alt="logical page flow" />
- </p>
-
- <p>
- This flow supports several routes from the home page of
- the application to the user's "My Page":
- </p>
-
- <ol>
- <li>
- <p>
- The user may directly navigate from
- <code>index.jsp</code>
- to
- <code>mypage.jsp</code>
- (by clicking a link), if the user is already
- logged in.
- </p>
- </li>
- <li>
- <p>
- If the user is not already logged in, attempts
- to navigate from
- <code>index.jsp</code>
- to
- <code>mypage.jsp</code>
- will be intercepted and the user will be taken
- to the
- <code>login.jsp</code>
- instead. After successfully logging in, the user
- will be automatically taken to
- <code>mypage.jsp</code>
- </p>
- </li>
- <li>
- <p>
- The user may directly navigate from
- <code>index.jsp</code>
- to
- <code>login.jsp</code>
- (by clicking a link). After logging in, the user
- will be automatically taken to
- <code>mypage.jsp</code>
- .
- </p>
-
- <p>
- In the event of a login failure,
- <code>login.jsp</code>
- will be redisplayed to give them another
- opportunity to authenticate themselves.
- </p>
- </li>
- <li>
- <p>
- If the user desires to register with the site,
- he can click a link that will take him to
- <code>signup.jsp</code>
- . One signed up, the
- <code>thanks.jsp</code>
- will be displayed which offers a link to the
- <code>login.jsp</code>
- page.
- </p>
- </li>
- </ol>
-
- </section>
-
- <section id="implementation_of_flow">
- <title>
- The Implementation of the Flow: Controllers and Actions
- </title>
-
- <p>
- In the above
- <strong>logical flow</strong>
- there are several
- <em>if</em>
- statements that cause the user flow to vary depending on
- their previous actions and other state.
- </p>
-
- <ul>
- <li>
- <em>If the user is not logged in...</em>
- </li>
- <li>
- <em>If the user is logged in...</em>
- </li>
- <li>
- <em>If the user's login attempt fails...</em>
- </li>
- </ul>
-
- <p>
- NetUI moves this condition logic out of the JSPs and
- into a Java class that controls the movement through the
- application. This Java class is the
- <strong>controller</strong>
- portion of the
- <strong>Model-View-Controller</strong>
- (MVC) pattern. This allows a page to be written, for
- example, that appears to link directly from the home
- page of the application to the user's "My Page". The
- controller is given the opportunity to intercept the
- navigation between the two and redirect the user to the
- login page, if required.
- </p>
-
- <p>
- Each of the interception points is an
- <strong>action</strong>
- of the particular controller class. Actions perform
- common application tasks. Here are some of the things
- that an action can do:
- </p>
-
- <ul>
- <li>navigate the user to a specified JSP</li>
- <li>perform conditional logic</li>
- <li>handle submitted data</li>
- <li>validate submitted data</li>
- <li>handle exceptions that arise in the application</li>
- </ul>
-
- <p>
- Note that controller classes, and the actions they
- contain, are
- <strong>URL addressable</strong>
- . Hitting the following URL creates an instance of the
- controller class
- <code>foo.MyControllerClass</code>
- and runs its
- <code>begin</code>
- action. (When no other action is specified, the
- <code>begin</code>
- method is run by default.)
- </p>
-
- <source>http://some.domain.com/foo/MyControllerClass.java</source>
-
- <p>
- Hitting the following URL creates an instance of
- <code>foo.MyControllerClass</code>
- (if it doesn't already exist) and invokes the
- <code>someAction</code>
- action. Note that the controller class isn't mentioned
- by name: it's assumed that only one controller class
- exists in the directory, so there is only one candidate
- controller class to instantiate.
- </p>
-
- <source>http://some.domain.com/foo/someAction.do</source>
- <note>
- To make a Page Flow controller handle a default
- directory URL, e.g.,
- <br />
- <br />
- http://some.domain.com/myApp/myPageFlow
- <br />
- <br />
- you will need to add the page flow's URL to the
- <code>welcome-file-list</code>
- in
- <code>/WEB-INF/web.xml</code>
- :
- <br />
- <br />
- <welcome-file-list>
- <br />
- <welcome-file>Controller.jpf</welcome-file>
- <br />
- <welcome-file>index.jsp</welcome-file>
- <br />
- </welcome-file-list>
- <br />
- <br />
- This would cause the following URL to be hit for the
- above example:
- <br />
- <br />
- http://some.domain.com/myApp/myPageFlow/Controller.jpf
- <br />
- <br />
- On some servers (like Tomcat), you would also need to
- make sure that a
- <em>file</em>
- called
- <code>Controller.jpf</code>
- also exists in the web content under
- <code>/myPageFlow</code>
- , even though the class
- <code>myPageFlow.Controller</code>
- actually handles the request. (The file can be blank.)
- </note>
-
- <p>
- Actions may perform any required complex logic. For
- example, if a user clicks on the "My Page" link, the
- action may check if the user is logged in, and if so,
- navigate the user to the
- <code>mypage.jsp</code>
- page; otherwise it will navigate the user to the
- <code>login.jsp</code>
- page.
- </p>
-
- <p>
- With normal HTML pages, each page is linked directly to
- other pages.
- </p>
-
- <ul>
- <li>
- <strong>page > page > page > page</strong>
- </li>
- </ul>
-
- <p>
- When using page flows, pages and actions are interwoven,
- transparently.
- </p>
-
- <ul>
- <li>
- <strong>
- page > action > page > action > page
- > action > page
- </strong>
- </li>
- </ul>
-
- <p>
- The above
- <strong>logical page flow</strong>
- can be redrawn with Page Flow controller actions in
- mind, as:
- </p>
-
- <p>
- <img src="images/impl-flow-1.png"
- alt="implementation page flow" />
- </p>
-
- <p>
- Now it is apparent that to navigate from
- <code>index.jsp</code>
- to
- <code>mypage.jsp</code>
- , the user traverses across the
- <code>myPage</code>
- action. This action performs the necessary check to
- determine if the user has already been authenticated. If
- the user has logged in already, it will direct the user
- straight to
- <code>mypage.jsp</code>
- ; otherwise it will direct the user to
- <code>login.jsp</code>
- .
- </p>
- </section>
- <section id="next">
- <title>Next...</title>
-
- <p>
- Next, learn about writing a
- <strong>controller</strong>
- class with actions.
- </p>
-
- <ul>
- <li>
- <a class="jump" href="site:pageflow_controllers">
- Controller Classes</a>
- </li>
- </ul>
- </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 />
- © 2004, Apache Software Foundation
- </legal>
- </footer>
+ <a href="site:pageflow_valid">data validation</a>
+ are accomplished through a declarative programming
+ model. The desired exception handling and validation
+ behaviors are declared in the controller class
+ (and additionally on form bean classes, for validation)
+ alongside your Java code in the form of metadata
+ annotations. This allows for single file editing and
+ eliminates the need for separate configuration files.
+ </p>
+ <p>
+ <strong>Powerful JSP Tags</strong>
+ </p>
+ <p>
+ NetUI provides three <a href="site:pageflow_tag_overview">tag libraries</a>: (1) one library
+ represents the core HTML tags, (2) another renders data
+ grids and complex data sets as HTML, and (3) a third
+ library provides page templating functionality.
+ </p>
+ <p>
+ The NetUI tags also support <a href="site:databinding">data binding</a> (1) to JSP
+ implicit objects (through the JSP 2.0 Expression
+ Language) and (2) to other NetUI implicit objects. Note
+ that many tags possess read-write access to these
+ implicit objects.
+ </p>
+ <p>
+ <strong>
+ First-class Integration with JavaServer Faces
+ </strong>
+ </p>
+ <p>
+ NetUI has solid integration with <a href="site:pageflow_jsf">JavaServer Faces</a>. It treats JSF as a
+ first-class view tier, where, for example, JSF components and command handlers can raise Page Flow
+ actions, can databind to NetUI implicit objects, etc.
+ </p>
+ <p>
+ <strong>Struts Integration</strong>
+ </p>
+ <p>
+ Page Flow is built on top of Apache Struts 1.1. Each
+ Page Flow controller is compiled into a Struts module.
+ As a result, NetUI and Struts applications can work
+ closely together.
+ </p>
+ <p>
+ Struts modules and page flows can co-habitate and
+ interact with one another inside a web app. To forward
+ from a page flow to a (pure) Struts module, simply
+ reference the desired action within the Struts module.
+ The same goes for the reverse direction: from a Struts
+ module, simply configure an action to point to the
+ desired method in the page flow.
+ <!--[todo: detailed doc based on R. Feit's: http://dev2dev.bea.com/products/wlworkshop81/articles/Feit.jsp]-->
+ </p>
+ <p>
+ You can also use the Struts merge feature to read
+ configuration data from a pure Struts app into your Page
+ Flow app's configuration files. Ordinarily, your Page
+ Flow's configuration files are generated entirely from
+ your application's JAVA source files (specifically from
+ the
+ <em>metadata annotations</em>
+ that decorate the controller classes). But, in cases
+ where you want to integrate a Struts module into your
+ application, you can specify that the configuration
+ files be generated from
+ <em>both</em>
+ the JAVA source files
+ <em>and</em>
+ the Struts module's configuration files, allowing you to
+ change or add
+ <em>any tag</em>
+ in the generated configuration file. For example,
+ suppose you want to override an action form's default
+ scoping from request-scoping to session-scoping. To do
+ this, you simply create a Struts configuration file that
+ overrides the appropriate parts of the Page Flow's
+ configuration file, and then refer to this override file
+ from within the Page Flow's JAVA source file (= the
+ controller class) using a special annotation. In
+ particular, you would specify the override file to state
+ that such-and-such an action form should have
+ session-scope rather then request-scope (so that the
+ action form can now be shared with the Struts app).
+ </p>
+ </section>
+ <section id="logical_flow">
+ <title>The Logical Flow</title>
+
+ <p>
+ Writing traditional web applications without a Page Flow
+ controller class requires a fair amount of logic to be
+ applied within the application's pages. For example, a
+ site that provides a "My Page" functionality for logged
+ in users would have to include logic on the home page to
+ determine if the "My Page" link should take the user to
+ the login form or directly to their customized page.
+ </p>
+
+ <p>
+ Using a page flow, the home page of the application
+ would not link directly to either the login page
+ <strong>or</strong>
+ the user's "My Page" location, but rather would point
+ back into Java code that makes the decision.
+ </p>
+
+ <p>
+ For the rest of this overview, the following
+ <strong>logical page flow</strong>
+ will be used:
+ </p>
+
+ <p>
+ <img src="images/logical-flow-1.png"
+ alt="logical page flow" />
+ </p>
+
+ <p>
+ This flow supports several routes from the home page of
+ the application to the user's "My Page":
+ </p>
+
+ <ol>
+ <li>
+ <p>
+ The user may directly navigate from
+ <code>index.jsp</code>
+ to
+ <code>mypage.jsp</code>
+ (by clicking a link), if the user is already
+ logged in.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the user is not already logged in, attempts
+ to navigate from
+ <code>index.jsp</code>
+ to
+ <code>mypage.jsp</code>
+ will be intercepted and the user will be taken
+ to the
+ <code>login.jsp</code>
+ instead. After successfully logging in, the user
+ will be automatically taken to
+ <code>mypage.jsp</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ The user may directly navigate from
+ <code>index.jsp</code>
+ to
+ <code>login.jsp</code>
+ (by clicking a link). After logging in, the user
+ will be automatically taken to
+ <code>mypage.jsp</code>
+ .
+ </p>
+
+ <p>
+ In the event of a login failure,
+ <code>login.jsp</code>
+ will be redisplayed to give them another
+ opportunity to authenticate themselves.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the user desires to register with the site,
+ he can click a link that will take him to
+ <code>signup.jsp</code>
+ . One signed up, the
+ <code>thanks.jsp</code>
+ will be displayed which offers a link to the
+ <code>login.jsp</code>
+ page.
+ </p>
+ </li>
+ </ol>
+
+ </section>
+
+ <section id="implementation_of_flow">
+ <title>
+ The Implementation of the Flow: Controllers and Actions
+ </title>
+
+ <p>
+ In the above
+ <strong>logical flow</strong>
+ there are several
+ <em>if</em>
+ statements that cause the user flow to vary depending on
+ their previous actions and other state.
+ </p>
+
+ <ul>
+ <li>
+ <em>If the user is not logged in...</em>
+ </li>
+ <li>
+ <em>If the user is logged in...</em>
+ </li>
+ <li>
+ <em>If the user's login attempt fails...</em>
+ </li>
+ </ul>
+
+ <p>
+ NetUI moves this condition logic out of the JSPs and
+ into a Java class that controls the movement through the
+ application. This Java class is the
+ <strong>controller</strong>
+ portion of the
+ <strong>Model-View-Controller</strong>
+ (MVC) pattern. This allows a page to be written, for
+ example, that appears to link directly from the home
+ page of the application to the user's "My Page". The
+ controller is given the opportunity to intercept the
+ navigation between the two and redirect the user to the
+ login page, if required.
+ </p>
+
+ <p>
+ Each of the interception points is an
+ <strong>action</strong>
+ of the particular controller class. Actions perform
+ common application tasks. Here are some of the things
+ that an action can do:
+ </p>
+
+ <ul>
+ <li>navigate the user to a specified JSP</li>
+ <li>perform conditional logic</li>
+ <li>handle submitted data</li>
+ <li>validate submitted data</li>
+ <li>handle exceptions that arise in the application</li>
+ </ul>
+
+ <p>
+ Note that controller classes, and the actions they
+ contain, are
+ <strong>URL addressable</strong>
+ . Hitting the following URL creates an instance of the
+ controller class
+ <code>foo.MyControllerClass</code>
+ and runs its
+ <code>begin</code>
+ action. (When no other action is specified, the
+ <code>begin</code>
+ method is run by default.)
+ </p>
+
+ <source>http://some.domain.com/foo/MyControllerClass.java</source>
+
+ <p>
+ Hitting the following URL creates an instance of
+ <code>foo.MyControllerClass</code>
+ (if it doesn't already exist) and invokes the
+ <code>someAction</code>
+ action. Note that the controller class isn't mentioned
+ by name: it's assumed that only one controller class
+ exists in the directory, so there is only one candidate
+ controller class to instantiate.
+ </p>
+
+ <source>http://some.domain.com/foo/someAction.do</source>
+ <note>
+ To make a Page Flow controller handle a default
+ directory URL, e.g.,
+ <br />
+ <br />
+ http://some.domain.com/myApp/myPageFlow
+ <br />
+ <br />
+ you will need to add the page flow's URL to the
+ <code>welcome-file-list</code>
+ in
+ <code>/WEB-INF/web.xml</code>
+ :
+ <br />
+ <br />
+ <welcome-file-list>
+ <br />
+ <welcome-file>Controller.jpf</welcome-file>
+ <br />
+ <welcome-file>index.jsp</welcome-file>
+ <br />
+ </welcome-file-list>
+ <br />
+ <br />
+ This would cause the following URL to be hit for the
+ above example:
+ <br />
+ <br />
+ http://some.domain.com/myApp/myPageFlow/Controller.jpf
+ <br />
+ <br />
+ On some servers (like Tomcat), you would also need to
+ make sure that a
+ <em>file</em>
+ called
+ <code>Controller.jpf</code>
+ also exists in the web content under
+ <code>/myPageFlow</code>
+ , even though the class
+ <code>myPageFlow.Controller</code>
+ actually handles the request. (The file can be blank.)
+ </note>
+
+ <p>
+ Actions may perform any required complex logic. For
+ example, if a user clicks on the "My Page" link, the
+ action may check if the user is logged in, and if so,
+ navigate the user to the
+ <code>mypage.jsp</code>
+ page; otherwise it will navigate the user to the
+ <code>login.jsp</code>
+ page.
+ </p>
+
+ <p>
+ With normal HTML pages, each page is linked directly to
+ other pages.
+ </p>
+
+ <ul>
+ <li>
+ <strong>page > page > page > page</strong>
+ </li>
+ </ul>
+
+ <p>
+ When using page flows, pages and actions are interwoven,
+ transparently.
+ </p>
+
+ <ul>
+ <li>
+ <strong>
+ page > action > page > action > page
+ > action > page
+ </strong>
+ </li>
+ </ul>
+
+ <p>
+ The above
+ <strong>logical page flow</strong>
+ can be redrawn with Page Flow controller actions in
+ mind, as:
+ </p>
+
+ <p>
+ <img src="images/impl-flow-1.png"
+ alt="implementation page flow" />
+ </p>
+
+ <p>
+ Now it is apparent that to navigate from
+ <code>index.jsp</code>
+ to
+ <code>mypage.jsp</code>
+ , the user traverses across the
+ <code>myPage</code>
+ action. This action performs the necessary check to
+ determine if the user has already been authenticated. If
+ the user has logged in already, it will direct the user
+ straight to
+ <code>mypage.jsp</code>
+ ; otherwise it will direct the user to
+ <code>login.jsp</code>
+ .
+ </p>
+ </section>
+ <section id="next">
+ <title>Next...</title>
+
+ <p>
+ Next, learn about writing a
+ <strong>controller</strong>
+ class with actions.
+ </p>
+
+ <ul>
+ <li>
+ <a class="jump" href="site:pageflow_controllers">
+ Controller Classes</a>
+ </li>
+ </ul>
+ </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 />
+ © 2004, Apache Software Foundation
+ </legal>
+ </footer>
</document>
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowInheritance.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowInheritance.xml?rev=267229&r1=267228&r2=267229&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowInheritance.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowInheritance.xml Fri Sep 2 09:50:42 2005
@@ -9,8 +9,8 @@
<section id="intro">
<title>Introduction</title>
<p>
- Page Flow inheritance is a powerful way to share actions, exception handlers, state, etc. among
- controller classes. The basic idea is simple: you use normal Java inheritance to share pieces
+ Page Flow inheritance is a powerful way to share actions, exception handlers, configuration, etc. among
+ controller classes. The basic idea is simple: you use Java inheritance to share pieces
of controller classes. This document shows ways in which you might use the feature, and also shows
areas that go beyond what you might expect from standard Jave inheritance.
</p>