Author: rich
Date: Sun May 15 22:58:36 2005
New Revision: 170317
URL: http://svn.apache.org/viewcvs?rev=170317&view=rev
Log:
JavaDoc updates, mainly to the Jpf annotation interface based on feedback from
Jeremiah.
tests: bvt in netui (WinXP)
BB: self (linux)
Modified:
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/PageFlowController.java
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/SharedFlowController.java
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/annotations/Jpf.java
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptor.java
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptorContext.java
Modified:
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/PageFlowController.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/PageFlowController.java?rev=170317&r1=170316&r2=170317&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/PageFlowController.java
(original)
+++
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/PageFlowController.java
Sun May 15 22:58:36 2005
@@ -92,6 +92,10 @@
* <code>${pageFlow.someProperty}</code>.
* </p>
*
+ * <p>
+ * There may only be one page flow in any package.
+ * </p>
+ *
* @see SharedFlowController
*/
public abstract class PageFlowController
Modified:
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/SharedFlowController.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/SharedFlowController.java?rev=170317&r1=170316&r2=170317&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/SharedFlowController.java
(original)
+++
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/SharedFlowController.java
Sun May 15 22:58:36 2005
@@ -77,6 +77,10 @@
* <code>${sharedFlow.</code><i>sharedFlowName</i><code>.someProperty}</code>.
* </p>
*
+ * <p>
+ * There may only be one shared flow in any package.
+ * </p>
+ *
* @see PageFlowController
*/
public abstract class SharedFlowController
Modified:
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/annotations/Jpf.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/annotations/Jpf.java?rev=170317&r1=170316&r2=170317&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/annotations/Jpf.java
(original)
+++
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/annotations/Jpf.java
Sun May 15 22:58:36 2005
@@ -123,10 +123,10 @@
boolean loginRequired() default false;
/**
- * Only valid for
{org.apache.beehive.netui.pageflow.PageFlowController}s. If set to
<code>true</code>, then
- * this page flow does not get discarded when another page flow is
hit. It ramains stored in the background,
- * and is reinstated when it is requested again. Long-lived page
flows may be deleted using
- *
{org.apache.beehive.netui.pageflow.PageFlowUtils#removedLongLivedPageFlow}.
+ * If set to <code>true</code>, then this page flow does not get
discarded when another page flow is hit
+ * (only valid for [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.PageFlowController}s). It ramains stored in
the
+ * background, and is reinstated when it is requested again.
Long-lived page flows may be deleted using
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.PageFlowUtils#removedLongLivedPageFlow}.
*/
boolean longLived() default false;
@@ -367,8 +367,34 @@
}
/**
+ * <p>
* Method-level annotation that configures an action method. This
annotation is required for a method to be
- * recognized as an action.
+ * recognized as an action. Nearly every action will define a list of
forwards through the [EMAIL PROTECTED] #forwards}
+ * attribute. An example of an action method is shown below:
+ * <blockquote>
+ * <code>
+ * @Jpf.Action(<br/>
+ * forwards={<br/>
+ *
@Jpf.Forward(name="page1",
page="page1.jsp"),<br/>
+ *
@Jpf.Forward(name="page2",
page="page2.jsp")<br/>
+ * },<br/>
+ * [EMAIL PROTECTED](name="failure",
navigateTo=Jpf.NavigateTo.currentPage)<br/>
+ * )<br/>
+ * public Forward someAction(MyFormBean bean)<br/>
+ * {<br/>
+ * if (...)<br/>
+ * return new
Forward("page1");<br/>
+ * else<br/>
+ * return new
Forward("page2");<br/>
+ * }
+ * </code>
+ * </blockquote>
+ * </p>
+ * <p>
+ * For actions that do not require Java code (for example, a begin action
that simply
+ * forwards to a particular page), [EMAIL PROTECTED] SimpleAction} can be
used instead.
+ * </p>
+ *
* @see SimpleAction
*/
@Target( METHOD )
@@ -403,10 +429,16 @@
boolean loginRequired() default false;
/**
- * Use a session-scoped token to prevent multiple submits to this
action. If this value is set to true, then
- * <code>isTokenValid</code> is called on [EMAIL PROTECTED]
org.apache.struts.util.TokenProcessor} before the action is
- * run. If <code>isTokenValid</code> returns <code>false</code>, then
a
- * [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.DoubleSubmitException} is thrown.
+ * <p>
+ * Use a session-scoped token to prevent multiple submits to this
action. When the server detects a double
+ * submit on the token, a [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.DoubleSubmitException} is thrown.
+ * </p>
+ * <p>
+ * This is a server-side solution that guards against double
processing; however, it is still a good
+ * idea to supplement this with a client-side solution to prevent
double-submits from happening in the first
+ * place (an example of this is the <code>disableSecondClick</code>
attribute on the NetUI Button tag, which
+ * disables the button through JavaScript as soon as it is pressed).
+ * </p>
*/
boolean preventDoubleSubmit() default false;
@@ -471,7 +503,11 @@
}
/**
- * A "simple" action, which defines its behavior wholly through an
annotation, rather than through a method.
+ * A "simple" action, which defines its behavior wholly through an
annotation, rather than through a method. This
+ * is useful when an action does not require any Java code to run (for
example, a begin action that simply forwards
+ * to a particular page). Actions that <i>do</i> require Java code are
built using methods annotated with
+ * [EMAIL PROTECTED] Action}.
+ *
* @see Action
*/
@Target( ANNOTATION_TYPE )
@@ -511,9 +547,16 @@
boolean doValidation() default false;
/**
+ * <p>
* The name of a class-level forward (a [EMAIL PROTECTED] Forward} in
[EMAIL PROTECTED] Controller#forwards}) which will serve as the
* destination for this simple action. Mutually-exclusive with with
[EMAIL PROTECTED] #action}, [EMAIL PROTECTED] #path},
* [EMAIL PROTECTED] #navigateTo}, [EMAIL PROTECTED] #returnAction},
and [EMAIL PROTECTED] #tilesDefinition}.
+ * </p>
+ * <p>
+ * If this simple action handles the return from a nested page flow
that was shown in a popup window, then
+ * the <code>forwardRef</code> attribute can be set to the special
value "_auto". This causes the framework to
+ * write out the correct javascript to close the popup window instead
of forwarding to another page.
+ * </p>
*/
String forwardRef() default "";
@@ -526,10 +569,16 @@
boolean loginRequired() default false;
/**
- * Use a session-scoped token to prevent multiple submits to this
action. If this value is set to true, then
- * <code>isTokenValid</code> is called on [EMAIL PROTECTED]
org.apache.struts.util.TokenProcessor} before the action is
- * run. If <code>isTokenValid</code> returns <code>false</code>, then
a
- * [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.DoubleSubmitException} is thrown.
+ * <p>
+ * Use a session-scoped token to prevent multiple submits to this
action. When the server detects a double
+ * submit on the token, a [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.DoubleSubmitException} is thrown.
+ * </p>
+ * <p>
+ * This is a server-side solution that guards against double
processing; however, it is still a good
+ * idea to supplement this with a client-side solution to prevent
double-submits from happening in the first
+ * place (an example of this is the <code>disableSecondClick</code>
attribute on the NetUI Button tag, which
+ * disables the button through JavaScript as soon as it is pressed).
+ * </p>
*/
boolean preventDoubleSubmit() default false;
@@ -781,10 +830,6 @@
String action() default "";
/**
- * Array of action outputs (name/type) that will be passed along with
this forward. Action outputs are used
- * within a page by databinding to
<code>${pageInput.</code><i>action-output-name</i><code>}</code>.
- */
- /**
* Array of action output declarations to be associated with this
Forward. An actual action output is passed on
* a [EMAIL PROTECTED] org.apache.beehive.netui.pageflow.Forward}
object. An action output supplies a "page input" in a
* page, where it is accessed by databinding to
@@ -859,9 +904,12 @@
}
/**
- * An action output, which is declared in a [EMAIL PROTECTED] Forward}
annotation and passed on a
- * [EMAIL PROTECTED] org.apache.beehive.netui.pageflow.Forward} object.
An action output supplies a "page input" in a page,
- * where it is accessed by databinding to
<code>${pageInput.</code><i>action-output-name</i><code>}</code>.
+ * An action output, which is declared in a [EMAIL PROTECTED] Jpf.Forward
@Jpf.Forward} annotation and passed from an action
+ * method on a [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.Forward} object. An action output may be
used as a
+ * "page input" in a page, where it is accessed by databinding to
+ * <code>${pageInput.</code><i>action-output-name</i><code>}</code>. The
benefit of action outputs (over setting
+ * request attributes) is that the annotations are visible to tools, and
that there is runtime checking of type and
+ * required-presence.
*/
@Target( ANNOTATION_TYPE )
@Retention( RUNTIME )
@@ -1665,14 +1713,15 @@
/**
* An annotation that causes a field to get automatically initialized with
a reference to a
* [EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.SharedFlowController}. The annotation is
valid within a page flow
- * or a JavaServer Faces backing class.
+ * ([EMAIL PROTECTED]
org.apache.beehive.netui.pageflow.PageFlowController} or a JavaServer Faces
backing bean
+ * [EMAIL PROTECTED] org.apache.beehive.netui.pageflow.FacesBackingBean}.
*/
@Target( FIELD )
@Retention( RUNTIME )
public @interface SharedFlowField
{
/**
- * The name of the shared flow, as declared in [EMAIL PROTECTED]
SharedFlowRef#name()}
+ * The name of the shared flow, as declared in [EMAIL PROTECTED]
SharedFlowRef#name} on [EMAIL PROTECTED] Controller}.
*/
String name();
}
Modified:
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptor.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptor.java?rev=170317&r1=170316&r2=170317&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptor.java
(original)
+++
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptor.java
Sun May 15 22:58:36 2005
@@ -24,7 +24,7 @@
/**
- * Base class for page flow action interceptors. These are configured in
/WEB-INF/beehive-netui-config.xml like this:
+ * Base class for Page Flow action interceptors. These are configured in
/WEB-INF/beehive-netui-config.xml like this:
* <pre>
* <netui-config
xmlns="http://beehive.apache.org/netui/2004/server/config">
* ...
@@ -123,14 +123,8 @@
* action has run. During this method, [EMAIL PROTECTED]
#setOverrideForward} may be called to:
*
* <ul>
- * <li>change the destination URI and thus prevent the action from
running, or,</li>
- * <li>set the destination URI to <code>null</code> (no forwarding)
and thus prevent the action from running, or,</li>
- * <li>
- * "inject" an entire nested page flow to run before the action is
invoked. If the override forward URI
- * is a nested page flow, then it will run until it raises one of
its return actions. At that point,
- * [EMAIL PROTECTED] #afterNestedIntercept} is called on <i>this
interceptor</i>, which can again choose to override
- * the forward or allow the original action to run.
- * </li>
+ * <li>change the destination URI that was returned by the action,
or,</li>
+ * <li>set the destination URI to <code>null</code> (no
forwarding).</li>
* </ul>
*
* [EMAIL PROTECTED] InterceptorChain#continueChain} is called to invoke
the rest of the
Modified:
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptorContext.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptorContext.java?rev=170317&r1=170316&r2=170317&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptorContext.java
(original)
+++
incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow/interceptor/action/ActionInterceptorContext.java
Sun May 15 22:58:36 2005
@@ -92,11 +92,10 @@
}
/**
- *
- * Set an [EMAIL PROTECTED] InterceptorForward} that changes the
destination URI of the intercepted action. If the
- * InterceptorForward points to a nested page flow, then [EMAIL
PROTECTED] ActionInterceptor#afterNestedIntercept} will be
- * called before the nested page flow returns to the original page flow.
- */
+ * Set an [EMAIL PROTECTED] InterceptorForward} that changes the
destination URI of the intercepted action. If the
+ * InterceptorForward points to a nested page flow, then [EMAIL PROTECTED]
ActionInterceptor#afterNestedIntercept} will be
+ * called before the nested page flow returns to the original page flow.
+ */
public void setOverrideForward( InterceptorForward fwd, ActionInterceptor
interceptor )
{
setResultOverride( fwd, interceptor );
