Author: rich
Date: Thu Aug 18 22:23:18 2005
New Revision: 233433
URL: http://svn.apache.org/viewcvs?rev=233433&view=rev
Log:
Added a doc for "Shared Flow vs. Inheritance". It's not hooked into the nav
bar yet. Also made some minor fixes in the Shared Flow doc.
tests: validate in docs/forrest/release (WinXP)
BB: self (linux)
Added:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow_vs_inheritance.xml
(with props)
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow.xml
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow.xml?rev=233433&r1=233432&r2=233433&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow.xml
Thu Aug 18 22:23:18 2005
@@ -8,7 +8,7 @@
<body>
<section id="intro">
<title>Introduction</title>
- <p>A shared flow (a kind of controller class) provides
a place for
+ <p>A shared flow (a kind of controller class) provides a place for
actions, exception handlers and data that the
developer wants
to make available to multiple page flows. You
can have multiple
shared flows, each with different delegated
functions. For
@@ -105,9 +105,9 @@
use the @Jpf.SharedFlowRef annotation (an
attribute of the parent @Jpf.Controller
annotation).</p>
<source>@Jpf.Contoller(
- sharedFlowsRefs = {
- @Jpf.SharedFlowRef(name = "someNameOne", type =
"SharedFlowClassOne.class"),
- @Jpf.SharedFlowRef(name = "someNameTwo", type =
"SharedFlowClassTwo.class")
+ sharedFlowsRefs={
+ @Jpf.SharedFlowRef(name="someNameOne",
type="SharedFlowClassOne.class"),
+ @Jpf.SharedFlowRef(name="someNameTwo", type="SharedFlowClassTwo.class")
}
)
public class SomeController extends Controller
@@ -115,9 +115,9 @@
<p>and then create a member of your shared flow class. The member
must be decorated with the
@Jpf.SharedFlowField annotation. </p>
<source>@Jpf.Contoller(
- sharedFlowsRefs = {
- @Jpf.SharedFlowRef(name = "sharedFlowOne", type =
"SharedFlowClassOne.class"),
- @Jpf.SharedFlowRef(name = "sharedFlowTwo", type =
"SharedFlowClassTwo.class")
+ sharedFlowsRefs={
+ @Jpf.SharedFlowRef(name="sharedFlowOne",
type="SharedFlowClassOne.class"),
+ @Jpf.SharedFlowRef(name="sharedFlowTwo",
type="SharedFlowClassTwo.class")
}
)
public class SomeController extends Controller
@@ -149,12 +149,12 @@
<p>Actions declared in a SharedFlow are accessed by specifying a fully
qualified action</p>
- <source><beehive-petstore:catalogNav
action="sharedFlow.specificSharedFlow.someAction"
labelValue="${bundle.view.mainMenuLabel}"/></source>
+ <source><beehive-petstore:catalogNav
action="specificSharedFlow.someAction"
labelValue="${bundle.view.mainMenuLabel}"/></source>
<p>where <code>specificSharedFlow</code> was the name given to the shared flow
in the
<code>@Jpf.SharedFlowRef/@Jpf.SharedFlowField</code>
annotations.</p>
- <source>@Jpf.SharedFlowRef(name = "specficSharedFlow", type =
"SomeSharedFlow.class")
+ <source>@Jpf.SharedFlowRef(name="specficSharedFlow",
type="SomeSharedFlow.class")
@Jpf.SharedFlowField(name="specificSharedFlow")
</source>
@@ -165,4 +165,4 @@
located at
<code><BeehiveRoot>/samples/petstoreWeb/webappRoot/SharedFlow.java</code></p>
</section>
</body>
-</document>
\ No newline at end of file
+</document>
Added:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow_vs_inheritance.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow_vs_inheritance.xml?rev=233433&view=auto
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow_vs_inheritance.xml
(added)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow_vs_inheritance.xml
Thu Aug 18 22:23:18 2005
@@ -0,0 +1,142 @@
+<?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>Shared Flow vs. Inheritance</title>
+ </header>
+ <body>
+ <section id="intro">
+ <title>Introduction</title>
+ <p>Page Flow supports both <a
href="inheritance.html">inheritance</a> and
+ <a href="sharedFlow.html">Shared Flow</a>. At first glance the
two seem similar; both allow you to share
+ actions and exception handlers. The general guideline for
which to use is simple: <em>use Page Flow
+ inheritance whenever you can</em>. It allows you to share more
than just actions and exception handlers
+ (e.g., you inherit everything in the base class
<code>@Jpf.Controller</code> annotation), and it uses a
+ familiar Java concept in order to do it. This document mainly
explains the (important) cases where you
+ <em>would</em> want to use Shared Flow.
+ </p>
+ </section>
+ <section id="whenToUseSharedFlow">
+ <title>When to Use Shared Flow</title>
+ <p>
+ There are three main cases where you would want to use Shared
Flow: for accessing shared state, for
+ shared/templated user interface, and when you cannot change
your controller class hierarchy.
+ </p>
+ <section id="accessingSharedState">
+ <title>Accessing shared state</title>
+ <p>
+ You want to share actions or exception handlers that use a
<em>single copy</em> of some shared
+ state. For example, the following shared flow action
<code>switchToLargePictures</code> sets a
+ single flag that can be used by <em>many</em> page flows:
+ </p>
+ <source>
[EMAIL PROTECTED]
+public class MySharedFlow extends SharedFlowController
+{
+ private boolean _usingLargePictures = false;
+
+ @Jpf.Action(
+ forwards={
+ @Jpf.Forward(name="cur", navigateTo=Jpf.NavigateTo.currentPage)
+ }
+ )
+ public Forward switchToLargePictures()
+ {
+ _usingLargePictures = true;
+ return new Forward("cur");
+ }
+
+ public boolean isUsingLargePictures()
+ {
+ return _usingLargePictures;
+ }
+}
+ </source>
+ <p>
+ There is only one instance of a given shared flow per
user, so any page flow which references
+ <code>MySharedFlow</code> will have access to the
<em>single</em> value of this flag. For example,
+ the following page flow references
<code>MySharedFlow</code> under the name "mySharedFlow":
+ </p>
+ <source>
[EMAIL PROTECTED](
+ sharedFlowRefs={
+ @Jpf.SharedFlowRef(name="mySharedFlow", type=MySharedFlow.class)
+ }
+)
+public class ExamplePageFlow extends PageFlowController
+{
+}
+ </source>
+ <p>
+ It can access the shared flow's
<code>usingLargePictures</code> property in one of two ways:
+ </p>
+ <ul>
+ <li>
+ In its JSPs, through databinding, e.g.,
+ <source>
+<c:if test="${sharedFlow.mySharedFlow.usingLargePictures}">
+ ...
+</c:if>
+ </source>
+ </li>
+ <li>
+ Directly, through an annotated field in the page flow
controller class:
+ <source>
[EMAIL PROTECTED](name="mySharedFlow")
+private MySharedFlow _mySharedFlow; // This field is auto-initialized.
+
[EMAIL PROTECTED](...)
+public Forward someAction()
+{
+ if (_mySharedFlow.isUsingLargePictures())
+ {
+ ...
+ }
+}
+ </source>
+ </li>
+ </ul>
+ <p>
+ There is a simple reason you would not want to put a flag
like <code>isUsingLargePictures</code>
+ in a base class. If you did, you would end up with a
<em>separate copy</em> of the value in each
+ derived controller class, thus making it more difficult to
share the flag.
+ </p>
+ </section>
+ <section id="sharedActionsForSharedView">
+ <title>
+ Shared actions and exception handlers for shared user
interface
+ </title>
+ <p>
+ Say you are sharing some bit of user interface, like a
menu bar. You may be using the NetUI
+ <a
href="../apidocs/classref_pageflows/org/apache/beehive/netui/tags/template/Template.html">
+ Template
+ </a>
+ tags, or you may be using Page Flow's support for
+ <a
href="http://struts.apache.org/userGuide/dev_tiles.html";>Tiles</a>. In either
case, the user
+ interface you're sharing will likely have its own actions
(and possibly exception handlers)
+ associated with it. <em>It usually does not make sense to
be forced to extend a different
+ page flow controller, just to get the shared actions for
something like a menu bar.</em> You may
+ be including <em>lots</em> of shared user interface
(navigation bar, header, footer, etc.), and it
+ would be bad for each one to require its own base class.
Instead, each one can have an associated
+ shared flow, which you reference in your page flow using a
<code>@Jpf.SharedFlowRef</code>.
+ </p>
+ <note>
+ The <a href="netui-samples">NetUI Samples</a> show shared
flows being used with both the Template
+ tags and with Tiles.
+ </note>
+ </section>
+ <section id="multipleInheritance">
+ <title>You cannot change the inheritance hierarchy for your
page flow controller</title>
+ <p>
+ In some cases, you simply cannot change the base class for
your page flow controller. You may have
+ a prescribed base class, yet you still want to share some
separate group of actions. When this
+ happens, you can always reference a shared flow, using a
<code>@Jpf.SharedFlowRef</code>.
+ </p>
+ <p>
+ Is this a sneaky way to support multiple inheritance? We
leave it for you to decide.
+ </p>
+ </section>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/sharedFlow_vs_inheritance.xml
------------------------------------------------------------------------------
svn:eol-style = native
