7.2 What Are ActionForms?


Almost every web application has to accept input from users. Some examples of user input are usernames and passwords, credit card information, and billing and shipping address information. HTML provides the necessary components to render the input fields in a browser, including text boxes, radio buttons, checkboxes, and buttons. When you're building these types of pages, you must nest the input components inside HTML form elements. Example 7-1 illustrates a very basic sign-in page, similar to the one used in the Storefront application.

Example 7-1. A simple sign-in page
<html> <head> <title>Example 7-1. OReilly Struts Book</title> <link rel="stylesheet" href="stylesheets/main.css" type="text/css"> </head> <body> <form method="post" action="/action/signin"> <!-- The table layout for the email and password fields --> <table BORDER="0" cellspacing="0" cellpadding="0"> <tr>   <td>Email: </td>   <td>&nbsp; </td>   <td>     <input type="text" name="email" size="20" maxlength="20"/>   </td> </tr> <tr>   <td>Password:</td>   <td>&nbsp; </td>   <td >     <input type="text" name="password" size="20" maxlength="25"/>   </td>     </tr>    <!-- The table layout for the signin button -->   <table width="250" border="0"> <tr>   <td>     <input type="submit" name="Submit" value="Signin" >   </td>       </tr> </table>   </form> </body> </html>

When the user presses the Signin button on the HTML form from Example 7-1, the values within the fields are submitted along with the HTTP request. The server application can retrieve the values that were entered, perform input validation on the data, and then pass the data to another component in the application where the actual authentication process occurs. If the input data fails the input validation rules, the application should return to the previous location, redisplay some or all of the values entered, and display an error message indicating that the login attempt failed.

Manually performing all of this functionality, retrieving the values, executing the validation, and displaying error messages on failure can be a daunting task. This type of behavior is performed in many places throughout a web application, and it would be nice to have it taken care of by the framework and to be able to reuse it across applications.

Fortunately, the Struts framework does provide this functionality and will handle these tasks on behalf of your application. The Struts framework relies on the org.apache.struts.action.ActionForm class as the key component for handling these tasks.

The ActionForm class is used to capture input data from an HTML form and transfer it to the Action class. Because users often enter invalid data, web applications need a way to store the input data temporarily so that it can be redisplayed when an error occurs. In this sense, the ActionForm class acts as a buffer to hold the state of the data the user entered while it is being validated. The ActionForm also acts as a "firewall" for your application in that it helps to keep suspect or invalid input out of your business tier until it has been scrutinized by the validation rules. Lastly, when data is returned from the business tier, a particular ActionForm can be populated and used by a JSP page to render the input fields for an HTML form. This allows more consistency for your HTML forms, as they always pull data from the ActionForm, not from different JavaBeans.

When the user-input data does pass input validation, the ActionForm is passed into the execute( ) method of the Action class. From there, the data can be retrieved from the ActionForm and passed on to the business tier.

Because the ActionForm imports packages from the Servlet API, you shouldn't pass the ActionForm to the business tier doing so would couple the business methods to the Servlet API and make it more difficult to reuse the business tier components. Instead, the data within the ActionForm should be transferred to an object from the domain model. A common approach is to create a DTO and populate it with the data from the ActionForm.


You don't have to declare an ActionForm for every HTML form in your application. The same ActionForm can be associated with one or more action mappings. This means that they can be shared across multiple HTML forms. For example, if you had a wizard interface where a set of data was entered and posted across multiple pages, you could use a single ActionForm to capture all of this data, a few fields at a time.

7.2.1 ActionForms and Scope

ActionForms can have two different levels of scope: request and session. If request scope is used, the ActionForm is available only until the end of the request/ response cycle. Once the response has been returned to the client, the ActionForm and the data within it are no longer accessible.

If you need to keep the form data around for longer than a single request, you can configure an ActionForm to have session scope. This might be necessary if your application captures data across multiple pages, like a wizard dialog does. An ActionForm that has been configured with session scope will remain in the session until it's removed or replaced with another object, or until the session times out. The framework doesn't have a built-in facility for automatically cleaning up session-scoped ActionForm objects. As with any other object placed into the HttpSession, it's up to the application to routinely perform cleanup on the resources stored there. This is slightly different from what happens with objects placed into request scope, because once the request is finished, they no longer can be referenced and so can be reclaimed by the garbage collector.

Unless you need to hold the form data across multiple requests, you should use request scope for your ActionForm objects.

If you don't specify the scope attribute for an action mapping, the ActionForm will default to session scope. To be safe, you should always explicitly specify the scope of the ActionForm. To see how to specify the scope for an action element, see "The Struts Configuration DTD" in Chapter 4.


When the controller receives a request, it attempts to recycle an ActionForm instance from either the request or the session, depending on the scope that the ActionForm has in the action element. If no instance is found, a new instance is created.

7.2.2 The Lifecycle of an ActionForm

The section "Using the Struts ActionForm" in Chapter 3 described the steps the framework takes when an ActionForm is being used by an application. From these steps, it's easy to get a picture of the lifecycle of an ActionForm. Figure 7-4 illustrates the main steps taken by the framework that have some effect on the ActionForm.

Figure 7-4. The lifecycle of an ActionForm
figs/jstr2_0704.gif


Figure 7-4 shows only the steps that are relevant to an ActionForm, not all those that a request goes through during request processing. Notice that when an ActionForm detects one or more validation errors, it performs a forward back to the resource identified in the input attribute. The data that was sent in the request is left in the ActionForm so that it can be used to repopulate the HTML fields.

7.2.3 Creating an ActionForm

The ActionForm class provided by the Struts framework is abstract, and you need to create subclasses of it to capture your application-specific form data. Within your subclass, you should define a property for each field that you want to capture from the HTML form. For example, suppose you want to capture the email and password fields from a form, similar to the one in Example 7-1. Example 7-2 illustrates the LoginForm for the Storefront application that can be used to store and validate the email and password fields.

Example 7-2. The LoginForm stores the email and password fields
package com.oreilly.struts.storefront.security; import javax.servlet.http.HttpServletRequest; import org.apache.struts.action.*; public class LoginForm extends ActionForm {   private String email = null;   private String password = null;   public void setEmail(String email) {     this.email = email;   }   public String getEmail( ) {     return (this.email);   }   public String getPassword( ) {     return (this.password);   }   public void setPassword(String password) {     this.password = password;   }   /**    * Validate the properties that have been sent from the HTTP request,    * and return an ActionErrors object that encapsulates any    * validation errors that have been found. If no errors are found, return    * an empty ActionErrors object.    */   public ActionErrors validate(ActionMapping mapping, HttpServletRequest request) {     ActionErrors errors = new ActionErrors( );     if( getEmail( ) == null || getEmail( ).length( ) < 1 ) {       errors.add("email", new ActionMessage("security.error.email.required"));     }     if( getPassword( ) == null || getPassword( ).length( ) < 1 ){       errors.add("password", new ActionMessage("security.error.password.required"));     }     return errors;   }   public void reset(ActionMapping mapping, HttpServletRequest request) {     /** Because this ActionForm should be request-scoped, do nothing here.      *  The fields will be reset when a new instance is created. We could      *  have just not overriden the parent reset( ) method, but we did so      *  to provide an example of the reset( ) method signature.      */   } }

When the form is submitted, an instance of the LoginForm will be created and populated from the request parameters. The framework does this by matching each request parameter name against the corresponding property name in the ActionForm class.

The ActionForm is populated from request parameters, not request attributes. If you are forwarding from one action to another, you can't add a request attribute and expect that the ActionForm will be populated from it. Request parameters and request attributes are two separate resources.


7.2.3.1 The validate( ) method

The RequestProcessor may call the validate( ) method for every request. Whether it's called depends on two things. First, an ActionForm must be configured for an action mapping. This means that the name attribute for an action element must correspond to the name attribute of one of the form-bean elements in the configuration file.

The second condition that must be met for the RequestProcessor to invoke the validate( ) method is that the validate attribute in the action mapping must have a value of true. The following fragment shows an action element that uses the LoginForm from Example 7-2 and meets both requirements:

<action    path="/signin"    type="com.oreilly.struts.storefront.security.LoginAction"    scope="request"    name="loginForm"    validate="true"    input="/security/signin.jsp">    <forward name="Success" path="/index.jsp" redirect="true"/>    <forward name="Failure" path="/security/signin.jsp" redirect="true"/>  </action>

When the signin action is invoked, the framework will populate an instance of a LoginForm using the values it finds in the request. Because the validate attribute has a value of true, the validate() method in the LoginForm will be called. Even if the validate attribute is set to false, the ActionForm still will be populated from the request.

The validate() method in the base ActionForm class simply returns null. If you want to perform validation on the data submitted with the request, you'll need to override the validate( ) method in your ActionForm subclasses, as in Example 7-2.


The validate() method may return an ActionErrors object, depending on whether any validation errors were detected; it also can return null if there are no errors. The framework will check for both null and an empty ActionErrors object. This saves you from having to create an instance of ActionErrors when there are no errors. The ActionError class and its parent class, ActionMessage, are discussed later in this chapter.

7.2.3.2 The reset( ) method

The reset() method has been a bane for much of the Struts user community at one time or another. Exactly when the reset() method is called and what should be done within it almost always are misinterpreted. This doesn't mean that one implementation is more correct than another, but many new Struts developers pick up misconceptions about reset() that they have a hard time shaking.

As Figure 7-4 showed, the reset( ) method is called for each new request, regardless of the scope of the ActionForm, before the ActionForm is populated from the request. The method was originally added to the ActionForm class to facilitate resetting Boolean properties back to their defaults. To understand why they need to be reset, it's helpful to know how the browser and the HTML form-submit operation process checkboxes.

When an HTML form contains checkboxes, only the values for the checkboxes that are checked are sent in the request. Those that are not checked are not included as a request parameter. The reset() method was added to allow applications to reset the Boolean properties in the ActionForm to false--because false wasn't included in the request, it was possible for the Boolean values to be stuck in the true state.

The reset() method in the base ActionForm contains no default behavior, as no properties are defined in this abstract class. Applications that extend the ActionForm class are allowed to override this method and reset the ActionForm properties to whatever state they want. This may include setting Boolean properties to true or false, setting String values to null or some initialized value, or even instantiating instances of other objects that the ActionForm holds on to. For an ActionForm that has been configured with request scope, the framework will create a new instance for each new request; hence, there's not much need to reset the values back to any default state. ActionForms that are configured with session scope are different, however, and this is where the reset() method comes in handy.

7.2.4 Declaring ActionForms in the Struts Configuration File

Once you have created a class that extends ActionForm, you need to configure the class in the Struts configuration file. The first step is to add a new form-bean element to the form-beans section of the file:

<form-beans>    <form-bean      name="loginForm"      type="com.oreilly.struts.storefront.security.LoginForm"/> </form-beans>

The value for the type attribute must be a fully qualified Java class name that is a descendant of ActionForm.

Once you have defined your form-bean, you can use it in one or more action elements. It's common to share one ActionForm across several actions. For example, suppose there was an admin application that managed the items in the Storefront application. There would need to be an HTML form for adding new items to the system. This might be the createItem action. There also would need to be a getItemDetail action to show the details of an existing item. These HTML forms would look similar, but they might be submitted to different actions. Still, because they contained the same properties, both forms could use the same ActionForm.

To use an ActionForm in an action element, you need to specify a few attributes for each action mapping that uses the ActionForm. These attributes are name, scope, and validate:

<action   path="/signin"   input="/security/signin.jsp"   name="loginForm"   scope="request"   type="com.oreilly.struts.storefront.security.LoginAction"   validate="true">   <forward name="Success" path="/index.jsp" redirect="true"/>   <forward name="Failure" path="/security/signin.jsp" redirect="true"/>  </action>

For more information on the attributes of the action element, see "The Struts Configuration DTD" in Chapter 4.

7.2.5 Using an ActionForm in an Action

Once you have configured the ActionForm for a particular Action, you can insert values into it and retrieve values from it within the execute() method, as Example 7-3 illustrates.

Example 7-3. The ActionForm is available within the execute( ) method
public ActionForward execute( ActionMapping mapping,                               ActionForm form,                               HttpServletRequest request,                               HttpServletResponse response )   throws Exception{     // Get the user's login name and password. They should already have     // been validated by the ActionForm.     String email = ((LoginForm)form).getEmail( );     String password = ((LoginForm)form).getPassword( );     // Log in through the security service.     IStorefrontService serviceImpl = getStorefrontService( );     UserView userView = serviceImpl.authenticate(email, password);     UserContainer existingContainer = null;     HttpSession session = request.getSession(false);     if ( session != null ){       existingContainer = getUserContainer(request);       session.invalidate( );     }else{       existingContainer = new UserContainer( );     }     // Create a new session for the user.     session = request.getSession(true);     existingContainer.setUserView(userView);     session.setAttribute(IConstants.USER_CONTAINER_KEY, existingContainer);     return mapping.findForward(IConstants.SUCCESS_KEY);   }

It's not mandatory that you use an ActionForm to capture the data from an HTML form. Even if you don't declare an ActionForm for a form, the data is still available from the request. However, your application will have to manually handle the process of validation and error handling from the Action class.


7.2.6 Declaring ActionForm Properties as Strings

All request parameters that are sent by the browser are strings. This is true regardless of the type that the value will eventually map to in Java. For example, dates, times, Booleans, and other values all are strings when they are pulled out of the request, and they will be converted into strings when they are written back out to the HTML page. Therefore, all of the ActionForm properties where the input may be invalid should be of type String, so that the data can be displayed back to the user in its original form when an error occurs. For example, say a user types in "12Z" for a property expecting an Integer. There's no way to store "12Z" into an int or Integer property, but you can store it into a String until it can be validated. This value can be used to render the input field with the value, so the user can see his mistake. Even the most inexperienced users have come to expect and look for this functionality.

ActionForms Are Not the Model

Many developers get confused when they learn about the ActionForm class. Although it can hold state for an application, the state that it holds should be limited and constrained to the user input that is received from the client, and the ActionForm should hold it only until it can be validated and transferred to the business tier.

You've already seen why it's important to separate the model from the presentation tier in an application. Business objects can be persisted and should contain the business logic for an application. They also should be reusable. This set of criteria does not match up well when compared against ActionForms. For one thing, the ActionForm class is tied to the Struts framework and explicitly to a web container, as it imports javax.servlet packages. It would be very difficult to port ActionForm classes to a different type of framework, such as a Swing application.

ActionForms are designed exclusively to capture the HTML data from a client, allow "presentation validation" to occur, and provide a transport vehicle for the data back to the more persistent business tier. They also transport data from the business tier forward to the views. Apart from these uses, you should keep the ActionForms separate from your business components.


7.2.7 Using ActionForms Across Multiple Pages

Many applications require wizard-like functionality where data is captured across multiple pages. ActionForms can be used for this but the scope must be set to session to ensure that the data collected from a previous page will be present throughout the set of wizard pages.

When programming this type of functionality into your application, you must be careful to validate only the fields that are ready to be validated. For instance, if you go from page 1 to page 2, only the properties populated from page 1 should be validated. You also must be careful with the reset() method. You don't want to reset fields that already have been entered, but, you might want to reset the properties for the upcoming page. This can be a little tricky, but keeping these thoughts in mind will save time.



Programming Jakarta Struts
Programming Jakarta Struts, 2nd Edition
ISBN: 0596006519
EAN: 2147483647
Year: 2003
Pages: 180

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net