@jpf:forward Annotation

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.

return-to

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.

The value for the return-to attribute must be a keyword, either "currentPage", or "previousPage", or "previousAction".

Note: To clarify the purpose of the return-to attribute, the keywords "page" and "action" were deprecated as of WebLogic Workshop 8.1 Service Pack 2. Instead of "page", the equivalent function is "previousPage". Instead of "action", the equivalent function is "previousAction".

If the value is "currentPage", 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.

If the value is "previousPage", the page that was shown before the current page is rendered.

If the value is "previousAction", the previous action in the current page flow is run.

return-action

The return-action attribute, which is only valid in a nested 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.

return-form

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.

return-form-type

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.

Note: 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.

redirect

Optional. A boolean, true or false. Default is false. When set to true, navigation causes a browser 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 Remarks section.

 /**
  * @jpf:action
  * @jpf:forward name="success" path="next.jsp"
  */
  public Forward next()
      throws SQLException
  {
      Item[] items = itemsDB.getAllItems();
      return new Forward("success", "items", items);
  } 

• "success" is the Forward name, and its value matches the name attribute's value on the @jpf:forward annotation. This match causes navigation to the next.jsp page when the action is run.
• "items" is the name of the page input, as defined in a JSP that is part of this page flow.
• items is the name of the actual object from which data will be obtained. In this case, items is a table referenced by a database control called by the page flow. For more information, see the <netui-data:declarePageInput> Tag Sample.

If you need to add more than one page input, you can first create the Forward object and then call its addPageInput method. For example:

 /**
  * @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;
  }

Remarks

The following rules apply to this annotation's use:

• 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:

   
  /** 
    * @jpf:forward name="errorPage" path="error.jsp"        
    */ 
    public class WelcomeFlow extends PageFlowController 
    { 
        ... 
         
        /** 
         * @jpf:action 
         */ 
         protected Forward loginSubmit( LoginForm loginForm ) 
         { 
             if ( userManagerBusinessControl.isOutOfService() ) 
             { 
                  return new Forward( "errorPage" ); 
             } 
             else 
             { 
                  ... 
             } 
         } 
    }

  Also note that @jpf:forward names on exception-handler methods (i.e., methods marked with the @jpf:exception-handler annotation) cannot conflict with @jpf:forward names at the class level or method level. The @jpf:forward names on exception-handler methods must be unique in the page flow class.
• Optionally, you can add a @jpf:catch annotation for exception handling.
• The forward's name and its capitalization must match exactly in the @jpf:forward annotation and in the return argument of a Forward object. For example:

  /**
   * @jpf:action
   * @jpf:forward name="goShopping" path="cart.jsp"
   */
   public Forward shopping()
   { return new Forward( "goShopping" 

• You could pass a FormData instance as the second argument to the Forward constructor, which has to take a @jpf:forward name as its first argument. For example:

      /**
       * @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 );
      }

• If your page flow uses overloaded actions, you must be aware of the run-time behavior to avoid unintended results. Here are the rules when an action forwards to an overloaded action:
  • 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.
  • 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.
  • If a nested page flow returns, the choice of overload is determined strictly by the return-form or return-form-type attributes on the returning @jpf:forward 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 Forward.
  • 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.
• By default, an instance of a Form Bean passed to an action method is scoped to the request. 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 @jpf:action Annotation topic and the help topic Form Bean Scopings. If you merge in Struts actions, you can scope a Form Bean instance to the session object, as explained in Merging Struts Artifacts Into Page Flows.

  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:

  • If A is pageflow-scoped and B is not, B gets a new instance of the Form Bean.
  • If A is pageflow-scoped and B is not, and 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).
  • If A is not pageflow-scoped and B is pageflow-scoped, B will not use the Form Bean instance that A created.
  • If A is not pageflow-scoped and B is pageflow-scoped, and 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.
  • If A is pageflow-scoped and B is pageflow-scoped, then B will use A's Form Bean instance (the member variable).
• 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 "GoToLogin.do". The page flow can attach data to the request and forward to a page, such as "login.jsp", 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".

  An alternative method of navigation is by using the redirect attribute in the @jpf:forward annotation. In this case, the server can respond to the browser and tell it to navigate somewhere else. If the user requests ("GoToLogin.do"), the page flow could redirect to "login.jsp", 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:

• When you want to clear out any data that was attached to a request.
• When it is important that the user's URL bar reflect the actual page that is displayed.

Related Topics

@jpf:action Annotation

@jpf:catch Annotation

@jpf:controller Annotation

@jpf:exception-handler Annotation

@jpf:message-resources Annotation

@jpf:validation-error-forward Annotation

Form Bean Scopings

Data Flow Sample