<?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</title>
	</header>
	<body>
		<section id="intro">
			<title>Introduction</title>
            <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.  Shared flows are most useful for
                accessing shared state, for shared/templated user interface, and when you cannot change your controller
                class hierarchy.
            </p>
			<p>
                Shared flows can reside anywhere in your web app, and can be referenced from other controller files or
                from pages.
            </p>
            <note>
                Both shared flows and <a href="site:pageflow_inheritance">Page Flow Inheritance</a> offer ways to share
                actions and exception handlers.  See
                <a href="site:pageflow_sharedFlowVsInheritance">Shared Flow vs. Inheritance</a> for some guidelines on
                when to use each one.
            </note>
		</section>
        <section id="basics">
            <title>Shared Flow Basics</title>
            <p>
                The Shared Flow feature has the following basic properties, which are described in
                more detail below.
            </p>
            <ul>
                <li>
                    A shared flow is <em>referenced</em> by any page flow that wants to share its
                    actions, exception handlers, and data.
                </li>
                <li>
                    When you hit a page flow, you are guaranteed to have access to a <em>single
                    instance of each of its referenced shared flows</em>.  These shared flow
                    instances are stored in the user session, and they are not destroyed until the
                    session ends, or until they are destroyed explicitly.
                </li>
                <li>
                    A page flow or any of its JSPs can raise actions on any referenced shared flow.
                </li>
                <li>
                    Unhandled exceptions in the page flow are <em>automatically</em> tried on all
                    referenced shared flows, until one of them handles the exception.
                </li>
            </ul>
        </section>
		<section id="creating">
			<title>Creating a Shared Flow</title>
			<p>To create a shared flow controller class:</p>
			<ol>
                <li>
                    add the
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
                        <code>@Jpf.Controller</code>
                    </a>
                    annotation to the class, and
                </li>
				<li>
                    extend the
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/SharedFlowController.html"><code>SharedFlowController</code></a>
                    class.
                </li>
			</ol>
            <p>For example:</p>
			<source>
import org.apache.beehive.netui.pageflow.annotations.Jpf; 
import org.apache.beehive.netui.pageflow.SharedFlowController; 
				
<strong>@Jpf.Controller</strong> 
public class MySharedFlow extends <strong>SharedFlowController</strong> 
{ 
    ... 
}</source>
            <p>
                You can add <a href="site:docs/pageflow/netuiBasic/actions">actions</a> and
                <a href="site:docs/pageflow/netuiBasic/exceptionHandling">exception handling</a> just like you would in
                a page flow controller.
            </p>
		</section>
        <section id="referencing">
			<title>Referencing Shared Flows from Page Flows</title>
            <p>
                To share actions, exception handlers, and state from a shared flow, a page flow needs to <em>declare a
                reference</em> in its controller class, using the
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SharedFlowRef.html">
                    <code>@Jpf.SharedFlowRef</code>
                </a>
                annotation. The following example shows two shared flow references being declared for page flow
                controller <code>SomeController</code>:
            </p>
            <source>
@Jpf.Contoller(
    sharedFlowRefs={
        @Jpf.SharedFlowRef(name="sharedFlowOne", type=example.SharedFlowClassOne.class),
        @Jpf.SharedFlowRef(name="sharedFlowTwo", type=example.SharedFlowClassTwo.class)
    }
)
public class SomeController extends PageFlowController</source>
            <p>
                Notice that this declaration <em>assigns a name</em> to each referenced shared flow. This name will be
                used throughout the page flow to shared actions and state. Throughout this document, we will refer to
                this as the <strong>shared flow name</strong>.
            </p>
        </section>

        <section id="sharingActions">
            <title>Shared Actions</title>
            <p>
                You can raise Shared Flow actions through NetUI JSP tags, through components/command-handlers in
                JavaServer Faces pages, from other actions in the same page flow, or, in general, through URLs.
                Basic instructions for raising actions can be found
                <a href="site:docs/pageflow/netuiBasic/actions/raising">here</a>.  <strong>The only difference between
                raising a shared flow action and raising a normal action is that you include the shared flow name along with
                the action name.</strong>  For example, the following JSP tag raises <code>someAction</code> on
                <code>example.SharedFlowClassOne</code>:
            </p>
            <source>
    &lt;netui:anchor action="sharedFlowOne.someAction"/></source>
            <p>
                Notice that the pattern is <strong><em>shared-flow-name</em><code>.</code><em>action-name</em></strong>. As
                another example, the following page flow action (part of <code>SomeController</code> in the above example)
                raises action <code>anotherAction</code> on <code>example.ShardFlowClassTwo</code>:
            </p>
            <source>
@Jpf.Action(
    forwards={
        @Jpf.Forward(name="sharedAction", action="sharedFlowTwo.anotherAction")
    }
)
public Forward doSharedAction()
{
    return new Forward("sharedAction");
}           </source>
            <p>
                You always use the shared flow <em>name</em>, not its classname, to refer to it. This allows page flows
                to choose their own namespaces for shared flow actions, thus avoiding conflicts in action names.
            </p>
        </section>
        <section id="exceptionHandling">
            <title>Shared Flow Exception Handling</title>
            <p>
                When an exception occurs and your page flow does not handle it (using
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Catch.html">
                    <code>@Jpf.Catch</code>
                </a>), <em>every referenced shared flow gets a chance to handle it</em>.  The list of
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SharedFlowRef.html">
                    <code>@Jpf.SharedFlowRef</code>
                </a>
                annotations is traversed in order, and the first shared flow with a matching <code>@Jpf.Catch</code>
                handles the exception.
            </p>
            <p>
                For more information on exception handling, see
                <a href="site:docs/pageflow/netuiBasic/exceptionHandling">this document</a>.
            </p>
        </section>
        <section id="databinding">
            <title>Databinding to Shared Flow Properties</title>
            <p>
                If your shared flow controller exposes properties, you can databind to those properties from JSPs or from
                JavaServer Faces pages, using the <code>sharedFlow</code> implicit object.  The basic pattern is:
                <strong><code>sharedFlow.</code><em>shared-flow-name</em><code>.</code><em>property-name</em></strong>.
                For example, the following JSP fragment displays the value of the <code>someProperty</code> property on
                <code>example.SharedFlowClassOne</code> (for the page flow definition, see the example in
                <a href="#referencing">Referencing</a>, above):
            </p>
            <source>
This is the value: ${sharedFlow.sharedFlowOne.someProperty}</source>
            <p>
                To be clear, what will be shown is the result of a method <code>getSomeProperty</code> on class
                <code>example.SharedFlowClassOne</code>.  In another example, the following text box pushes a value into
                the <code>writableProperty</code> property when its form is submitted:
            </p>
            <source>
Edit this: &lt;netui:textBox dataSource="sharedFlow.sharedFlowOne.writableProperty"/></source>
            <p>
                Of course, you can do the same kind of binding from JavaServer Faces pages, using the JSF Expression
                Language:
            </p>
            <source>
&lt;h:panelGrid rendered="#{sharedFlow.sharedFlowOne.showDetails}">
    ...     </source>
            <p>
                In that example, a <code>panelGrid</code> component decides whether to be rendered based on the value of
                the <code>showDetails</code> property in <code>example.SharedFlowOneClass</code>
            </p>
        </section>
        <section id="accessingDirectly">
            <title>Accessing a Shared Flow Directly</title>
            <p>
                If you want, you can declare a member variable in your page flow controller which will be automatically
                initialized with a reference to a shared flow controller. This is <em>optional</em>; you do not have to
                do this in order to use a shared flow controller.  If you do want to access the shared flow controller
                object directly, you annotate a member field using the
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SharedFlowField.html">
                    <code>@Jpf.SharedFlowField</code>
                </a>
                annotation. For example, the following page flow controller gets its <code>mySharedFlow</code> field
                automatically initialized:
            </p>
            <source>
@Jpf.Contoller(
    sharedFlowRefs={
        @Jpf.SharedFlowRef(name="sharedFlowOne", type=example.SharedFlowClassOne.class)
    }
)
public class SomeController extends PageFlowController
{
    @Jpf.SharedFlowField(name="sharedFlowOne")
    private example.SharedFlowClassOne mySharedFlow;
}           </source>
            <p>
                Note that you use the <em>name</em> of the shared flow reference in order to initialize the field. Once
                you have done this, you can use the shared flow controller object in any way you like (access its state,
                call methods, etc.).
            </p>
        </section>
	</body>
</document>
