<?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="site:pageflow_inheritance">inheritance</a> and
                <a href="site:pageflow_sharedFlow">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
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
                    <code>@Jpf.Controller</code>
                </a>
                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>
&lt;c:if test="${sharedFlow.mySharedFlow.usingLargePictures}"&gt;
    ...
&lt;/c:if&gt;
                        </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/javadoc/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
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SharedFlowRef.html">
                        <code>@Jpf.SharedFlowRef</code></a>.
                </p>
                <note>
                    The <a href="site: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
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SharedFlowRef.html">
                        <code>@Jpf.SharedFlowRef</code></a>.
                </p>
                <p>
                    Is this a sneaky way to support multiple inheritance? We leave it for you to decide.
                </p>
            </section>
        </section>
    </body>
</document>
