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>
