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/08/19 07:23:24 UTC
svn commit: r233433 - in
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow:
sharedFlow.xml sharedFlow_vs_inheritance.xml
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>
+@Jpf.Controller
+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>
+@Jpf.Controller(
+ 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>
+@Jpf.SharedFlowField(name="mySharedFlow")
+private MySharedFlow _mySharedFlow; // This field is auto-initialized.
+
+@Jpf.Action(...)
+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