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/05/16 07:58:37 UTC
svn commit: r170317 - in
/incubator/beehive/trunk/netui/src/pageflow/org/apache/beehive/netui/pageflow:
PageFlowController.java SharedFlowController.java annotations/Jpf.java
interceptor/action/ActionInterceptor.java
interceptor/action/ActionInterceptorContext.java
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 {@link 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
+ * {@link 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 {@link #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/>
+ * validationErrorForward=@Jpf.Forward(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), {@link 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 {@link org.apache.struts.util.TokenProcessor} before the action is
- * run. If <code>isTokenValid</code> returns <code>false</code>, then a
- * {@link 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 {@link 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
+ * {@link Action}.
+ *
* @see Action
*/
@Target( ANNOTATION_TYPE )
@@ -511,9 +547,16 @@
boolean doValidation() default false;
/**
+ * <p>
* The name of a class-level forward (a {@link Forward} in {@link Controller#forwards}) which will serve as the
* destination for this simple action. Mutually-exclusive with with {@link #action}, {@link #path},
* {@link #navigateTo}, {@link #returnAction}, and {@link #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 {@link org.apache.struts.util.TokenProcessor} before the action is
- * run. If <code>isTokenValid</code> returns <code>false</code>, then a
- * {@link 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 {@link 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 {@link 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 {@link Forward} annotation and passed on a
- * {@link 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 {@link Jpf.Forward @Jpf.Forward} annotation and passed from an action
+ * method on a {@link 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
* {@link org.apache.beehive.netui.pageflow.SharedFlowController}. The annotation is valid within a page flow
- * or a JavaServer Faces backing class.
+ * ({@link org.apache.beehive.netui.pageflow.PageFlowController} or a JavaServer Faces backing bean
+ * {@link org.apache.beehive.netui.pageflow.FacesBackingBean}.
*/
@Target( FIELD )
@Retention( RUNTIME )
public @interface SharedFlowField
{
/**
- * The name of the shared flow, as declared in {@link SharedFlowRef#name()}
+ * The name of the shared flow, as declared in {@link SharedFlowRef#name} on {@link 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, {@link #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,
- * {@link #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>
*
* {@link 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 {@link InterceptorForward} that changes the destination URI of the intercepted action. If the
- * InterceptorForward points to a nested page flow, then {@link ActionInterceptor#afterNestedIntercept} will be
- * called before the nested page flow returns to the original page flow.
- */
+ * Set an {@link InterceptorForward} that changes the destination URI of the intercepted action. If the
+ * InterceptorForward points to a nested page flow, then {@link 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 );