Author: steveh Date: Tue Aug 31 15:54:21 2004 New Revision: 37268 Added: incubator/beehive/trunk/netui/docs/guide/reference/jpf/action-output.html (contents, props changed) Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/action.html incubator/beehive/trunk/netui/docs/guide/reference/jpf/catch.html incubator/beehive/trunk/netui/docs/guide/reference/jpf/controller.html incubator/beehive/trunk/netui/docs/guide/reference/jpf/exception-handler.html incubator/beehive/trunk/netui/docs/guide/reference/jpf/forward.html incubator/beehive/trunk/netui/docs/guide/reference/jpf/message-resources.html incubator/beehive/trunk/netui/docs/guide/reference/jpf/navJpfAnnotations.html incubator/beehive/trunk/netui/docs/guide/reference/jpf/simple-action.html Log: Latest content for JPF annotation reference.
Added: incubator/beehive/trunk/netui/docs/guide/reference/jpf/action-output.html ============================================================================== --- (empty file) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/action-output.html Tue Aug 31 15:54:21 2004 @@ -0,0 +1,175 @@ +<!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN"> + +<html> +<head> +<title>@Jpf.ActionOutput Annotation</title> +<!--(Meta)==========================================================--> +<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;"> +<meta name=workshop content=WWKSHOP> +<meta name="revision" content="$Revision: #2 $"> +<meta name="date" content="$Date: 2004/06/25 $"> +<!-- In the component metatag, please indicate whether this topic is for Integration, Workshop, or Portal. --> +<meta name="component" content="Workshop"> +<!-- In the description metatag, please provide a BRIEF description of the topic contents. --> +<meta name="description" content="@jpf:action Annotation reference for page flows"> +<!-- In the component metatag, please list keywords that will help a user search for this topic. --> +<meta name="keywords" content="@jpf:action Annotation reference page flows"> +<!--(Links)=========================================================--> +<link href="../../beehive.css" rel="stylesheet" type="text/css"> +</head> +<!--(Body)==========================================================--><body> +<div id="topictitle"> + <h1>@Jpf.ActionOutput Annotation</h1> +</div> +<div id="topictext"> + <p>The <span class="langinline">@Jpf.ActionOutput</span> annotation defines + the data returned by an Action method. Use the @Jpf.ActionOutput in conjunction + with a databindable JSP tag, such as <a href="../taglib/beehive.apache.org/netui/tags-html-1.0/span.html"><neuti:span></a> + or <a href="../taglib/beehive.apache.org/netui/tags-databinding-1.0/repeater.html"><netui-data:repeater></a>, + to display the data on a JSP page.</p> + <h2><strong>Reading Data from the <code>pageInput</code> Databinding Context</strong></h2> + <p>The @Jpf.ActionOutput annotation writes the data to the <code>pageInput</code> + databinding context, from which JSP pages can read the data using a databinding + expression. To read the data, refer to the <code>@Jpf.ActionOutput</code>'s + <code>name</code> attribute. For example, the following <code>@Jpf.ActionOutput</code> + annotation defines <code>String</code> data output with the name <code>myStringData</code>.</p> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + actionOutputs={ @Jpf.ActionOutput(<font color="#000000">name</font>="<font color="#FF0000">myStringData</font>", type=String.class) }, + navigateTo = Jpf.NavigateTo.currentPage) + } + ) +</pre> + <p>To read the data, refer to it with the databinding expression <code>pageInput.myStringData</code>. + For example,</p> + <pre> <netui:span value="${<font color="#FF0000">pageInput.myStringData</font>}"/></pre> + <h2><strong>Writing Data to the <code>pageInput</code> Databinding Context</strong></h2> + <p>The data is loaded into the <code>pageInput.xxx</code> databinding context + through either the Forward constructor</p> + <p> <code>Forward(String forwardName, String actionOutputName, + Object actionOutputValue)</code> </p> + <p>or through the Forward method</p> + <p> <code>addActionOutput(String actionOutputName, Object + actionOutputValue)</code> </p> + <p><strong>Using the Forward Contructor</strong></p> + <p>The following example shows how to load data into the <code>pageInput</code> + databinding context using the Forward constructor <code>Forward(String, Object)</code>. + The constructor loads the String data into the databinding context <code>pageInput.myStringData</code>.</p> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + actionOutputs={ @Jpf.ActionOutput(name="myStringData", type=String.class) }, + navigateTo = Jpf.NavigateTo.currentPage + ) + } + ) + protected Forward stringOutput() + { + <font color="#FF0000">return new Forward( "success", "myStringData", "--- String Value ---" );</font> + }</pre> + <p><strong>Using the Method add </strong></p> + <p>The following example shows how to load data into the <code>pageInput</code> + databinding context using the Forward constructor <code>Forward(String, Object)</code>. + The constructor loads the String data into the databinding context <code>pageInput.myStringData</code>.</p> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + actionOutputs={ @Jpf.ActionOutput(name="myStringData", type=String.class) }, + navigateTo = Jpf.NavigateTo.currentPage + ) + } + ) + protected Forward stringOutput() + { + Forward fwd = new Forward("success"); + <font color="#FF0000">fwd.addPageInput( "myStringData", "--- String Value ---" );</font> + return fwd; + }</pre> + <h2>Class and Method Scopings</h2> + <p>@Jpf.ActionOutput can be either class-scoped or method-scoped. A class-scoped + @Jpf.ActionOutput annotation decorates the class signature, as shown below.</p> + <p><strong>A Class-Scoped <code>@Jpf.ActionOutput</code> Annotation</strong></p> + <pre>@Jpf.Controller( + forwards = { + @Jpf.Forward( + name = "stringArray", + [EMAIL PROTECTED](name="stringArray", type=String[].class)}, + navigateTo = Jpf.NavigateTo.currentPage + ) + } +) +public class MyPageFlowController extends PageFlowController +{ + ... +} +</pre> + <p>A method-scoped @Jpf.ActionOutput annotation decorates the method signature, + as shown below.</p> + <p><strong>A Method-Scoped <code>@Jpf.ActionOutput</code> Annotation</strong> + </p> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + actionOutputs={ @Jpf.ActionOutput(name="string", type=String.class) }, + navigateTo = Jpf.NavigateTo.currentPage) + } + ) + protected Forward myStringData() + { + ... + }</pre> + <p>If the annotation is class-scoped, then any method in the class can be used + to write data to the <code>pageInput.xxx</code> databinding context. The following + example shows a class-scoped annotation, along with a method that writes to + the <code>pageInput.goodArray</code> databinding context.</p> + <pre>@Jpf.Controller( + forwards = { + @Jpf.Forward( + name = "globalSuccessGood", + [EMAIL PROTECTED](name="<font color="#FF0000">goodArray</font>", type=String[].class)}, + navigateTo = Jpf.NavigateTo.currentPage) + ) + } +) +public class PageInputController extends PageFlowController +{ + @Jpf.Action() + protected Forward returnArray() + { + return new Forward( "globalSuccessGood", "<font color="#FF0000">goodArray</font>", new String[]{ "String Value 1", "String Value 2" } ); + } +} +</pre> + <h2>Syntax</h2> + <pre><strong> + @Jpf.ActionOutput( + <a href="#form">name</a> = "<em>name</em>", + <a href="#nullable">nullable</a> = <em>boolean,</em> + <a href="#type">type</a> = <em>JavaType</em> + )</strong></pre> + <h2>Attributes</h2> + <p class="attribute"><a name="form" id="form"></a>name</p> + <p class="partdesc">Optional. </p> + <p class="attribute"><a name="nullable" id="nullable"></a>nullable</p> + <p class="partdesc">Optional. </p> + <p class="attribute"><a name="type" id="type"></a>type</p> + <p class="partdesc">Optional. </p> + <h2><a name="remarks"></a>Remarks</h2> + <p>Note that @Jpf.ActionOutput is not a standalone annotation, instead it must + be used within a <a href="forward.html">@Jpf.Forward</a> annotation.</p> + <p class="relatedtopics">Related Topics</p> + <p><a href="catch.html">@Jpf.Catch Annotation</a></p> + <p><a href="controller.html">@Jpf.Controller Annotation</a></p> + <p><a href="exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> + <p><a href="forward.html">@Jpf.Forward Annotation</a></p> + <p><a href="message-resources.html">@Jpf.MessageResources Annotation</a></p> + <h3>Samples</h3> + <p> </p> +</div> +</body> +</html> Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/action.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/action.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/action.html Tue Aug 31 15:54:21 2004 @@ -38,124 +38,125 @@ displayInFrames(); </script> <!-- InstanceBeginEditable name="body" --> -<div id="topictitle"> +<div id="topictitle"> <h1 class="Title">@Jpf.Action Annotation</h1> </div> <div id="topictext"> - <p>You can use the <span class="langinline">@Jpf.Action</span> annotation to - designate an action method in a page flow. Action methods in a page flow perform - control logic, such as forwarding the user to a new JSP or another page flow. - Optionally, you can cause an action to read and update from a <span class="langinline">FormData</span> - (or <span class="langinline">ActionForm</span>) member variable; set login - requirements for users; or indicate that the action method will not update - any member data in the page flow. </p> - <p>For information about the method signatures of an action method, see the - <a href="forward.html">@jpf:forward Annotation</a>. That topic also describes + <p>The <span class="langinline">@Jpf.Action</span> annotation designates an + Action method in a Controller file (JPF file). Action methods perform control + logic, such as forwarding the user to a new JSP page or another Page Flow. + Optionally, you can cause an Action method to read from and update a Form + Bean; set login requirements for users; or indicate that the Action method + will not update any member data in the page flow. </p> + <p>For information about the method signatures of an Action method, see the + <a href="forward.html">@Jpf.Forward Annotation</a>. That topic also describes the run-time behavior of overloaded actions, in the Remarks section. </p> <h2>Syntax</h2> - <p class="syntax">@Jpf.Action</p> - <p class="syntaxindent">[ form = "<form name>" ]</p> - <p class="syntaxindent">[ login-required = "{ true | false }"</p> - <p class="syntaxindent">[ read-only = "{ true | false }" ]</p> - <p class="syntaxindent">[ roles-allowed = "<J2EE role name> [ , <J2EE - role name> ] " ] </p> + <pre> + @Jpf.Action( + <a href="#forwards">forwards</a> = { <a href="forward.html">@Jpf.Forward(...)</a>, ... }, + <a href="#login-required">loginRequired</a> = <em>boolean</em>, + <a href="#read-only">readOnly</a> = <em>boolean</em>, + <a href="#roles-allowed">rolesAllowed</a> = {"<em>role1</em>", "<em>role2</em>", ...} + <a href="#useFormBean">useFormBean</a> = "<em>formBeanInstance</em>", + <a href="#validation-error-page">validationErrorForward</a> = <a href="forward.html">@Jpf.Forward(...)</a>, + )</pre> <h2>Attributes</h2> - <p class="attribute"><a name="form" id="form"></a>form</p> - <p class="partdesc">Optional. A Form Bean instance that will be passed to the - method. The Form Bean instance that is passed to the , allowing the action - to read and update from a FormData (or ActionForm) member variable. <a href="../../guide/netui/guide/conHandlingExceptions.html"></a>For + <p class="attribute"><a name="forwards" id="forwards"></a>forwards</p> + <p class="partdesc">Optional. Specifies one or many <a href="forward.html">@Jpf.Forward</a> + annotations. In its simplest form, a @Jpf.Forward annotation controls user + navigation through a Page Flow. Multiple @Jpf.Forward annotation must be specified + in a comma-separated list, for example:</p> + <p class="partdesc"> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward(name="success", path="good.jsp"), + @Jpf.Forward(name="failure", path="error.jsp") + } + )</pre> + <p class="attribute"><a name="useFormBean" id="useFormBean"></a>useFormBean</p> + <p class="partdesc">Optional. The Form Bean instance that will be passed to + the method. <a href="../../guide/netui/guide/conHandlingExceptions.html"></a>For more information, see the <a href="#remarks">Remarks</a> section. </p> - <p class="attribute"><a name="login-required" id="login-required"></a>login-required</p> + <p class="attribute"><a name="login-required" id="login-required"></a>loginRequired</p> <p class="partdesc">Optional. A boolean that indicates whether the user must - be logged-in to use this action method. If set to <span class="langinline">login-required="true"</span> - the action method can only be run if the user is logged in. That is, the page - flow runtime checks to see if <span class="langinline">request.getUserPrincipal() + be logged-in to call this Action method. If set to <span class="langinline">login-required="true"</span> + the Action method can only be run if the user is logged in. That is, the Page + Flow runtime checks to see if <span class="langinline">request.getUserPrincipal() == null</span>. If it is, then the exception <span class="langinline">com.bea.wlw.netui.pageflow.NotLoggedInException</span> - is thrown and the code in the action method is not executed. You can catch - the exception in the page flow or the web project's Global.app, and from there - attempt to log the user in.</p> - <p class="partdesc">When you create a new "Web Project" project with - WebLogic Workshop, a default Global.app file is created for you in the project's - /WEB-INF/src/global directory. Global.app allows you to define actions that - can be invoked by any other page flow in a web application. In Global.app, - you can catch and handle exceptions that were not caught in your page flow. - For more information, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling + is thrown and the code in the Action method is not executed. You can catch + the exception in the Controller file (using a <a href="catch.html">@Jpf.Catch</a> + annotation) or the web project's Global.app, and from there attempt to log + the user in.</p> + <p class="partdesc">Global.app (located in the <code>WEB-INF/src/global</code> + directory) allows you to define actions that can be invoked by any other Page + Flow in a web application. For more information, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling Exceptions in Page Flows.</a></p> - <p class="attribute"><a name="read-only" id="read-only"></a>read-only</p> + <p class="attribute"><a name="read-only" id="read-only"></a>readOnly</p> <p class="partdesc">Optional. The default is <span class="langinline">read-only="false"</span>. Use this attribute to indicate your intention that this action <nobr><strong>will - not</strong></nobr> update any member data in the page flow. In a WebLogic - cluster environment, this designation causes WebLogic Workshop to skip any - attempted failover of the pageflow after the action is run. This option may - allow you to increase the performance of the page flow in cluster environments, - by making it unnecessary for WebLogic Workshop to communicate portions of - this page flow's state data across the nodes in the cluster that pertain to - the read-only actions.</p> - <p class="attribute"><a name="roles-allowed" id="roles-allowed"></a>roles-allowed</p> - <p class="partdesc">Optional. Specifies the name of one or more security roles - that are defined in the web project's <span class="filepath">/WEB-INF/web.xml</span> - file. If more than one security role name is specified, use a comma to separate - each name. For - more information on security roles, see the <a href="../../guide/security/role-based/navRoleBasedSecurity.html">Role-Based - Security</a>.</p> - <p class="partdesc">If roles-allowed is defined, the use of this action method - will be limited to logged-in users who are associated with at least one - of - the specified roles specified at this method-level, or one of the security - roles specified on the class-level annotation <span class="langinline">@jpf:controller</span> (if used). - That - is, - security roles that are specified at the method level with <span class="langinline">@Jpf.Action</span> - <strong>add</strong> to any allowable roles defined at the class level with - <span class="langinline">@jpf:controller.</span> If the user is not logged-in, - a <span class="langinline">com.bea.wlw.netui.pageflow.NotLoggedInException</span> + not</strong></nobr> update any member data in the page flow. </p> + <p class="attribute"><a name="roles-allowed" id="roles-allowed"></a>rolesAllowed</p> + <p class="partdesc">Optional. Specifies the name of one or more security roles + that are defined in the web project's <span class="filepath">/WEB-INF/web.xml</span> + file. If more than one security role name is specified, use a comma to separate + each name. For more information on security roles, see the <a href="../../guide/security/role-based/navRoleBasedSecurity.html">Role-Based + Security</a>.</p> + <p class="partdesc">If roles-allowed is defined, the use of this action method + will be limited to logged-in users who are associated with at least one of + the specified roles specified at this method-level, or one of the security + roles specified on the class-level annotation <span class="langinline">@jpf:controller</span> + (if used). That is, security roles that are specified at the method level + with <span class="langinline">@Jpf.Action</span> <strong>add</strong> to any + allowable roles defined at the class level with <span class="langinline">@Jpf.Controller.</span> + If the user is not logged-in, a <span class="langinline">com.bea.wlw.netui.pageflow.NotLoggedInException</span> will be thrown. If the user is not in an appropriate role, a <span class="langinline">com.bea.wlw.netui.pageflow.UnfulfilledRolesException</span> - will be thrown. For more information, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling - Exceptions in Page Flows.</a></p> - <p class="attribute"><a name="validation-error-page" id="validation-error-page"></a>validation-error-page - (Deprecated) </p> - <p class="partdesc"><h>This attribute on @Jpf.Action has been deprecated, as - of WebLogic Workshop 8.1 Service Pack 2. Instead you can use the <a href="validation-error-forward.html">@jpf:validation-error-forward - Annotation</a>. </p> + will be thrown. For more information, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling + Exceptions in Page Flows.</a></p> + <p class="attribute"><a name="validation-error-page" id="validation-error-page"></a>validationErrorForward</p> + <p class="partdesc"><h>Optional. Specifies a <a href="forward.html">@Jpf.Forward</a> + annotation used to handle validation errors.</p> <h2><a name="remarks"></a>Remarks</h2> <p>The following rules apply to this annotation's use:</p> <ul style="list-style: disc;" type="disc"> <li> <p>Without an <span class="langinline">@Jpf.Action</span> annotation, a - method will not be recognized by the page flow runtime as an action method.</p> + method will not be recognized by the Page Flow runtime as an action method.</p> </li> - <li>You cannot use the <span class="langinline">jpf:action</span> annotation - at the page flow class level.</li> - <li>When you drag an action icon onto the palette in a page flow's Flow View, - the <span class="langinline">@Jpf.Action</span> annotation is automatically - added for you in the *.jpf source code. Initially this looks like the following - code fragment, where we provided the method name "shopping" for - the action:</li> + <li>You can use the <span class="langinline">Jpf:Action</span> annotation + at the Page Flow class level only when nested inside of a <a href="controller.html">@Jpf.Controller</a> + annotation.</li> + <li>When you drag an<a href="../../java-class/workshop/pageflow/ui/views/flow/model/ActionNode.html"> + Action icon</a> from the <a href="../../guide/netui/guide/conOtherIDECompsForPageFlows.html#jpfpalettewin">Design + Palette</a> into Flow View, the <span class="langinline">@Jpf.Action</span> + annotation is automatically added for you in the JPF file's source code. + Initially this looks like the following code fragment, where we provided + the method name "shopping" for the action:</li> <blockquote> - <pre><font face="Courier New, Courier, mono">/** - * @Jpf.Action - */ - public Forward shopping() - { - return new Forward( "success" ); - }</font></pre> + <pre> @Jpf.Action() + protected Forward shopping() + { + Forward forward = new Forward("success"); + + return forward; + }</pre> <p>In Flow View, you can then draw a forward arrow to a destination, such - as a JSP or a page flow. This step will add a <span class="langinline">@jpf:forward</span> - annotation in your *.jpf file. You can also change the Forward object's + as a JSP or a Page Flow. This step will add a <span class="langinline">@Jpf.Forward</span> + annotation in your JPF file. You can also change the Forward object's return name from "success" to another name. However, if you - do, remember to also change the name attribute on the corresponding @jpf:forward - annotation for the action method. For more information, see <a href="forward.html">@jpf:forward + do, remember to also change the <code>name</code> attribute on the corresponding + <code>@Jpf.Forward</code> annotation. For more information, see <a href="forward.html">@Jpf.Forward Annotation</a>.</p> </blockquote> <li> - <p>You can cause an action to read and update from a <span class="langinline">FormData</span> - (or <span class="langinline">ActionForm</span>) member variable, by using - the <span class="langinline">@Jpf.Action form="<form name>"</span> - annotation. For example, in the page flow class:</p> - <pre> - /** - * @Jpf.Action form="_pageFlowForm" - */ + <p>You can cause an Action method to read from and update a Form Bean instance, + by using the <span class="langinline">@Jpf.Action useFormBean="<form + name>"</span> annotation. In the following example, assume that + <code>_pageFlowForm</code> is an instance of a Form Bean.</p> + <pre> + @Jpf.Action( + useFormBean="_pageFlowForm" + ) protected Forward doit( MyForm myForm ) { // _pageFlowForm is a member variable @@ -165,44 +166,40 @@ ... }</pre> For a related advanced discussion about the behavior seen when you forward - directly from one action to another, and the effects of form scoping, see - the Remarks section of the topic <a href="forward.html">@jpf:forward Annotation</a> + directly from one Action to another, and the effects of form scoping, see + the Remarks section of the topic <a href="forward.html">@Jpf.Forward Annotation</a> and the help topic <a href="../../guide/netui/guide/conReqScopedVsPageScopedBean.html">Page Flow Scopings</a>.</li> <li> - <p>If you enable <span class="langinline">login-required="true"</span> - for an action method, be sure to handle the exception that can occur if - a user who is not logged-in raises the action on a JSP page in the page - flow. You can add the exception code in the page flow class. For example:</p> + <p>If you enable <span class="langinline">loginRequired=true</span> for + an Action method, be sure to handle the exception that can occur if a + non-logged-in user invokes the Action. You can add the exception handling + code in the Page Flow class. In the following example, a non-logged-in + user who invokes the <code>loginSubmit</code> Action method will cause + a <code>FailedLoginException</code> to be thrown, an exception handled + by the <code>failedLogin</code> method.</p> <pre> - import javax.security.auth.login.FailedLoginException; - - ... - - /** - * @Jpf.Action - * @jpf:forward name="success" path="LoginSuccess.jsp" - * @jpf:catch type="FailedLoginException" method="failedLogin" - */ - protected Forward loginSubmit( LoginForm loginForm ) - throws Exception + @Jpf.Action( + forwards = { @Jpf.Forward(name = "success", path = "LoginSuccess.jsp") }, + catches = { @Jpf.Catch(type = FailedLoginException.class, method = "failedLogin") } + ) + protected Forward loginSubmit( LoginForm loginForm ) throws Exception { login( loginForm.getUsername(), loginForm.getPassword() ); userName = loginForm.getUsername(); - return new Forward( "success", loginForm ); + return new Forward( "success", loginForm ); } - /** - * @jpf:exception-handler - * @jpf:forward name="loginPage" path="Login.jsp" - */ - protected Forward failedLogin( FailedLoginException ex, String actionName, - String message, FormData form ) + @Jpf.ExceptionHandler( + forwards = { @Jpf.Forward(name = "loginPage", path = "Login.jsp") } + ) + protected Forward failedLogin( FailedLoginException ex, String actionName, String message, FormData form ) { - return new Forward( "loginPage" ); - }</pre> - <p>You can also use the Global.app file, which the Page Flow Wizard provides - in your web project's <span class="langinline">WEB-INF/src/global</span> + return new Forward( "loginPage" ); + } +</pre> + <p>Alternatively, you can handle exceptions in the Global.app file, which + is provided in your web project's <span class="langinline">WEB-INF/src/global</span> folder. In your page flow, you may notice the line: </p> <p class="codeblock">// protected global.Global globalApp;</p> <p>It is <strong>not</strong> required that you uncomment this line in order @@ -237,32 +234,33 @@ }</pre> </li> - <li>The <span class="langinline">roles-allowed</span> attribute lets you limit - access to a page flow action method to users who are associated with the - J2EE role. This, in turn, limits access from the current context to the - web resource that would be loaded as a result of the action. </li> + <li>The <span class="langinline">rolesAllowed</span> attribute lets you limit + access to an Action method to users who are associated with the J2EE role. + </li> <p>Note that currently using the following IDE menu option defines a new security role in the <strong>application's</strong> <span class="langinline">/META-INF/application.xml</span> file:</p> - <p>Tools > Security > Create New Security Role...</p> + <p>Tools --> Security --> Create New Security Role...</p> <p>However, <span class="langinline">/META-INF/application.xml </span>is not - the XML file that is used for the page flow roles-allowed checking. Enter - any J2EE roles in the web project's web.xml file, and associate usernames - with the role name in the web project's weblogic.xml file.</p> + the XML file that is used for the Page Flow <code>rolesAllowed</code> checking. + Instead the roles are checked against the web project's web.xml file and + weblogic.xml file. For more detailed information, see <a href="../../guide/security/role-based/ovwRoleBasedSecurity.html">An + Overview of Role-Based Security</a>.</p> </ul> <p class="relatedtopics">Related Topics</p> - <p><a href="catch.html">@jpf:catch Annotation</a></p> - <p><a href="controller.html">@jpf:controller Annotation</a></p> - <p><a href="exception-handler.html">@jpf:exception-handler Annotation</a></p> - <p><a href="forward.html">@jpf:forward Annotation</a></p> - <p><a href="message-resources.html">@jpf:message-resources Annotation</a></p> - <p><a href="validation-error-forward.html">@jpf:validation-error-forward Annotation</a></p> + <p><a href="catch.html">@Jpf.Catch Annotation</a></p> + <p><a href="controller.html">@Jpf.Controller Annotation</a></p> + <p><a href="exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> + <p><a href="forward.html">@Jpf.Forward Annotation</a></p> + <p><a href="message-resources.html">@Jpf.MessageResources Annotation</a></p> +</div> +<div id="topictext"> <p><a href="../../guide/netui/guide/conReqScopedVsPageScopedBean.html">Form Bean Scopings</a></p> <h3>Samples</h3> <p><a href="../../guide/netui/samples/samDataFlow.html">Data Flow Sample</a></p> </div> -<!-- InstanceEndEditable --> +<!-- InstanceEndEditable --> <script language="JavaScript"> writeTopicInfo(); </script> Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/catch.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/catch.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/catch.html Tue Aug 31 15:54:21 2004 @@ -38,65 +38,67 @@ displayInFrames(); </script> <!-- InstanceBeginEditable name="body" --> -<div id="topictitle"> +<div id="topictitle"> <h1 class="Title">@Jpf.Catch Annotation</h1> </div> -<div id="topictext"> - <p>You can use the <span class="langinline">@Jpf.Catch</span> annotation to - catch exceptions that occur in the page flow and possibly route them to error - handlers.</p> - <p>For more information about using this annotation, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling - Exceptions in Page Flows.</a></p> +<div id="topictext"> + <p>You can use the <span class="langinline">@Jpf.Catch</span> annotation to + catch exceptions that occur in the Page Flow and route them to error handlers.</p> + <p>For more information about using this annotation, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling + Exceptions in Page Flows.</a></p> <h2>Syntax</h2> - <p class="syntax">@Jpf.Catch</p> - <p class="syntaxindent">type = "<exception type>"</p> - <p class="syntaxindent">{ path = "<path>" | method - = "<method name>" }</p> - <p class="syntaxindent">[ message = "<message String>" ]</p> - <p class="syntaxindent">[ message-key = "<key value>" ]</p> + <pre> + @Jpf.Catch( + <a href="#type">type</a> = <em>exception_class</em>, + <a href="#path">path</a> = "<em>path</em>", + <a href="#method">method</a> = "<em>method</em>", + <a href="#message">message</a> = "<em>message</em>", + <a href="#message-key">messageKey</a> = "<em>messageKey</em>" + ) + </pre> <h2>Attributes</h2> <p class="attribute"><a name="type"></a>type</p> - <p class="partdesc">Required. Specifies the fully qualified Java type of the - exceptions that should be caught.</p> + <p class="partdesc">Required. Specifies the fully qualified Java type of the + exception that should be caught.</p> <p class="attribute"><a name="path"></a>path</p> - <p class="partdesc">Either this attribute or the method attribute is required. - Specifies the resource to which the runtime should forward when it catches an - exception of the type specified in the type attribute. The path can map to one - of the following:</p> + <p class="partdesc">Either this attribute or the <a href="#method"><code>method</code></a> + attribute is required. Specifies the resource to which the runtime should + forward when it catches an exception of the type specified in the <code><a href="#type">type</a></code> + attribute. The <code>path</code> can refer to one of the following:</p> </div> <ul> <li> - <div class="partdesc"> A JSP or another page flow in this web application.</div> + <div class="partdesc"> A JSP page or another Page Flow in this web application.</div> </li> <li> - <div class="partdesc"> An action, such as <span class="langinline">/help/helpPage.do</span>. - </div> + <div class="partdesc"> An Action method in the current Page Flow, such as + <span class="langinline">/help/helpPage.do</span>. </div> </li> </ul> <div> <p class="attribute"><a name="method"></a>method</p> - <p class="partdesc">Either this attribute or the path attribute is required. - Specifies the name of an exception handler method that has been designated - with a <span class="langinline">@jpf:exception-handler</span> annotation. - That method will be invoked when the exception of the type specified in the - type attribute is caught.</p> + <p class="partdesc">Either this attribute or the <a href="#path"><code>path</code></a> + attribute is required. Specifies the name of an exception handler method that + has been designated with a <span class="langinline">@Jpf.ExceptionHandler</span> + annotation. That method will be invoked when the exception of the type specified + in the <code>type</code> attribute is caught.</p> <p class="attribute"><a name="message"></a>message</p> <p class="partdesc">Optional. Specify a string that provides useful information about the exception. This message will be passed to the exception-handler - method, if the method attribute is used.</p> - <p class="attribute"><a name="message-key" id="message-key"></a>message-key</p> + method, if the <code>method</code> attribute is used.</p> + <p class="attribute"><a name="message-key" id="message-key"></a>messageKey</p> <p class="partdesc">Optional. Specify a key that is used to select a message from a message map. Typically this key is used to enable internationalization of messages, which are passed to the exception-handler method, and can also - be displayed using the <a href="../../taglib/www.bea.com/workshop/netui-tags-html-1.0/errors.html"><netui:errors/> - tag</a>. The key refers to a message resource that is defined by the <a href="message-resources.html">@jpf:message-resources + be displayed using the <a href="../taglib/beehive.apache.org/netui/tags-html-1.0/errors.html"><netui:errors/> + tag</a>. The key refers to a message resource that is defined by the <a href="message-resources.html">@Jpf.MessageResources Annotation.</a></p> <h2>Remarks</h2> <p>The following rules apply to this annotation's use:</p> <ul style="list-style: disc;" type="disc"> <li> <p>The <span class="langinline">@Jpf.Catch</span> annotation may be used - on action methods and the page flow class, and in the /WEB-INF/src/global/Global.app + on Action methods, the Page Flow class, and in the /WEB-INF/src/global/Global.app file.</p> </li> <li> @@ -105,15 +107,14 @@ of <span class="langinline">NullPointerException</span>), this annotation will apply to any subtype that is thrown, unless there is a <span class="langinline">@Jpf.Catch</span> that applies more specifically to the subtype. </p> - <p>For example, given the following annotations, an <span class="langinline">IllegalStateException</span> will be routed to "error1.jsp", while a <span class="langinline">NullPointerException</span> will be routed to "error2.jsp". (Both <span class="langinline">IllegalStateException</span> and <span class="langinline">NullPointerException</span> are subtypes of <span class="langinline">Exception</span>). </p> <pre> - * @Jpf.Catch type="Exception" path="error1.jsp" - * @Jpf.Catch type="NullPointerException" path="error2.jsp" + @Jpf.Catch(type = Exception, path = "error1.jsp") + @Jpf.Catch(type = NullPointerException, path = "error2.jsp") </pre> </li> </ul> @@ -121,75 +122,78 @@ <ul> <li> <div>The <span class="langinline">path</span> value can be relative to the - page flow within the local file hierarchy, or relative to the root of the + Page Flow within the local file hierarchy, or relative to the root of the web application.</div> </li> </ul> <div> <ul style="list-style: disc;" type="disc"> <li> - <p>In a page flow class, you can use the <span class="langinline">@Jpf.Catch</span> - annotation with, or without, the <span class="langinline">@jpf:exception-handler</span> + <p>You can use the <span class="langinline">@Jpf.Catch</span> annotation + with, or without, an associated <span class="langinline">@Jpf.ExceptionHandler</span> annotation. If you use <span class="langinline">@Jpf.Catch</span> without - <span class="langinline">@jpf:exception-handler</span> in the page flow, + <span class="langinline">@Jpf.ExceptionHandler</span> in the page flow, you can only catch errors and take action such as forwarding to a generic errors.jsp page. For example:</p> <pre> -/** - * @jpf:action - * @jpf:forward name="readyForNextCandidate" path="name.jsp" - * @Jpf.Catch type="com.acme.WorkflowException" path="errors.jsp" -*/ -public Forward confirmationPage_hire(HireForm form) -throws Exception + @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "readyForNextCandidate", + path = "name.jsp", + path = "errors.jsp" + ) + } +) +public Forward confirmationPage_hire(HireForm form) throws Exception { hiringService.hire(firstName, lastName, title, startDate); - . - . - .</pre> + . + . + . +}</pre> </li> </ul> </div> <ul> - <li> + <li> <div> Note that <span class="langinline">@Jpf.Catch</span> annotations <strong>cannot</strong> - be used to catch exceptions on exception-handler methods. The following - code is invalid and results in a compilation error: </div> + be used to catch exceptions on exception-handler methods (= methods marked + with the <code>@Jpf.ExceptionHandler</code> annotation). The following code + is invalid and results in a compilation error: </div> </li> </ul> <blockquote> <div> </div> <div> <pre> - /** - * Invalid code: - * @jpf:exception-handler - * @Jpf.Catch type="Exception" path="foo.jsp" - */ - public Forward bad( Exception e, String msg, String msgKey, ActionForm form ) + /** + * Invalid code: + */ + @Jpf.ExceptionHandler( forwards = { @Jpf.Forward(name = "errorPage", path = "/error.jsp") } ) + @Jpf.Action( catches = { @Jpf.Catch(method = "exceptionHandler") } ) + public Forward bad( Exception e, String msg, String msgKey, ActionForm form ) </pre> </div> </blockquote> -<div> +<div> <p>For information about using the <span class="langinline">@Jpf.Catch</span> - and <span class="langinline">@jpf:exception-handler</span> annotations together, - to both catch and handle exceptions, see <a href="exception-handler.html">@jpf:exception-handler - annotation</a>. Also see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling + and <span class="langinline">@Jpf.ExceptionHandler</span> annotations together, + to both catch and handle exceptions, see <a href="exception-handler.html">@Jpf.ExceptionHandler + annotation</a> and <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling Exceptions in Page Flows.</a></p> +</div> +<div> <p class="relatedtopics">Related Topics</p> - <p><a href="exception-handler.html">@jpf:exception-handler Annotation</a></p> <p><a href="../../guide/netui/guide/conHandlingExceptions.html">Handling Exceptions in Page Flows</a></p> - <p><a href="action.html">@jpf:action Annotation</a></p> - <p><a href="controller.html">@jpf:controller Annotation</a></p> - <p><a href="forward.html">@jpf:forward Annotation</a></p> - <p><a href="message-resources.html">@jpf:message-resources Annotation</a></p> - <p><a href="validation-error-forward.html">@jpf:validation-error-forward Annotation</a></p> - <p><a href="../../guide/netui/guide/conGettingStartedPageFlows.html">Getting - Started with Page Flows</a></p> - <p> </p> + <p><a href="exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> + <p><a href="action.html">@Jpf.Action Annotation</a></p> + <p><a href="controller.html">@Jpf.Controller Annotation</a></p> + <p><a href="forward.html">@Jpf.Forward Annotation</a></p> + <p><a href="message-resources.html">@Jpf.MessageResources Annotation</a></p> </div> -<!-- InstanceEndEditable --> +<!-- InstanceEndEditable --> <script language="JavaScript"> writeTopicInfo(); </script> Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/controller.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/controller.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/controller.html Tue Aug 31 15:54:21 2004 @@ -37,138 +37,140 @@ <script language="JavaScript"> displayInFrames(); </script> -<!-- InstanceBeginEditable name="body" --> +<!-- InstanceBeginEditable name="body" --> <div id="topictitle"> <h1 class="Title">@Jpf.Controller Annotation</h1> </div> -<div id="topictext"> - <p>You can use the <span class="langinline">@Jpf.Controller</span> annotation - at the class-level only to designate the following characteristics of the page - flow: +<div id="topictext"> + <p>You can use the <span class="langinline">@Jpf.Controller</span> annotation + only at the class-level to designate the following characteristics of the + Page Flow: <ul style="list-style: disc;" type="disc"> - <li>Is this page flow "nested," meaning, can control return to the - calling page flow after this page flow completes its work? - <li>Is the use of this page flow limited to logged-in users? - <li>Is the use of this page flow limited to logged-in users who are - associated with a J2EE role, as defined in the application's web.xml file? - <li>Will a Struts configuration file be merged with the page flow's - configuration file? + <li>Is this Page Flow "nested," meaning, can control return to the + calling Page Flow after this Page Flow completes its work? + <li>Is the use of this Page Flow limited to logged-in users? + <li>Is the use of this Page Flow limited to members of a particular J2EE security + role? + <li>Will a Struts configuration file be merged with the Page Flow's configuration + file? </ul> </div> -<div id="topictext"> +<div id="topictext"> <p class="notepara"><strong>Note:</strong> At the class level, you have the - option of also using a <a href="catch.html">@jpf:catch annotation</a>, a global - <a href="forward.html">@jpf:forward annotation</a>, or both. These annotations + option of also using a <a href="catch.html">@Jpf.Catch annotation</a>, a global + <a href="forward.html">@Jpf.Forward annotation</a>, or both. These annotations may be used at the class level, with or without a @Jpf.Controller annotation.</p> </div> -<div> +<div> <h2>Syntax</h2> - <p class="syntax">@Jpf.Controller</p> - <p class="syntaxindent">[ nested = "true | false" ]</p> - <p class="syntaxindent">[ login-required = "true | false" ]</p> - <p class="syntaxindent">[ roles-allowed = "<J2EE-role-name> [ , - <J2EE-role-name> ] " ]</p> - <p class="syntaxindent">[ struts-merge = "<Struts-file>.xml" ]</p> + <pre> + @Jpf.Controller( + catches = { <a href="catch.html">@Jpf.Catch(...)</a>, ... }, + forwards = { <a href="forward.html">@Jpf.Forward(...)</a>, ... }, + messageResources = { <a href="message-resources.html">@Jpf.MessageResource(...)</a>, ... }, + readOnly = <em>boolean</em>, + nested = <em>boolean</em>, + strutsMerge = "<em>mergeXML</em>", + validatableBeans = { @Jpf.ValidatableBean(...), ...} + )</pre> <h2>Attributes</h2> <p class="attribute"><a name="nested"></a>nested</p> - <p class="partdesc">Optional. A boolean that indicates whether this is a - nested page flow that can be called from another page flow. If the <span class="langinline">@Jpf.Controller</span> - annotation is used, but the <span class="langinline">nested </span>attribute - is not, the default is <span class="langinline">nested="false"</span>.</p> - <p class="attribute"><a name="login-required" id="login-required"></a>login-required</p> + <p class="partdesc">Optional. A boolean that indicates whether this is a nested + Page Flow that can be called from another Page Flow. If the <span class="langinline">@Jpf.Controller</span> + annotation is used, but the <span class="langinline">nested </span>attribute + is not, the default is <span class="langinline">nested="false"</span>.</p> + <p class="attribute"><a name="login-required" id="login-required"></a>loginRequired</p> <p class="partdesc">Optional. A boolean that indicates whether the user must - be logged-in to use this page flow. If the <span class="langinline">@Jpf.Controller</span> + be logged-in to use this Page Flow. If the <span class="langinline">@Jpf.Controller</span> annotation is used, but both the <span class="langinline">login-required</span> and <span class="langinline">roles-allowed</span> attributes are not used, the default is <span class="langinline">login-required="false"</span>. However, if only the <span class="langinline">roles-allowed</span> attribute is used, then <span class="langinline">login-required="true"</span> is implied.</p> - <p class="partdesc">The JPF compiler will issue an error if you use both the <span class="langinline">roles-allowed</span> - attribute and the <span class="langinline">login-required</span> attribute.</p> - <p class="attribute"><a name="roles-allowed" id="roles-allowed"></a>roles-allowed</p> - <p class="partdesc">Optional. Specifies the name of one or more J2EE roles - that are defined in the web project's <span class="filepath">/WEB-INF/web.xml</span> - file. If more than one J2EE role name is specified, use a comma to separate - each name. If defined, the use of all action methods in this page flow is - limited to users who are associated with the specified role(s). Note that - users who are granted the roles specified may access all methods in the page - flow, regardless of any further role restrictions applied to individual - methods by the <span class="langinline">@jpf:action</span> annotation.</p> - <p class="partdesc">You can, optionally, also use the <span class="langinline">@jpf:action</span> - annotation to <strong>add</strong> to the authorized role(s) that are declared - at the class-level by <span class="langinline">@Jpf.Controller.</span> The - method-level <span class="langinline">@jpf:action</span> annotation also has a - <span class="langinline">roles-allowed</span> attribute. For more information, - see <a href="Action.html">@jpf:action annotation.</a></p> + <p class="partdesc">The JPF compiler will issue an error if you use both the + <span class="langinline">roles-allowed</span> attribute and the <span class="langinline">login-required</span> + attribute.</p> + <p class="attribute"><a name="roles-allowed" id="roles-allowed"></a>rolesAllowed</p> + <p class="partdesc">Optional. Specifies the name of one or more J2EE roles that + are defined in the web project's <span class="filepath">/WEB-INF/web.xml</span> + file. If more than one J2EE role name is specified, use a comma to separate + each name. If defined, the use of all Action methods in this Page Flow is + limited to users who are associated with the specified role(s). Note that + users who are granted the roles specified may access all methods in the Page + Flow, regardless of any further role restrictions applied to individual methods + by the <a href="action.html">@Jpf.Action</a> annotation.</p> + <p class="partdesc">You can, optionally, also use the <span class="langinline">@Jpf.Action</span> + annotation to <strong>add</strong> to the authorized role(s) that are declared + at the class-level by <span class="langinline">@Jpf.Controller.</span> The + method-level <span class="langinline">@Jpf.Action</span> annotation also has + a <span class="langinline">rolesAllowed</span> attribute. For more information, + see <a href="Action.html">@Jpf.Action annotation.</a></p> <p class="attribute"><a name="struts-merge" id="struts-merge"></a>struts-merge</p> - <p class="partdesc">Optional. Specifies a standard Struts configuration XML - file that you want the WebLogic Workshop compiler to merge into the generated - configuration file for the page flow: <span class="langinline">/WEB-INF/jpf-struts-<pageflow-name>.xml</span>. - The Struts XML file, by convention, should reside in the web project's - /WEB-INF directory. After the compilation step that creates the merged <span class="langinline">/WEB-INF/jpf-struts-<pageflow-name>.xml</span>, - functionality that was enabled by the Struts configuration is available to the - page flow controller.</p> - <p class="partdesc">The purpose of the "Struts Merge" feature is to - enable you to override page flow defaults, or to specify settings for the page - flow that are not provided by page flow annotations or their attributes. The - Struts merge files should typically be small and only modify the page flow and - its actions and form beans. You can also add Struts tags that are not - supported by page flows, such as the <span class="langinline"><plug-in></span> - tag. While you could, for example, add action mappings in the Struts merge - file, BEA does not recommend this practice. Struts action mappings should be - declared in the page flow's .jpf file with <span class="langinline">@jpf</span> - annotations, and then (if necessary) modified with the Struts merge file. For - details, see <a href="../../guide/netui/guide/conStrutsMerge.html">Merging - Struts Artifacts Into Page Flows.</a></p> + <p class="partdesc">Optional. Specifies a standard Struts configuration XML + file that you want the WebLogic Workshop compiler to merge into the generated + configuration file for the Page Flow. The generated configuration file is + named: <span class="langinline">/WEB-INF/jpf-struts-<pageflow-name>.xml</span>. + The Struts XML file, by convention, should reside in the web project's /WEB-INF + directory. After the compilation step that creates the merged <span class="langinline">/WEB-INF/jpf-struts-<pageflow-name>.xml</span>, + functionality that was enabled by the Struts configuration is available to + the Page Flow controller.</p> + <p class="partdesc">The purpose of the "Struts Merge" feature is to + enable you to override Page Flow defaults, or to specify settings for the + Page Flow that are not provided by Page Flow annotations or their attributes. + The Struts merge files should typically be small and only modify the Page + Flow and its Actions and Form Bean. You can also add Struts tags that are + not supported by Page Flows, such as the <span class="langinline"><plug-in></span> + tag. While you could, for example, add Action mappings in the Struts merge + file, BEA does not recommend this practice. Struts action mappings should + be declared in the Page Flow's JPF file with <span class="langinline">@Jpf</span> + annotations, and then (if necessary) modified with the Struts merge file. + For details, see <a href="../../guide/netui/guide/conStrutsMerge.html">Merging + Struts Artifacts Into Page Flows.</a></p> <h2>Remarks</h2> <p>The following rules apply to this annotation's use:</p> <ul style="list-style: disc;" type="disc"> - <li> + <li> <p>The <span class="langinline">@Jpf.Controller</span> annotation is optional - and can be used only to qualify the page flow class. This annotation cannot - be used on a method within the page flow class.</p> + and can be used only to qualify the Page Flow class signature. This annotation + cannot be used on a method within the Page Flow class.</p> </li> - <li>A nested page flow is useful when you want to perform some processing - and then return (with or without the results) to the calling page flow. - For example, a vacation scheduling page flow could call a nested page flow - that lists the company holidays. After the companyHolidays page flow is - used, a method that exists in the nested page flow could return the user - to the calling vacationScheduling page flow.</li> - <li> - <p>The <span class="langinline">roles-allowed</span> attribute on this @Jpf.Controller - annotation lets you limit access to this page flow's action methods to - users who are associated with the security role. This, in turn, limits - access from the current context to the web resource that would be loaded - as a result of the action. Again, you can add to the authorized - role(s) declared at the class-level with @Jpf.Controller by using the - <span class="langinline">roles-allowed</span> attribute on a method-level - <a href="action.html">@jpf:action annotation</a>.</p> + <li>A nested Page Flow is useful when you want to perform some processing + and then return (with or without the results) to the calling Page Flow. + For example, a vacation scheduling Page Flow could call a nested Page Flow + that lists the company holidays. After the CompanyHolidays Page Flow is + used, a method that exists in the nested Page Flow could return the user + to the calling VacationScheduling Page Flow.</li> + <li> + <p>The <span class="langinline">rolesAllowed</span> attribute on this @Jpf.Controller + annotation lets you limit access to this Page Flow's Action methods to + those users who are associated with a specific security role. Again, you + can add to the authorized role(s) declared at the class-level with @Jpf.Controller + by using the <span class="langinline">rolesAllowed</span> attribute on + a method-level <a href="action.html">@Jpf.Action annotation</a>.</p> </li> - <li> - <p>Note that the following IDE menu option defines a new security role in - the <strong>application's</strong> <span class="langinline">/META-INF/application.xml</span> - file:</p> - <p>Tools > Security > Create New Security Role...</p> - <p>However, <span class="langinline">/META-INF/application.xml </span>is - not the XML file that is used for the page flow scoped roles-allowed checking. - Enter any security roles in the web project's web.xml file, and associate - principals with the role name in the web project's weblogic.xml file. For - more information, see the <a href="../../guide/security/role-based/navRoleBasedSecurity.html">Role-Based - Security</a>.</p> + <li> + <p>Note that the following IDE menu option defines a new security role in + the <strong>application's</strong> <span class="langinline">/META-INF/application.xml</span> + file:</p> + <p>Tools --> Security --> Create New Security Role...</p> + <p>However, <span class="langinline">/META-INF/application.xml </span>is + not the XML file that is used for the Page Flow <code>rolesAllowed</code> + checking. Instead the roles are checked against the web project's web.xml + file and weblogic.xml file. For more detailed information, see <a href="../../guide/security/role-based/ovwRoleBasedSecurity.html">An + Overview of Role-Based Security</a>.</p> </li> </ul> +</div> +<div> <p class="relatedtopics">Related Topics</p> - <p><a href="action.html">@jpf:action Annotation</a></p> - <p><a href="catch.html">@jpf:catch Annotation</a></p> - <p><a href="forward.html">@jpf:forward Annotation</a></p> - <p><a href="exception-handler.html">@jpf:exception-handler Annotation</a></p> - <p><a href="message-resources.html">@jpf:message-resources Annotation</a></p> - <p><a href="validation-error-forward.html">@jpf:validation-error-forward Annotation</a></p> - <p><a href="../../guide/netui/guide/conGettingStartedPageFlows.html">Getting - Started with Page Flows</a></p> + <p><a href="action.html">@Jpf.Action Annotation</a></p> + <p><a href="catch.html">@Jpf.Catch Annotation</a></p> + <p><a href="forward.html">@Jpf.Forward Annotation</a></p> + <p><a href="exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> + <p><a href="message-resources.html">@Jpf.MessageResources Annotation</a></p> </div> -<!-- InstanceEndEditable --> +<!-- InstanceEndEditable --> <script language="JavaScript"> writeTopicInfo(); </script> Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/exception-handler.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/exception-handler.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/exception-handler.html Tue Aug 31 15:54:21 2004 @@ -35,120 +35,97 @@ <script language="JavaScript"> displayInFrames(); </script> -<!-- InstanceBeginEditable name="body" --> -<div id="topictitle"> +<!-- InstanceBeginEditable name="body" --> +<div id="topictitle"> <h1 class="Title">@Jpf.ExceptionHandler Annotation</h1> </div> <div id="topictext"> - <p>You can use the <span class="langinline">@Jpf.ExceptionHandler</span> annotation - to mark an error handler method that is specified by a <span class="langinline">@jpf:catch - </span>annotation in a page flow. Without a <span class="langinline">@Jpf.ExceptionHandler</span> - annotation, the page flow runtime will not route exceptions to an error handler - method.</p> - <p>For more information about using this annotation, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling - Exceptions in Page Flows.</a></p> + <p>Use the <span class="langinline">@Jpf.ExceptionHandler</span> annotation + to mark an exception-handler method. Exceptions thrown inside the Page Flow + class, and which are caught by a <span class="langinline"><a href="catch.html">@Jpf.Catch</a> + </span>annotation can be routed to the exception-handler method. Without a + <span class="langinline">@Jpf.ExceptionHandler</span> annotation, the Page + Flow runtime will not route exceptions to an error handler method within the + Page Flow class. Instead the exceptions will be handled generically by the + Global.app.</p> + <p>For more information about using this annotation, see <a href="../../guide/netui/guide/conHandlingExceptions.html">Handling + Exceptions in Page Flows.</a></p> <h2>Syntax</h2> - <p class="syntax">@Jpf.ExceptionHandler</p> - <p class="syntaxindent"> [ read-only = "{ true | false }" ]</p> - <p class="syntaxindent"> </p> + <pre> + @Jpf.ExceptionHandler( + <a href="#read-only">readOnly</a> = "<em>boolean</em>" + } + </pre> <h2>Attributes</h2> <p class="attribute"><a name="read-only" id="read-only"></a>read-only</p> - <p class="partdesc">Optional. The default is <span class="langinline">read-only="false"</span>. + <p class="partdesc">Optional. The default is <span class="langinline">readOnly="false"</span>. Use this attribute to indicate your intention that this method <nobr><strong>will - not</strong></nobr> update any member data in the page flow. In a WebLogic + not</strong></nobr> update any member data in the Page Flow. In a WebLogic cluster environment, this designation causes WebLogic Workshop to skip any - attempted failover of the pageflow after the action is run. This option may - allow you to increase the performance of the page flow in cluster environments, + attempted failover of the Page Flow after the Action is run. This option may + allow you to increase the performance of the Page Flow in cluster environments, by making it unnecessary for WebLogic Workshop to communicate portions of - this page flow's state data across the nodes in the cluster that pertain to + this Page Flow's state data across the nodes in the cluster that pertain to the read-only actions.</p> </div> <div> <h2>Remarks</h2> <p>The following rules apply to this annotation's use:</p> <ul style="list-style: disc;" type="disc"> - <li>The <span class="langinline">@Jpf.ExceptionHandler</span> annotation - must be used with a <span class="langinline">@jpf:catch</span> annotation. - For example: - <pre> - package login2; - - import com.bea.wlw.netui.pageflow.PageFlowController; - import com.bea.wlw.netui.pageflow.Forward; - import com.bea.wlw.netui.pageflow.FormData; - import javax.servlet.http.HttpServletRequest; -<strong> import javax.security.auth.login.FailedLoginException;</strong> - - /** - * @jpf:controller nested="true" - */ - public class Login extends PageFlowController - { - public String userName; - /** - * @jpf:action - * @jpf:forward name="success" path="LoginSuccess.jsp" -<strong> * @jpf:catch type="FailedLoginException" method="failedLogin"</strong> - */ - protected Forward loginSubmit( LoginForm loginForm ) - throws Exception + <li>The <span class="langinline">@Jpf.ExceptionHandler</span> annotation must + be used with a <span class="langinline">@Jpf.Catch</span> annotation. For + example: + <pre> + @Jpf.Action( + forwards = { @Jpf.Forward(name = "success", path = "loginSuccess.jsp")}, + catches = { @Jpf.Catch(type = FailedLoginException, method = "failedLogin")} + ) + public Forward loginSubmit( LoginForm loginForm ) throws Exception { login( loginForm.getUsername(), loginForm.getPassword() ); userName = loginForm.getUsername(); - return new Forward( "success", loginForm ); + return new Forward( "success", loginForm ); } - /** -<strong> * @Jpf.ExceptionHandler</strong> - * @jpf:forward name="loginPage" path="Login.jsp" - */ -<strong> protected Forward failedLogin( FailedLoginException ex, String actionName, - String message, FormData form )</strong> + @Jpf.ExceptionHandler( + forwards = { @Jpf.Forward(name = "loginPage", path = "login.jsp")} + ) + public Forward failedLogin( FailedLoginException ex, String actionName, String message, FormData form ) { LoginForm loginForm = ( LoginForm ) form; - loginForm.setMessage( "Login incorrect. Do you need to create an account?" ); - return new Forward( "loginPage" ); - } - . - . - .</pre> + loginForm.setMessage( "Login incorrect. Do you need to create an account?" ); + return new Forward( "loginPage" ); + } </pre> </li> </ul> </div> <ul> - <li> - <div> Note that <span class="langinline">@jpf:catch</span> annotations cannot - be used to catch exceptions on ExceptionHandler methods. The following - code is invalid and results in a compilation error: </div> + <li> + <div> Note that <span class="langinline">@Jpf.Catch</span> annotations cannot + be used to catch exceptions on ExceptionHandler methods. The following code + is invalid and results in a compilation error: + <pre> + /** + * Invalid code: + */ + @Jpf.ExceptionHandler( forwards = { @Jpf.Forward(name = "errorPage", path = "/error.jsp") } ) + @Jpf.Action( catches = { @Jpf.Catch(method = "exceptionHandler") } ) + public Forward bad( Exception e, String msg, String msgKey, ActionForm form ) </pre> + </div> </li> </ul> -<blockquote> - <div> - <pre> - /** - * Invalid code: - * @Jpf.ExceptionHandler - * @jpf:catch type="Exception" path="foo.jsp" - */ - public Forward bad( Exception e, String msg, String msgKey, ActionForm form ) - </pre> - </div> -</blockquote> -<div> +<div> <p class="relatedtopics">Related Topics</p> - <p><a href="catch.html">@jpf:catch Annotation</a></p> - <p><a href="../../guide/netui/guide/conHandlingExceptions.html">Handling - Exceptions in Page Flows</a></p> - <p><a href="action.html">@jpf:action Annotation</a></p> - <p><a href="controller.html">@jpf:controller Annotation</a></p> - <p><a href="forward.html">@jpf:forward Annotation</a></p> - <p><a href="message-resources.html">@jpf:message-resources Annotation</a></p> - <p><a href="validation-error-forward.html">@jpf:validation-error-forward Annotation</a></p> - <p><a href="../../guide/netui/guide/conGettingStartedPageFlows.html">Getting - Started with Page Flows</a></p> - <p> </p> + <p><a href="catch.html">@Jpf.Catch Annotation</a></p> + <p><a href="action.html">@Jpf.Action Annotation</a></p> + <p><a href="controller.html">@Jpf.Controller Annotation</a></p> + <p><a href="forward.html">@Jpf.Forward Annotation</a></p> + <p><a href="message-resources.html">@Jpf.MessageResources Annotation</a></p> </div> -<!-- InstanceEndEditable --> +<a href="../../guide/netui/guide/conHandlingExceptions.html">Handling Exceptions +in Page Flows</a> +<div></div> +<!-- InstanceEndEditable --> <script language="JavaScript"> writeTopicInfo(); </script> Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/forward.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/forward.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/forward.html Tue Aug 31 15:54:21 2004 @@ -34,18 +34,17 @@ <script language="JavaScript"> displayInFrames(); </script> -<!-- InstanceBeginEditable name="body" --> +<!-- InstanceBeginEditable name="body" --> <div id="topictitle"> <h1 class="Title">@Jpf.Forward Annotation</h1> </div> <div id="topictext"> - <p>You can use the <span class="langinline">@Jpf.Forward</span> annotation to - describe the location the page flow runtime should go to next. The location - may be a JSP, a page flow, a specific page flow action, or an external URL. - This annotation may be used on action methods and the page flow class, and - in the /WEB-INF/src/global/Global.app. Using the @Jpf.Forward at the class - level results in a global forward that can be used by any action method in - the page flow class.</p> + <p>The <span class="langinline">@Jpf.Forward</span> annotation navigates a user + to a new location. The location may be a JSP, a Page Flow, a specific Page + Flow action, or an external URL. This annotation can modify either individual + Action methods or an entire Page Flow class. Using the <code>@Jpf.Forward</code> + at the class-level results in a global forward that can be used by any Action + method in the Page Flow class. </p> <p>The Remarks section includes a discussion about what happens if you use <a href="#overloaded">overloaded actions</a>. Also, the Remarks section contains a description about the behavior seen when you forward directly from one action to another, and the effects @@ -53,37 +52,39 @@ </div> <div> <h2>Syntax</h2> - <p class="syntax">@Jpf.Forward</p> - <p class="syntaxindent">name = "<forward name>"</p> - <p class="syntaxindent">{ path = "<path>" | return-action - = "<action name>" | return-to = {"currentPage" - | "previousPage" | "previousAction"} }</p> - <p class="syntaxindent">{ return-form = "<form name>" | return-form-type - = "<form type>" }</p> - <p class="syntaxindent">[ redirect = { "true" | "false" - } ]</p> + <pre><strong> + @Jpf.Forward( + <a href="#name">name</a> = "<em>name</em>", + <a href="#path">path</a> = "<em>path</em>", + <a href="#return-to">navigateTo</a> = [currentPage | previousPage | previousAction | page], + <a href="#returnaction">returnAction</a> = "<em>returnAction</em>", + <a href="#outputFormBean">outputFormBean</a> = "<em>formBeanInstance</em>"; + <a href="#outputFormBeanType">outputFormBeanType</a> = <em>JavaClass</em>, + <a href="#actionoutputs">actionOutputs</a> = { <a href="action-output.html"><em>@Jpf.ActionOutput(...)</em></a>, ... }, + <a href="#redirect">redirect</a> = <em>boolean</em> + )</strong></pre> <h2>Attributes</h2> <div id="topictext"> <p class="attribute"><a name="name"></a>name</p> - <p class="partdesc">Required. Specifies the name of the forward, which causes - the navigation to occur. Note that <span class="langinline">@Jpf.Forward</span> - names on exception-handlers can conflict with <span class="langinline">@Jpf.Forward</span> - names on actions and at the class level. The <span class="langinline">@Jpf.Forward</span> - names that you specify must be unique in the page flow.</p> + <p class="partdesc">Required. Specifies the name of the forward. The <span class="langinline">name + </span>specified must be unique in the Page Flow. [tbd: this isn't really + true] Note that <span class="langinline">@Jpf.Forward</span> names on exception-handlers + can conflict with <span class="langinline">@Jpf.Forward</span> names on + actions and at the class level. </p> <p><strong>You must specify only one of the following: the <span class="langinline">path</span>, <span class="langinline">return-to</span>, or the <span class="langinline">return-action</span> attributes.</strong></p> <p class="attribute"><a name="path"></a>path</p> <p class="partdesc"> The <span class="langinline">path</span> attribute is - a string that maps to one of the following entities:</p> + a string that refers to one of the following:</p> </div> <ul> <li> - <div class="partdesc"> A JSP or another page flow in this web application + <div class="partdesc"> A JSP or another Page Flow in this web application </div> </li> <li> - <div class="partdesc"> An action within a page flow in this web application + <div class="partdesc"> An action within a Page Flow in this web application </div> </li> <li> @@ -93,57 +94,87 @@ </ul> </div> <blockquote> - <p>If the path begins with a protocol such as "http:" the page flow + <p>If the path begins with a protocol such as "http:" the Page Flow runtime will look outside of this web application for the resource, and it will automatically cause a redirect (rather than a server forward) to the resource. If the path begins with a forward slash, "/", the runtime will start at the web application's root directory to locate the resource. If the path omits the forward slash, "/", the reference is relative - to the page flow's directory.</p> + to the Page Flow's directory.</p> </blockquote> -<p class="attribute"><a name="return-to" id="return-to"></a>return-to</p> -<p class="partdesc">The return-to attribute always applies to the current page - flow, whether it is a nested page flow or the main page flow. To return to an - action in the “nesting” page flow use the return-action attribute.</p> -<p class="partdesc">The value for the <span class="langinline">return-to</span> - attribute must be a keyword, either <span class="langinline">"currentPage", - </span> or <span class="langinline">"previousPage",</span> or <span class="langinline">"previousAction". - </span></p> -<p class="notepara"><strong>Note:</strong> To clarify the purpose of the <span class="langinline">return-to</span> - attribute, the keywords <span class="langinline">"page"</span> and - <span class="langinline">"action"</span> were deprecated as of WebLogic - Workshop 8.1 Service Pack 2. Instead of <span class="langinline">"page"</span>, - the equivalent function is <span class="langinline">"previousPage"</span>. - Instead of <span class="langinline">"action"</span>, the equivalent - function is <span class="langinline">"previousAction"</span>. </p> -<p class="partdesc"> If the value is <span class="langinline">"currentPage"</span>, +<blockquote> + <p></p> +</blockquote> +<p class="attribute"><a name="return-to" id="return-to"></a>navigateTo</p> +<p class="partdesc">The <span class="langinline">navigateTo</span> attribute has + three possible keyword values:</p> +<p class="partdesc"><span class="langinline"> currentPage<br> + </span><span class="langinline">previousPage<br> + </span><span class="langinline">previousAction</span></p> +<p class="partdesc">The <code>navigateTo</code> attribute always applies to the + current Page Flow, whether it is a nested Page Flow or the main Page Flow. To + return to an action in the main Page Flow use the <code><a href="#returnaction">returnAction</a></code> + attribute.<span class="langinline"> </span></p> +<p class="notepara">If the value is <span class="langinline">"currentPage"</span>, the same JSP page is rendered again by the server, along with any updated data - that occurred as a result of executing the annotated action method. </p> + that occurred as a result of executing the annotated Action method. </p> <p class="notepara">If the value is <span class="notepara">"</span><span class="langinline">previousPage</span><span class="notepara">"</span>, the page that was shown before the current page is rendered. </p> <p class="notepara">If the value is <span class="langinline">"previousAction"</span>, - the previous action in the current page flow is run. </p> -<p class="attribute"><a name="return-action"></a>return-action</p> -<p class="partdesc">The return-action attribute, which is only valid in a <strong>nested</strong> - page flow, causes control to return to the calling (or "nesting") - page flow (leaving the current page flow), and then causes the specified action - to be raised on the calling page flow. </p> + the previous action in the current Page Flow is run.</p> <blockquote> - <p class="attribute"><a name="return-form"></a>return-form</p> - <p class="partdesc">Optional. The return-form attribute, which is only valid - when used with the return-action attribute, causes the given page flow member - variable to be attached to the returned Forward automatically.</p> - <p class="attribute"><a name="return-form-type" id="return-form-type"></a>return-form-type</p> - <p class="partdesc">Optional. The return-form-type attribute, which is only - valid when used with the return-action attribute, is used in conjunction with - the Forward that is returned. Forward takes the actual FormData instance as - the second argument to its constructor. This attribute declares the type of - the form bean that will be returned to the calling page flow.</p> + <p class="notepara"><strong>Note:</strong> To clarify the purpose of the <span class="langinline">return-to</span> + attribute, the keywords <span class="langinline">"page"</span> and + <span class="langinline">"action"</span> were deprecated as of WebLogic + Workshop 8.1 Service Pack 2. Instead of <span class="langinline">"page"</span>, + the equivalent function is <span class="langinline">"previousPage"</span>. + Instead of <span class="langinline">"action"</span>, the equivalent + function is <span class="langinline">"previousAction"</span>.</p> </blockquote> -<p class="notepara"><strong>Note:</strong> If multiple actions with the same name - (such as "success") exist in the calling page flow, either the return-form-type - value or the return-form member variable type will be used to determine the - appropriate action.</p> +<p class="attribute"><a name="returnaction"></a>returnAction</p> +<p class="partdesc">Specifies an Action method in the main Page Flow. The <code>returnAction</code> + attribute, which is only valid in a <strong>nested</strong> Page Flow, causes + control to return to the calling (or "nesting") Page Flow, and then + causes the specified action to be raised on the calling Page Flow. </p> +<blockquote> + <p class="attribute"><a name="outputFormBean"></a>outputFormBean</p> + <p class="partdesc">Optional. The <code>returnFormBean</code> attribute, which + is only valid when used with the <a href="#returnaction"><code>returnAction</code></a> + attribute, causes the specified Page Flow member variable to be attached to + the returned Forward automatically.</p> +</blockquote> +<blockquote> + <p class="attribute"><a name="outputFormBeanType" id="outputFormBeanType"></a>outputFormBeanType</p> + <p class="partdesc">Optional. The <code>returnFormBeanType</code> attribute, + which is only valid when used with the <a href="#returnaction"><code>returnAction</code></a> + attribute, declares the type of the Form Bean that will be returned to the + calling Page Flow. Use this attribute in conjunction with the Forward constructor + that takes a Form Bean instance as the second argument, as shown below.<br> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "done", + returnAction = "done", + outputFormBeanType = Form.class + ) + } + ) + public Forward submit(Form form) + { + return new Forward("done", form); + }</pre> + <p></p> +</blockquote> +<p class="notepara"><strong>Note:</strong> If multiple Actions with the same name + (such as "success") exist in the calling Page Flow, either the <code>outputFormBeanType</code> + value or the <code>outputFormBean</code> member variable type will be used to + determine the appropriate action.</p> +<p class="attribute"><a name="actionoutputs"></a>actionOutputs</p> +<p class="partdesc">Optional. Specifies one or many <span class="langinline"><a href="action-output.html">@Jpf.ActionOutput</a></span> + annotations. The @Jpf.ActionOutput annotation is used to place data on the <code>pageInput</code> + databinding context, from which JSP pages can retreive the data. For details + see <a href="../../guide/netui/guide/conDeclaringPageInputs.html">Declaring + Page Inputs</a> and <a href="action-output.html"><code>@Jpf.ActionOutput</code></a>.</p> <p class="attribute"><a name="redirect"></a>redirect</p> <p class="partdesc">Optional. A boolean, <span class="langinline">true</span> or <span class="langinline">false</span>. Default is <span class="langinline">false</span>. @@ -151,33 +182,69 @@ redirect to the specified destination. Redirecting is useful when you want to clear out any data that was attached to a request, or when it is important that the user's URL bar reflect the actual page that is displayed (instead of the - action name). For details, see the <a href="#remarks">Remarks</a> section.</p> + Action name). For details, see the <a href="#remarks">Remarks</a> section.</p> <div id="topictext"> - <h2>Action Method Signatures</h2> - <p>An action method has several possible signatures. One signature takes no - parameters. For example:</p> - <p><font face="Courier New, Courier, mono">public Forward shopping()</font></p> - <p>The second type of signature uses a form. For example:</p> - <p><font face="Courier New, Courier, mono">public Forward shopping(CheckoutForm - form)</font></p> - <p>The form bean is a class that extends <span class="langinline">com.bea.wlw.netui.pageflow.FormData</span>. - You can define the form bean as an inner class within the page flow class, + <h2>Forward Constructors</h2> + <p>The @Jpf.Forward annotation works in conjuction with a number of different + Forward constructors. (For an exhaustive list of different Forward class constructors, + see the <a href="../../java-class/com/bea/wlw/netui/pageflow/Forward.html">Forward + class</a> Javadoc.)</p> + <p>One constructor takes a String parameter, used to determine navigation. For + example, when a new Forward object is constructed with the parameter <code>"success"</code>, + the <code>@Jpf.Forward</code> annotation determines that the navigation destination + is the JSP page <code>index.jsp</code>:</p> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + path = "index.jsp" + ) + } + ) + protected Forward begin() + { + return new Forward( "success" ); + }</pre> + <p>A second type of constructor takes two parameters: a String and Form Bean. + This is used to attach data to the navigational forward. For example:</p> + <pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + returnAction = "done", + outputFormBeanType = MyFormBean.class + ) + } + ) + public Forward submit(MyFormBean form) + { + return new Forward("success", form); + } +</pre> + <p>A Form Bean is a class that extends <span class="langinline">com.bea.wlw.netui.pageflow.FormData</span>. + You can define the Form Bean as an inner class within the Page Flow class, or separately in the web project.</p> - <p>If you are using the <a href="../../taglib/www.bea.com/workshop/netui-tags-databinding-1.0/declarePageInput.html"><netui-data:declarePageInput> - tag</a> in your JSP, you may use a third type of signature, where you return - a new Forward that contains three parameters. For example:</p> - <pre> /** - * @jpf:action - * @Jpf.Forward name="success" path="next.jsp" - */ - public Forward next() - throws SQLException - { - Item[] items = itemsDB.getAllItems(); - return new Forward("success", "items", items); - } </pre> - <p>In the new Forward, the parameters in <span class="langinline">new Forward("success", - "items", items)</span> for this example are as follows:</p> + <p>If you are using the <a href="action-output.html">@Jpf.ActionOutput</a> annotation, + you may use a third type of signature, where you return a new Forward that + contains three parameters. For example:</p> + <pre> + @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + actionOutputs={ @Jpf.ActionOutput(name="items", type=Item[].class) }, + navigateTo = Jpf.NavigateTo.currentPage + ) + } + ) + protected Forward next() throws SQLException + { + return new Forward( "success", "items", items ); + } + + </pre> + <p>The parameters in <span class="langinline">new Forward("success", + "items", items)</span> have the following roles:</p> </div> <ul> <li> @@ -188,71 +255,63 @@ </li> <li> <div><span class="langinline">"items"</span> is the name of the - page input, as defined in a JSP that is part of this page flow. </div> + page input, as defined in a JSP that is part of this Page Flow. </div> </li> <li> <div><span class="langinline">items</span> is the name of the actual object from which data will be obtained. In this case, <span class="langinline">items</span> - is a table referenced by a database control called by the page flow. For - more information, see the <a href="../../guide/netui/samples/tagSamples/netui_databinding/samDeclarePageInputTag.html"><netui-data:declarePageInput> + is a table referenced by a database control called by the Page Flow. For + more information, see <a href="../../guide/netui/guide/conDeclaringPageInputs.html">Declaring + Page Inputs</a> and <a href="../../guide/netui/samples/tagSamples/netui_databinding/samDeclarePageInputTag.html"><netui-data:declarePageInput> Tag Sample</a>. </div> </li> </ul> -<p>If you need to add more than one page input, you can first create the Forward - object and then call its <span class="langinline">addPageInput</span> method. - For example:</p> -<pre> /** - * @jpf:action - * @Jpf.Forward name="success" path="next.jsp" - */ - public Forward next() - throws SQLException - { - Forward fwd = new Forward("success"); - fwd.addPageInput("products", productsDB.getAllProducts()); - fwd.addPageInput( "items", itemsDB.getAllItems()); - return fwd; - }</pre> +<p>If you need to add more than one action output, you can first create the Forward + object and then call the <span class="langinline"><a href="../../java-class/com/bea/wlw/netui/pageflow/Forward.html#addPageInput(java.lang.String,%20java.lang.Object)">addPageInput</a></span> + method. For example:</p> +<pre> @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "success", + actionOutputs={ + @Jpf.ActionOutput(name="str", type=String.class), + @Jpf.ActionOutput(name="strArray", type=String[].class) + }, + path = "greeting.jsp") + } + ) + protected Forward getGreetings() + { + Forward fwd = new Forward("success"); + fwd.addPageInput( "str", "Hi!" ); + fwd.addPageInput( "strArray", new String[]{ "Hi!", "Hi again!" } ); + return fwd; + }</pre> <h2><a name="remarks"></a> Remarks</h2> <p>The following rules apply to this annotation's use:</p> <ul> - <li>Optionally, you can add a @jpf:catch annotation for exception handling.</li> - <li>The forward's name and its capitalization <strong>must match exactly</strong> - in the @Jpf.Forward annotation and in the return argument of a Forward object. - For example: + <li>Optionally, you can add a <a href="catch.html">@Jpf.Catch</a> annotation + for exception handling.</li> + <li>The the @Jpf.Forward annotation's <code>name</code> attribute must match + exactly (including case sensitivity) to the first parameter of the Forward + constructor. For example: <pre> -/** - * @jpf:action - * @Jpf.Forward name="<strong>goShopping</strong>" path="cart.jsp" - */ - public Forward shopping() - { return new Forward( "<strong>goShopping</strong>" );</pre> - Also note that <span class="langinline">@Jpf.Forward</span> names on exception-handlers - can conflict with <span class="langinline">@Jpf.Forward</span> names on actions - and at the class level. The <span class="langinline">@Jpf.Forward</span> names - that you specify must be unique in the page flow.</li> - <li>You could pass a <span class="langinline">FormData</span> instance as the - second argument to the Forward constructor, which has to take a <span class="langinline">@Jpf.Forward</span> - <b>name</b> as its first argument. For example: - <pre> - /** - * @jpf:action - * @Jpf.Forward name="success" path="DonePage.jsp" - */ - protected Forward PrefsPageSubmit( PrefsForm form ) - { - userInfo.setFavColor( form.getFavColor() ); - DoneForm doneForm = new DoneForm(); - doneForm.setUsername( userInfo.getUsername() ); - doneForm.setPassword( userInfo.getPassword() ); - doneForm.setFavColor( userInfo.getFavColor() ); - return new Forward( "success", doneForm ); - }</pre> + @Jpf.Action( + forwards = { + @Jpf.Forward( + name = "<font color="#FF0000">goShopping</font>", + path = "shopping.jsp" + ) + } + ) + public Forward shopping() + { return new Forward( "<strong><font color="#FF0000">goShopping</font></strong>" );</pre> </li> <li> You can use the @Jpf.Forward as a class-level annotation, resulting in - a global forward for the page flow. A global forward is useful for pages that - are often forwarded to, such as error pages. When you use a global forward, - you do not have to define the forward on every action method. For example: + a global forward available to any method in the Page Flow. A global forward + is useful for pages that are often forwarded to, such as error pages. When + you use a global forward, you do not have to define the forward on every Action + method. For example: <pre> /** * @Jpf.Forward name="errorPage" path="error.jsp" @@ -262,7 +321,7 @@ ... /** - * @jpf:action + * @Jpf.action */ protected Forward loginSubmit( LoginForm loginForm ) { @@ -275,61 +334,80 @@ ... } } - }</pre> + } + + [EMAIL PROTECTED]( + forwards = { @Jpf.Forward(name = "error", path = "errorPage.jsp") } +) +public class TestController extends PageFlowController +{ + @Jpf.Action() + protected Forward someAction() + { + Forward forward = new Forward("error"); + return forward; + } +}</pre> </li> - <li><a name="overloaded"></a>If your page flow uses overloaded actions, you - must be aware of the run-time behavior to avoid unintended results. Here are + <li><a name="overloaded"></a>If your Page Flow uses overloaded Actions, you + must be aware of the runtime behavior to avoid unintended results. Here are the rules when an action forwards to an overloaded action: <ul> - <li> The choice of overload is determined strictly by the form that was - passed in the Forward object. If there was no form passed in the Forward, - the action with no form is used. </li> - <li>If you do not put a form on a Forward object, then there must be an - action that takes no form; otherwise, it will fail.</li> - <li> If a nested page flow returns, the choice of overload is determined - strictly by the <span class="langinline">return-form</span> or <span class="langinline">return-form-type</span> + <li> The choice of overload is determined strictly by the Form Bean that + was passed in the Forward object. If there was no Form Bean passed in + the Forward, the Action with no form is used. </li> + <li>If you do not put a Form Bean on a Forward object, then there must be + an action that takes no Form Bean; otherwise, it will fail.</li> + <li> If a nested Page Flow returns to the main Page Flow, the choice of + overload is determined strictly by the <span class="langinline"><a href="#outputFormBean">outputFormBean</a></span> + or <span class="langinline"><a href="#outputFormBeanType">outputFormBeanType</a></span> attributes on the returning <span class="langinline">@Jpf.Forward</span> - in the nested page flow. If neither of these attributes are present, the - choice of overload is determined strictly by the form that was passed + in the nested Page Flow. If neither of these attributes are present, the + choice of overload is determined strictly by the Form Bean that was passed in the Forward.</li> <li>If a page raises an action, the overload without a form will be chosen first. If all overloads take a form, then it will choose the one whose full classname comes first alphabetically.</li> </ul> <li><a name="scoping"></a>By default, an instance of a Form Bean passed to an - action method is scoped to the <span class="langinline">request</span>. You + Action method is scoped to the <span class="langinline">request</span>. You can alternatively scope a Form Bean instance to the life of the Controller - file. For information about pageflow-scoped forms, see the Remarks section - of the <a href="Action.html">@jpf:action Annotation</a> topic and the help - topic <a href="../../guide/netui/guide/conReqScopedVsPageScopedBean.html">Form + file (this is called a "Page Flow-scoped Form Bean"). For information + about Page Flow-scoped Form Bean, see the Remarks section of the <a href="Action.html">@Jpf.Action + Annotation</a> topic and the help topic <a href="../../guide/netui/guide/conReqScopedVsPageScopedBean.html">Form Bean Scopings</a>. If you merge in Struts actions, you can scope a Form Bean instance to the <span class="langinline">session</span> object, as explained in <a href="../../guide/netui/guide/conStrutsMerge.html">Merging Struts Artifacts Into Page Flows</a>. <p>The following list describes advanced behavior that is important to know - only for cases when you are forwarding between two actions. This presents - scenarios when action A forwards to action B:</p> + only for cases when you are forwarding between two Actions methods. This + presents scenarios when Action A forwards to Action B:</p> <ul> - <li>If A is pageflow-scoped and B is not, B gets a new instance of the Form - Bean. </li> - <li>If A is pageflow-scoped and B is not, <strong>and</strong> if A explicitly - passes its Form Bean on the Forward to B, B will use A's instance of the - Form Bean (the member variable).</li> - <li>If A is not pageflow-scoped and B is pageflow-scoped, B will not use - the Form Bean instance that A created. </li> - <li>If A is not pageflow-scoped and B is pageflow-scoped, <strong>and</strong> - if A explicitly passes its Form Bean instance on the Forward to B, B will - not only use A's Form Bean instance, but the member variable will be set - to the instance that A passed. </li> - <li>If A is pageflow-scoped and B is pageflow-scoped, then B will use A's - Form Bean instance (the member variable).</li> + <li>If action A takes a Page Flow-scoped Form Bean and action B does not, + B receives a newly constructed request-scoped instance of the Form Bean. + </li> + <li>If A takes a Page Flow-scoped Form Bean and B does not, <strong>and</strong> + if A explicitly passes its Form Bean on the Forward to B, B will use A's + Page Flow-scoped instance of the Form Bean.</li> + <li>If A takes a request-scoped Form Bean and B takes a Page Flow-scoped + Form Bean, B will not use the (request-scoped) Form Bean instance that + was created for A, instead B will use the Page Flow-scoped Form Bean. + </li> + <li>If A takes a request-scoped Form Bean and B takes a Page Flow-scoped + Form Bean, <strong>and</strong> if A explicitly passes its Form Bean instance + on the Forward to B, B will not only use A's (request-scoped) Form Bean + instance, <em>but the Page Flow-scoped Form Bean will be re-set to carry + the same data as the instance that A passed</em>. </li> + <li>If A takes a Page Flow-scoped Form Bean and B takes a Page Flow-scoped + Form Bean, then B will use A's Form Bean instance.</li> </ul> </li> - <li>When an action method causes navigation to a page, it forwards the request + <li>When an Action method causes navigation to a page, it forwards the request to the URL for that page. Any attributes that were attached to the original request are available for the next page to use. This means that the user can send a request for an action, such as "<span class="langinline">GoToLogin.do</span>". - The page flow can attach data to the request and forward to a page, such as + The Page Flow can attach data to the request and forward to a page, such as "<span class="langinline">login.jsp</span>", which is sent back to the browser. The user's URL address bar might read "http://server/welcomeFlow/GoToLogin.do". However, the page displayed is actually "http://server/welcomeFlow/login.jsp". @@ -337,7 +415,7 @@ in the <span class="langinline">@Jpf.Forward</span> annotation. In this case, the server can respond to the browser and tell it to navigate somewhere else. If the user requests ("<span class="langinline">GoToLogin.do</span>"), - the page flow could redirect to "<span class="langinline">login.jsp</span>", + the Page Flow could redirect to "<span class="langinline">login.jsp</span>", which would cause the browser to navigate directly to "http://server/welcomeFlow/login.jsp". The latter URL is shown in the user's URL bar. Thus the redirect attribute is useful for two scenarios:</p> @@ -353,16 +431,15 @@ </ul> <p class="listplain"> </p> <p class="relatedtopics">Related Topics</p> -<p><a href="action.html">@jpf:action Annotation</a></p> -<p><a href="catch.html">@jpf:catch Annotation</a></p> -<p><a href="controller.html">@jpf:controller Annotation</a></p> -<p><a href="exception-handler.html">@jpf:exception-handler Annotation</a></p> -<p><a href="message-resources.html">@jpf:message-resources Annotation</a></p> -<p><a href="validation-error-forward.html">@jpf:validation-error-forward Annotation</a></p> +<p><a href="action.html">@Jpf.Action Annotation</a></p> +<p><a href="catch.html">@Jpf.Catch Annotation</a></p> +<p><a href="controller.html">@Jpf.Controller Annotation</a></p> +<p><a href="exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> +<p><a href="message-resources.html">@Jpf.MessageResources Annotation</a></p> <p><a href="../../guide/netui/guide/conReqScopedVsPageScopedBean.html">Form Bean Scopings</a></p> <p><a href="../../guide/netui/samples/samDataFlow.html">Data Flow Sample</a></p> -<!-- InstanceEndEditable --> +<!-- InstanceEndEditable --> <script language="JavaScript"> writeTopicInfo(); </script> Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/message-resources.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/message-resources.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/message-resources.html Tue Aug 31 15:54:21 2004 @@ -3,7 +3,7 @@ <html><!-- InstanceBegin template="/Templates/Tag.dwt" codeOutsideHTMLIsLocked="false" --> <head> <!-- InstanceBeginEditable name="doctitle" --> -<title>@Jpf.MessageResources Annotation</title> +<title>@Jpf.MessageResource Annotation</title> <!-- InstanceEndEditable --> <!--(Meta)==========================================================--> @@ -37,85 +37,68 @@ <script language="JavaScript"> displayInFrames(); </script> -<!-- InstanceBeginEditable name="body" --> -<div id="topictitle"> - <h1 class="Title">@Jpf.MessageResources Annotation</h1> +<!-- InstanceBeginEditable name="body" --> +<div id="topictitle"> + <h1 class="Title">@Jpf.MessageResource Annotation</h1> </div> -<div id="topictext"> +<div id="topictext"> <p>You can use the <span class="langinline">@Jpf.MessageResources</span> annotation - at the page flow class level to specify a message bundle. Using message resources + at the Page Flow class level to specify a message bundle. Using message resources allows you to internationalize your web applications by <strong>not hard-coding</strong> labels in your JSP pages. For example, an ErrorMessages.properties resource file could contain messages to display when form validation errors occur.</p> <h2>Syntax</h2> - <p class="syntax">@Jpf.MessageResources</p> - <p class="syntaxindent">resources = "<property-resources>"</p> - <p class="syntaxindent">[ key = "<bundle-key-name>" ]</p> + <pre> + @Jpf.MessageResource( + <a href="#resources">name</a> = "<em>resource_name</em>", + <a href="#key">bundleKey</a> = "<em>bundle</em>" + ) +</pre> <h2>Attributes</h2> - <p class="attribute"><a name="resources" id="MessageResources"></a>resources</p> - <p class="partdesc">Required. A resource that contains message properties, - such as an Errors.properties file that you create separately and place in a - subfolder under the page flow's /WEB-INF/classes folder. For example:</p> - <p class="partdesc"><font face="Courier New, Courier, mono">@Jpf.MessageResources - resources="validation.ErrorMessages"</font></p> - <p class="partdesc">The page flow runtime will look for the messages in a - subfolder of the web project's <span class="langinline">/WEB-INF</span> - folder, either:</p> + <p class="attribute"><a name="resources" id="MessageResources"></a>name</p> + <p class="partdesc">Required. A resource that contains message properties, such + as a file that you create separately and place in a subfolder under the web + application's /WEB-INF folder. For example:</p> + <pre> @Jpf.MessageResource( name = "properties.bundle1" )</pre> + <p class="partdesc">The Page Flow runtime will look for the <code>bundle1.properties</code> + file in a subfolder of the web project's <span class="langinline">/WEB-INF</span> + folder. Note that the file can also packaged in a JAR file. [tbd: research + the actual seach mechanism]</p> </div> -<ul> - <li> - <div class="partdesc"> - /<span class="langinline">WEB-INF/classes/validation/ErrorMessages.properties</span> - </div> - </li> - <li> - <div class="partdesc"> - Or in a JAR file in <span class="langinline">/WEB-INF/lib</span> - </div> - </li> -</ul> -<div> - <p class="attribute"><a name="key" id="MessageResources"></a>key</p> - <p class="partdesc">Optional. You can specify the name of the <span class="langinline">ServletContext</span> - attribute in which to store the Bundle read from the - <property-resources>. In most cases you can omit this attribute and - accept the default of <span class="langinline">org.apache.struts.Globals.MESSAGE_KEY</span>, - which works with the <netui:error> and <netui:errors> JSP tags - provided by WebLogic Workshop.</p> +<div> + <p class="attribute"><a name="key" id="MessageResources"></a>bundleKey</p> + <p class="partdesc">Optional. You can specify the name of the <span class="langinline">ServletContext</span> + attribute in which to store the properties file identified by <code>name</code>. + In most cases you can omit this attribute and accept the default of <span class="langinline">org.apache.struts.Globals.MESSAGE_KEY</span>, + which works with the <a href="../../taglib/www.bea.com/workshop/netui-tags-html-1.0/error.html"><netui:error></a> + and <a href="../../taglib/www.bea.com/workshop/netui-tags-html-1.0/errors.html"><netui:errors></a> + JSP tags provided by WebLogic Workshop.</p> <h2>Remarks</h2> <p>The following rules apply to this annotation's use:</p> <ul style="list-style: disc;" type="disc"> - <li> - <p>The message property resource cannot reside in the WEB-INF/... - directory of another web project. The *.properties file must reside in a - /WEB-INF/classes/<folder>/ directory, or in a JAR in /WEB-INF/lib - (in a JAR), for this web project.</p> + <li> + <p>The message property resource cannot reside in the /WEB-INF directory + of another web project. The <code>*.properties</code> file must reside + in a /WEB-INF/classes/<folder>/ directory, or in a JAR in /WEB-INF/lib + (in a JAR), for this web project. [tbd: true?]</p> </li> - <li>For a sample page flow that demonstrates form validation and the use of - the message properties, see the following page flow. Also see the - <netui:error> tag used in this sample page flow's JSP files.</li> + <li>For a sample Page Flow that demonstrates form validation and the use of + the message properties, see the following Page Flow. </li> <p><font face="Courier New, Courier, mono"><WEBLOGIC_HOME>\samples\workshop\SamplesApp\WebApp\validation\Controller.jpf</font></p> <li>For sample message properties files, see:</li> <p><font face="Courier New, Courier, mono"><WEBLOGIC_HOME>\samples\workshop\SamplesApp\WebApp\WEB-INF\classes\validation\basic\Messages.properties</font></p> <p>and:</p> <p><font face="Courier New, Courier, mono"><WEBLOGIC_HOME>\samples\workshop\SamplesApp\WebApp\WEB-INF\classes\validation\validator\Messages.properties</font></p> </ul> - <div> + <div> <p class="relatedtopics">Related Topics</p> - - <p><a href="catch.html">@jpf:catch Annotation</a></p> - - <p><a href="controller.html">@jpf:controller Annotation</a></p> - - <p><a href="exception-handler.html">@jpf:exception-handler Annotation</a></p> - - <p><a href="forward.html">@jpf:forward Annotation</a></p> - <p><a href="validation-error-forward.html">@jpf:validation-error-forward Annotation</a></p> - <p><a href="../../guide/netui/guide/conGettingStartedPageFlows.html">Getting - Started with Page Flows</a></p> - <p> </p> + <p><a href="catch.html">@Jpf.Catch Annotation</a></p> + <p><a href="controller.html">@Jpf.Controller Annotation</a></p> + <p><a href="exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> + <p><a href="forward.html">@Jpf.Forward Annotation</a></p> </div> - <!-- InstanceEndEditable --> +</div> +<!-- InstanceEndEditable --> <script language="JavaScript"> writeTopicInfo(); </script> Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/navJpfAnnotations.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/navJpfAnnotations.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/navJpfAnnotations.html Tue Aug 31 15:54:21 2004 @@ -43,13 +43,13 @@ <h2 class="navtitle">Page Flow Annotations</h2> <p class="navtitle">The page flow annotations used in web applications define the behavior of the page flow controller class and its methods.</p> - <p class="navtitle"><a href="../../javadoc-tag/jpf/action.html">@jpf:action + <p class="navtitle"><a href="../../javadoc-tag/jpf/action.html">@Jpf.Action Annotation</a></p> <p class="navdesc">Designates an action method. Optionally, this annotation - may set login and J2EE role requirements. Without a <span class="langinline">@jpf:action</span> + may set login and J2EE role requirements. Without a <span class="langinline">@Jpf.action</span> annotation, an action method will not be recognized by the page flow runtime as an action method. This annotation may be used at the method-level only.</p> - <p class="navtitle"><a href="../../javadoc-tag/jpf/catch.html">@jpf:catch Annotation</a></p> + <p class="navtitle"><a href="../../javadoc-tag/jpf/catch.html">@Jpf.Catch Annotation</a></p> <p class="navdesc">Provides information used by the page flow runtime to catch exceptions and possibly route them to error handlers. This annotation may be used on action methods and the page flow class, and in the global page flow @@ -60,27 +60,25 @@ must be logged in; whether logged-in users must be associated with existing J2EE roles; and whether a Struts XML configuration file should be merged into the page flow. This annotation may be used at the page flow class level only.</p> - <p class="navtitle"><a href="../../javadoc-tag/jpf/exception-handler.html">@jpf:exception-handler + <p class="navtitle"><a href="../../javadoc-tag/jpf/exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> - <p class="navdesc">Designates an error handler method. Without a <span class="langinline">@jpf:exception-handler</span> + <p class="navdesc">Designates an error handler method. Without a <span class="langinline">@Jpf.exception-handler</span> annotation, the page flow runtime will not recognize an error handler method. </p> - <p class="navtitle"><a href="../../javadoc-tag/jpf/forward.html">@jpf:forward + <p class="navtitle"><a href="../../javadoc-tag/jpf/forward.html">@Jpf.Forward Annotation</a></p> - <p class="navdesc">Describes a location to which the page flow runtime should - go to next. The location may be a JSP, a page flow, or an action method. This - annotation may be used on action methods and the page flow class, and in the - global page flow that resides in WEB-INF/src/global/Global.app.</p> - <p class="navtitle"><a href="../../javadoc-tag/jpf/message-resources.html">@jpf:message-resources - Annotation</a></p> - <p class="navdesc">Specifies a message bundle, allowing you to implement - validation in the page flow's form beans. This annotation may be used at the - page flow class level only.</p> - <p class="navtitle"><a href="../../javadoc-tag/jpf/validation-error-forward.html">@jpf:validation-error-forward - Annotation</a></p> - <p class="navdesc">Indicates which page should be loaded, or which action should - be run, if a form validation error occurs as a result of running the annotated - action. This annotation may be used at the method level only.</p> + <p class="navdesc">Describes a location to which the page flow runtime should + go to next. The location may be a JSP, a page flow, or an action method. This + annotation may be used on action methods and the page flow class, and in the + global page flow that resides in WEB-INF/src/global/Global.app.</p> + <p class="navtitle"><a href="../../javadoc-tag/jpf/message-resources.html">@Jpf.MessageResources + Annotation</a></p> + <p class="navdesc">Specifies a message bundle, allowing you to implement validation + in the page flow's form beans. This annotation may be used at the page flow + class level only.</p> + <p class="navtitle"><a href="../../javadoc-tag/jpf/message-resources.html">@Jpf.SimpleAction + Annotation</a></p> + <p class="navdesc">Specifies a [tbd].</p> <p class="navtitle"><a href="../../javadoc-tag/common/control.html">@common:control Annotation</a></p> <p class="navdesc">Indicates that a member variable in a page flow references Modified: incubator/beehive/trunk/netui/docs/guide/reference/jpf/simple-action.html ============================================================================== --- incubator/beehive/trunk/netui/docs/guide/reference/jpf/simple-action.html (original) +++ incubator/beehive/trunk/netui/docs/guide/reference/jpf/simple-action.html Tue Aug 31 15:54:21 2004 @@ -44,13 +44,22 @@ <div id="topictext"> <p>[tbd]</p> <h2>Syntax</h2> - <p class="syntax">[tbd] </p> + <pre> + @Jpf.SimpleAction( + name = "<em>name</em>", + path = "<em>path</em>", + navigateTo = <strong>[currentPage | previousPage | previousAction | page]</strong> + )</pre> <h2>Attributes</h2> <p class="attribute"><a name="form" id="form"></a>[tbd]</p> <h2><a name="remarks"></a>Remarks</h2> <p>[tbd]</p> <p class="relatedtopics">Related Topics</p> - <p><a href="catch.html">[tbd]</a><a href="../../guide/netui/guide/conReqScopedVsPageScopedBean.html"></a></p> + <p class="relatedtopics">Related Topics</p> + <p><a href="catch.html">@Jpf.Catch Annotation</a></p> + <p><a href="controller.html">@Jpf.Controller Annotation</a></p> + <p><a href="exception-handler.html">@Jpf.ExceptionHandler Annotation</a></p> + <p><a href="forward.html">@Jpf.Forward Annotation</a></p> <h3>Samples</h3> <p><a href="../../guide/netui/samples/samDataFlow.html">[tbd]</a></p> </div>
