Re: [jira] Assigned: (BEEHIVE-525) Need JavaDoc for the Jpf annotation interface

[Richard Feit <rf...@bea.com>]

Thanks for all the feedback, Jeremiah.  I think I've hit everything 
here, except the stuff I've commented (inline, below).

Jeremiah Johnson (JIRA) wrote:

>     [ http://issues.apache.org/jira/browse/BEEHIVE-525?page=all ]
>
>Jeremiah Johnson reassigned BEEHIVE-525:
>----------------------------------------
>
>    Assign To: Rich Feit  (was: Jeremiah Johnson)
>
>I am looking at revision 165313 - the docs are helpful.  Thanks for the updates.  Here are some more comments - please consider them before closing the bug.
>
>Action
>-	add to summary: In some cases, the begin action or some action that is used on a return from a nested page flow doesn't have any logic; an action is required, but it just returns a static forward.  In those cases, you would use a SimpleAction instead of an action.
>-	add to summary: Nearly every action will have a list of forwards.
>-	add an example
>-	preventDoubleSubmit provides irrelevant technical detail - change it to something like this: Use a session-scoped token to prevent multiple submits to this action.  This is a server-side solution that protects the server from double processing; however, it is still a good idea to supplement this with a client-side solution to physically prevent double-submits.  When the server detects a double submit on the token, then a DoubleSubmitException is thrown.
>
>ActionOuptut
>-	the summary isn't clear to me; is that accurate about the ConditionalForward?  I would suggest something like this: A defined action output that may be used as a 'page input' in a page (accessed by databinding to ${pageInput.action-output-name}.  The benefit of action outputs (over setting request attributes) is that you get compile and runtime checking with the action outputs.
>  
>
Weird -- that was a javadoc bug.  I had {@link Forward}, but it created 
a link to ConditionalForward.  I made another attempt -- comments welcome.

>Controller
>-	add note in summary that there may be only one class with the Controller annotation per package
>  
>
There can actually be both a page flow and a shared flow in a package.  
I've added the only-one restriction to the docs for PageFlowController 
and SharedFlowController.

>-	rearrange the sentence for the longLived summary so the current second sentence is first
>
>SharedFlowField
>-	I don't think that the summary is accurate because I don't think that the SharedFlowField can exist withouth a SharedFlowRef; therefore, it isn't really automatic; does this sound okay: An annotation that identifies a field as the reference to a SharedFlowController.  The annotation initializes the field based on the matching shared flow reference in the controller annotation.  A SharedFlowField is only needed if some code needs to explicitly access something in the shared flow (as opposed to some other annotation referring to the shared flow).
>
>  
>
I didn't totally understand the concern you had about "automatic" -- 
let's talk about it in person (or IM -- richfeit@YIM).  I did update the 
description...

>SimpleAction
>-	add something like this to the summary: If you need an action but there is no logic within the action, then you will use a SimpleAction rather than an Action.
>-	add something like this to forwardRef: If the simple action is a return from a popup, then you will use the special value of _auto.
>
>
>  
>
>>Need JavaDoc for the Jpf annotation interface
>>---------------------------------------------
>>
>>         Key: BEEHIVE-525
>>         URL: http://issues.apache.org/jira/browse/BEEHIVE-525
>>     Project: Beehive
>>        Type: Bug
>>  Components: NetUI
>>    Versions: V1, V1Alpha, V1Beta
>>    Reporter: Rich Feit
>>    Assignee: Rich Feit
>>     Fix For: V1
>>    
>>
>
>  
>
>>The JavaDoc in org.apache.beehive.netui.pageflow.annotations.Jpf is incomplete (to say it kindly).
>>    
>>
>
>  
>