Author: steveh
Date: Wed Mar 9 16:04:37 2005
New Revision: 156715
URL: http://svn.apache.org/viewcvs?view=rev&rev=156715
Log:
Adding topic on shared flows.
Added:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sharedFlow.xml
(with props)
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml
Added:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sharedFlow.xml
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sharedFlow.xml?view=auto&rev=156715
==============================================================================
---
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sharedFlow.xml
(added)
+++
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sharedFlow.xml
Wed Mar 9 16:04:37 2005
@@ -0,0 +1,165 @@
+<?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. You
can have multiple
+ shared flows, each with different delegated
functions. For
+ example, you might have one shared flow
specifically for
+ handling exceptions, and another shared flow to
provides common
+ data resources.</p>
+ <p>Shared flows can reside anywhere in your web app,
and can be
+ invoked from other controller files or from JSP
files.</p>
+ </section>
+ <section id="declaring">
+ <title>Creating a Shared Flow</title>
+ <p>To create a shared flow controller file</p>
+ <ol>
+ <li> decorate the class with the @Controller
annotation </li>
+ <li> extend the SharedFlowController class</li>
+ </ol>
+ <source>import
org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.SharedFlowController;
+
+<strong>@Jpf.Controller</strong>
+public class SharedFlow extends <strong>SharedFlowController</strong>
+{
+
+ ...
+
+}</source>
+ </section>
+ <section><title>Adding Actions and Data to a Shared Flow</title>
+ <p>Shared flows have all of capabilities of other
controller files.
+ They can contain</p>
+ <ol>
+ <li>ordinary Java methods</li>
+ <li>simple actions (actions defined by
the @Jpf.SimpleAction annotation)</li>
+ <li>action methods (methods decorated
with the @Jpf.Action annotation)</li>
+ <li>exception handling code (via the
@Jpf.Catch annotation)</li>
+ <li>common data</li>
+ <li>and other sorts of
functionality...</li>
+ </ol>
+ <p>Suppose you wanted a common handler for the generic
<code>Exception.class</code>
+ whenever and wherever
+ it is thrown in your web app. To add this sort
of exception handling, you would
+ (1) add a @Jpf.Catch annotation and (2) add the
appropriate exception handling method
+ to the shared flow. You could, of course, add
the same code to each controller file
+ in your application, but that would make for
redundant code. By adding the exception
+ handling code to the shared flow, you have a
centralized, non-redundant way to handle
+ a given exception type whenever it arises.</p>
+ <p>The @Jpf.Catch annotation appears as an
attribute of the parent @Jpf.Controller
+ annotation. The @Jpf.Catch annotation
added below means, roughly, "When
+ the exception
<code>Exception.class</code> is thrown, invoke the method
+ <code>handleGenericException</code> to
handle it."</p>
+ <source>import
org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.SharedFlowController;
+
[EMAIL PROTECTED](
+ <strong>catches={
+ @Jpf.Catch(method="handleGenericException", type=Exception.class)
+ }</strong>
+)
+public class SharedFlow extends SharedFlowController
+{
+
+ ...
+
+}</source>
+<p>The exception handling method appears as a method decorated with the
+ <code>@Jpf.ExceptionHandler</code> annotation.</p>
+ <source>import
org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.SharedFlowController;
+
[EMAIL PROTECTED](
+ catches={
+ @Jpf.Catch(method="handleGenericException", type=Exception.class)
+ }
+)
+public class SharedFlow extends SharedFlowController
+{
+ <strong>
+ @Jpf.ExceptionHandler(
+ forwards={
+ @Jpf.Forward(name="errorPage", path="/error.jsp")
+ }
+ )
+ protected Forward handleException(Exception ex, String actionName, String
message, Object form) {
+ // ...other error handling code here...
+ return new Forward("errorPage");
+ }</strong>
+
+}</source>
+ </section>
+ <section>
+ <title>Invoking Shared Flows from Other Controller
Files</title>
+ <p>To invoke the functionality of shared flow, it must
first be declared on the
+ invoking resource. To declared a shared flow
on another controller file,
+ 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")
+ }
+)
+public class SomeController extends Controller
+</source>
+ <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")
+ }
+)
+public class SomeController extends Controller
+{
+
+ @Jpf.SharedFlowField(name="sharedFlowOne")
+ private SharedFlowClassOne _sharedFlowOne = null;
+
+}
+</source>
+<p>You will recieve a compiler error if you annotate a member field as a
shared flow
+ (with @Jpf.SharedFlowField) without having first declared the
+ shared flow in the Controller annotation (with @Jpf.SharedFlowRef).</p>
+
+<p>Now you can invoke the resources within the shared flow. For example, to
invoke the
+ shared flow's <code>handleLogout()</code> method, do the following:</p>
+ <source> _sharedFlowOne.handleLogout();</source>
+
+ </section>
+ <section>
+ <title>Invoking Shared Flows from JSP Pages</title>
+ <p>Shared flow resources can be accessed from a JSP
using the scope <code>sharedFlow</code>,
+ for example,</p>
+
+ <source><netui-data:repeater
dataSource="sharedFlow.specificSharedFlow.someData"></source>
+
+<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>
+
+<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")
+
[EMAIL PROTECTED](name="specificSharedFlow")
+ </source>
+ </section>
+ <section>
+ <title>Example Code</title>
+ <p>See the shared flow controller file in the PetStore
sample,
+ located at
<code>BEEHIVE_HOME/samples/petstoreWeb/webappRoot/SharedFlow.jpfs</code></p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/pageflow/sharedFlow.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml?view=diff&r1=156714&r2=156715
==============================================================================
---
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml
(original)
+++
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/site.xml
Wed Mar 9 16:04:37 2005
@@ -19,6 +19,7 @@
<pageflow_jsp label="JSP Files" href="pageflow/pageflow_jsp.html"/>
<pageflow_building label="Building a Web-App"
href="pageflow/pageflow_building.html"/>
<pageflow_altering label="Altering a Page Flow"
href="pageflow/pageflow_altering.html"/>
+ <pageflow_sharedFlow label="Shared Flow"
href="pageflow/sharedFlow.html"/>
<pageflow_programming label="Page Flow Programming"
href="pageflow/guide.html"/>
</pageflow>
<controls label="Controls">
