@jpf:action Annotation

You can use the @jpf:action 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 FormData (or ActionForm) member variable; set login requirements for users; or indicate that the action method will not update any member data in the page flow.

For information about the method signatures of an action method, see the @jpf:forward Annotation. That topic also describes the run-time behavior of overloaded actions, in the Remarks section.

Syntax

@jpf:action

[ form = "<form name>" ]

[ login-required = "{ true | false }"

[ read-only = "{ true | false }" ]

[ roles-allowed = "<J2EE role name> [ , <J2EE role name> ] " ]

Attributes

form

Optional. A Form Bean instance that will be passed to the method. For more information, see the Remarks section.

Optional. A boolean that indicates whether the user must be logged-in to use this action method. If set to login-required="true" the action method can only be run if the user is logged in. That is, the page flow runtime checks to see if request.getUserPrincipal() == null. If it is, then the exception com.bea.wlw.netui.pageflow.NotLoggedInException 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.

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 Handling Exceptions in Page Flows.

read-only

Optional. The default is read-only="false". Use this attribute to indicate your intention that this action will not 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.

roles-allowed

Optional. Specifies the name of one or more security roles that are defined in the web project's /WEB-INF/web.xml 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 Role-Based Security.

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 @jpf:controller (if used). That is, security roles that are specified at the method level with @jpf:action add to any allowable roles defined at the class level with @jpf:controller. If the user is not logged-in, a com.bea.wlw.netui.pageflow.NotLoggedInException will be thrown. If the user is not in an appropriate role, a com.bea.wlw.netui.pageflow.UnfulfilledRolesException will be thrown. For more information, see Handling Exceptions in Page Flows.

validation-error-page (Deprecated)

This attribute on @jpf:action has been deprecated, as of WebLogic Workshop 8.1 Service Pack 2. Instead you can use the @jpf:validation-error-forward Annotation.

Remarks

The following rules apply to this annotation's use:

Without an @jpf:action annotation, a method will not be recognized by the page flow runtime as an action method.
You cannot use the jpf:action annotation at the page flow class level.
When you drag an action icon onto the palette in a page flow's Flow View, the @jpf:action 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:

/**
 * @jpf:action
 */
 public Forward shopping()
 { 
     return new Forward( "success" ); 
 }
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 @jpf:forward 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 @jpf:forward Annotation.

You can cause an action to read and update from a Form Bean instance, by using the @jpf:action form="<form name>" annotation. For example, in the page flow class:
```
            
	  /**           
	   * @jpf:action form="_pageFlowForm"         
	   */           
	  protected Forward doit( MyForm myForm )           
	  {             
	       // _pageFlowForm is a member variable               
	       // Note that myForm == _pageFlowForm              
	                 
	       String name = _pageFlowForm.getFullName();               
	       ...          
	  }
```
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 @jpf:forward Annotation and the help topic Page Flow Scopings.

If you enable login-required="true" 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:

	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
    {
        login( loginForm.getUsername(), loginForm.getPassword() );
        userName = loginForm.getUsername();
        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 )
    {
        return new Forward( "loginPage" );
    }

You can also use the Global.app file, which the Page Flow Wizard provides in your web project's WEB-INF/src/global folder. In your page flow, you may notice the line:

// protected global.Global globalApp;

It is not required that you uncomment this line in order to have access to methods in Global.app. However, if you do uncomment it, this globalApp declaration will give your page flow easy access to public methods and variables in Global.app.

In the Global.app file, check that you have code such as:

/**
 * @jpf:catch type="Exception" method="handleException"
 */
 public class Global extends GlobalApp
 { 

     /**
      * General handler for uncaught exceptions.
      *
      * @jpf:exception-handler
      * @jpf:forward name="errorPage" path="/error.jsp"
      */
      protected Forward handleException( Exception ex, String actionName,
      String message, FormData form )
      {
          System.err.print( "[" + getRequest().getContextPath() + "] " );
          System.err.println( "Unhandled exception caught in Global.app:" );
          ex.printStackTrace();
          return new Forward( "errorPage" );
      }

      ...

 }

The roles-allowed 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.

Note that currently using the following IDE menu option defines a new security role in the application's /META-INF/application.xml file:

Tools > Security > Create New Security Role...

However, /META-INF/application.xml 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.

Samples

Data Flow Sample