The Spring Framework

An AbstractController is a suitable class to extend if you want a controller that does not access any parameters from the request object (i.e., any parameter set on the web page). Of course, one can still access request parameters by querying the request object directly (it is, after all, passed as a parameter to the handleRequest method) but if one needs such parameters, one should use one of the command or form controllers instead. The advantage that AbstractController provides over a simple Controller is that it provides support for synchonising on the session (see Section 3.3, “Preventing Duplicate Form Submission”) and it extends WebContentGenerator, which provides support for cache control of the web pages, requiring a session to be present when the controller is invoked and choosing whether a HTML POST or GET or both are allowed to invoke this controller: see the API documentation for details. This features are normally configured via the Spring application context file.

In our example program, sprMVCFull.controller.HomeController extends AbstractController:

package sprMVCFull.controller;
import org.springframework.web.servlet.mvc.AbstractController;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Calendar;

public class HomeController extends AbstractController
{
    private String greeting;

    protected ModelAndView handleRequestInternal(HttpServletRequest request,
                                                 HttpServletResponse response)
            throws Exception
    {
        String s = greeting +
                   ": the date and time is now " +
                   Calendar.getInstance().getTime() ;
        return new ModelAndView("home", "message", s);
    }

    public void setGreeting(String greeting)
    {
        this.greeting = greeting;
    }
}

As we can see, this controller does not take any data from the input web page (although it is adding some to the output page) so an AbstractController is very appropriate here.

The sprMVCFull.controller.HomeController class is embedded in our web space at /hello.html via setting a property in the controllerMapping bean in the context file, WEB-INF/controller-servlet.xml.

To invoke this controller, we need a link to /hello.html from a web page. We could use a normal html link, a button that uses a little Javascript to go to the address or a submit button in a form. Whatever we do, we should wrap the URL in a c:url JSTL tag to ensure that url rewriting is done correctly in case the user has disabled cookies and we need to preserve the connection between the user's request and a Session object. In WEB-INF/jsp/index.jsp, the following line does this correctly for a simple link:

<a href='<c:url value="/hello.html"/>'>

An AbstractCommandController is intended to add the automatic handling of parameters from a web page request to the functionality of AbstractController. The idea is that one specifies the model class (i.e., the class of the business object) to copy the request parameters into. Within the controller, one can then access those values in a simple manner without having to process the request object directly. The sprMVCFull.controller.PrintParamController class is an example:

package sprMVCFull.controller;
import org.springframework.web.servlet.mvc.AbstractCommandController;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.validation.BindException;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import sprMVCFull.model.PrintParamCommand;
public class PrintParamController extends AbstractCommandController
{
    public PrintParamController()
    {
        setCommandClass(PrintParamCommand.class);
    }

    protected ModelAndView handle(HttpServletRequest request,
                                  HttpServletResponse response,
                                  Object command,
                                  BindException errors) throws Exception
    {
        return new ModelAndView("printCommand", "command", ((PrintParamCommand)command).getParamName());
    }

}

We have to specify the class that the parameters should be copied into, in our case the sprMVCFull.model.PrintParamCommand class, and when the controller is invoked, the AbstractCommandController super class methods will ensure that all parameters in the request whose names match properties in the model bean will be copied into the model bean.

In fact, Spring MVC is much more sophisticated that merely to support "copying into the model bean". For any property in the model bean whose type is not String, Spring will try to use one of its built-in PropertyEditors to transform the String obtained from the request and set the appropriate property in the model bean by doing a suitable transformation of the string. Thus for a property of any of a number of numeric types (int, float, Integer, etc.), Spring will invoke its CustomNumberEditor to parse the string into the appropriate numeric type. Similarly there are built-in editors for boolean and for String arrays (the latter transforms a comma-separated string into an array of Strings). There are others as well, including a date editor, although that is not registered by default so must be registered explicitly if required. You can also define your own custom editors and register them with the request parameter binder in order to handle your own classes if you wish.

The sprMVCFull.controller.PrintParamController class is mapped into our web space at /printCommand so again we can use a link, a button with javascript or a button in a form to invoke it. Again we need to wrap the URL in a c:url JST tag to handle URL rewriting. However, we also need to set the parameter, in our case, a property of type String with name "paramName":

If the user explicitly enters input data on a web page, instead of simply clicking on one of the available links, then there is a possibility that the data entered will be invalid for some reason: perhaps he or she has mis-spelled a word or entered a value, or a combination of values, that is not allowed. In this case we want to be able to easily check the data entered and, if there is a problem with it, to re-display the same page back to the user, with the incorrect data still on it, so that the user can correct the data without having to retype everything all over again. Furthermore, we would like to be able to display appropriate error messages on the page to indicate to the user what the problem is.

The key to understanding SimpleFormController is to realise that there are three separate issues involved:

First, let us consider the model object associated with the controller. The relevant controller in our example is sprMVCFull.controllerProcessDetailsController. The model object associated with this controller (and form) is sprMVCFull.model.Person. A fairly minimal implementation of the controller is as follows:

package sprMVCFull.controller;
import org.springframework.web.servlet.mvc.SimpleFormController;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.util.WebUtils;
import org.springframework.validation.BindException;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import sprMVCFull.model.Person;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class ProcessDetailsController extends SimpleFormController
{
    public ProcessDetailsController()
    {
        setCommandClass(Person.class);
    }
    
    protected ModelAndView onSubmit(Object command) throws Exception
    {
        Person person = (Person) command ;

        // This debug call represents the real business use case
        logger.debug("got person: " + person) ;
        return new ModelAndView("printCommand", "command", command.toString());
    }
}

In the constructor, we configure the class used as the model object for the form. The only reason we need to do this is so that the framework can create a new model object of the correct type when we first get the form submitted. Of course, we could avoid doing this configuration here and instead do it in the application context file where we wire up all our context beans. However, I have left this configuration here because sometimes we want to replace that configuration with something else: namely, we sometimes want to create not just a default object of the appropriate type, but one which is pre-initialised to some valuesFor our example, we might want the person details shown to be those of the user, so that he or she can then modify and update them. To this, we replace the four lines of the constructor above with the following:

    protected Object formBackingObject(HttpServletRequest request)
        throws Exception
    {
        Person p = new Person() ;
        p.setFirstname("John");
        p.setLastname("Smith");
        p.setEmail("J.Smith@somewhere.co.uk");
        p.setGender("M");
        return p;
    }

Of course, in practice the model object would, most likely, be retrieved from a database.

Now that our model object is taken care of, we can consider how the controller is invoked.

The question remains, how does Spring distinguish between the two cases? The default is that if the incoming request used a POST method, then Spring assumes that it is a submission of data from the form. If, however, the request used a GET method, then an initial request is assumed and no attempt is made to extract the form data from the request. In practice, this matches extremely well with the standard use of requests and form page invocation and submission.

Finally, we look at how processing continues out of a form controller. There are usually two cases:

Sometimes there is one other way to proceed from the controller: if you wish to allow the user to cancel the form altogether then you need to shortcut the standard procedure for dealing with the form. Otherwise, when the form data is submitted, validation will take place and if the data is not correct, the user will be returned to the input form until it is filled in correctly. It is not resonable to force a user to correctly fill in a form that he wishes to cancel.

The solution is intercept the request before it goes through model object validation, check if this is a cancel operation, and, if it is not, continue where you left off. If it is a cancel, however, you can redirect to a suitable alternative ModelAndView. This can be done by adding the following code to the controller:

private static final String PARAM_CANCEL = "_cancel" ;                         

protected ModelAndView processFormSubmission(HttpServletRequest request,       
                                             HttpServletResponse response,
                                             Object command,
                                             BindException errors)
        throws Exception
{
    if (WebUtils.hasSubmitParameter(request, PARAM_CANCEL))                    
        return new ModelAndView("printCommand", "command", "form submission cancelled") ; 
    return super.processFormSubmission(request, response, command, errors);    
}

	First we need to set the name of the parameter that will be set when the user presses the cancel button
	Overriding this method is only necessary if you want to do some processing BEFORE the validation of the model for the form.
	Since we have intercepted the dispatching to the controller before handling of the model object has taken place, we must search for the parameter directly in the request object. Fortunately, Spring provides this utilities class that makes that search simple.
	If the operation invoked was a cancel, then we stop further processing of the controller and immediately return the new target ModelAndView
	If the operation invoked was not a cancel, then we want to continue where we left off; i.e., we want to let the default processFormSubmission method execute as if we had not overridden it at all.

So far, we have discussed the code in the controller class, and we will not discuss the code in the model object as it is a standard java bean with no special or Spring specific aspects at all. However, we have not discussed how validation of the model object works. To do this we add a special validator class which is specific to the controller (and then wire it in via the application context file). The wiring is accomplished, in our case by adding the following lines to the application context file under the bean for our form controller:

        <property name="validator">
            <bean class="sprMVCFull.model.PersonValidator"/>
        </property>

The class referred to must implement the Validator interface to support validation of the model object, and typically the model object itself will do so, but one can, as in the example code, have an independant class provides the validation support:

package sprMVCFull.model;
import org.springframework.validation.Validator;
import org.springframework.validation.Errors;
import org.springframework.validation.ValidationUtils;
import java.util.regex.Pattern;

public class PersonValidator implements Validator
{
    public boolean supports(Class clazz)
    {
        return clazz.equals(Person.class);
    }

    public void validate(Object obj, Errors errors)
    {
        Person p = (Person) obj ;

        ValidationUtils.rejectIfEmptyOrWhitespace(errors,  "firstname",
                                                  "required.firstname", "First name is required");
        ValidationUtils.rejectIfEmptyOrWhitespace(errors,  "lastname",
                                                  "required.lastname", "Last name is required");
        ValidationUtils.rejectIfEmptyOrWhitespace(errors,  "gender",
                                                  "required.gender", "Gender is required");
        validateEmail(p.getEmail(), errors);
    }

    private static final Pattern EMAIL_PATTERN = Pattern.compile("^\\w+([_\\.-]\\w+)*@(\\w+([_\\.-]\\w+)*)");
    private void validateEmail(String email, Errors errors)
    {
        ValidationUtils.rejectIfEmptyOrWhitespace(errors,  "email",
                                                  "required.email", "Email address is required");
        if (!EMAIL_PATTERN.matcher(email).matches())
        {
            errors.rejectValue("email", "invalid.email", "Email address is invalid") ;
        }
    }
}

In the above code, the Validator requires implementation of two methods: the support method will be used by Spring to check which of a possible collect of Validator methods is suitable for validating objects of a particular class. The second, validate, actually carries out the validation. The first argument will be the model object with its properties set from the corresponding request object parameters but with no validation yet applied. The second is an errors object that essentially contains a collection of errors found so far. If, on return from this method, the error collection is empty, that validation will be considered to have succeeded and processing can continue. Otherwise it will have failed and the form view will be show again.

Error objects are created and added to the errors collection object either by calling the reject or the rejectValue method on the errors object itself, or by using the convenience methods of ValidationUtils. In general, the Value form of the methods are for errors in a specific field or property of the model object whereas the other methods are used to signify global or multi-field problems.

All that is left now is to integrate the error messages and the model object property values into the forms for display to the user. This is done with a small number of Spring tags. Note that we do not need to use these tags in general: without them, we do not get the error messages on the form or the intial values for the input fields, but copying of form input values to the model object on submission of the form would still work.

<<%@ page contentType="text/html;charset=UTF-8" language="java" session="false" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %>
<%@ taglib prefix="spring" uri="http://www.springframework.org/tags" %>   

<html>
  <head>
    <title>Books Rn't Us</title>
  </head>
  <body>
    <h1>
        Test of a SimpleForm Controller
    </h1>
    <p>
       <form action='<c:url value="/processDetails.html"/>' method="post">
          <p>
            <spring:hasBindErrors name="command">                    
              <c:forEach var="err" items="${errors.globalErrors}">
                <span class="error"><c:out value="${err.defaultMessage}"/></span><br />
              </c:forEach>
            </spring:hasBindErrors>

            First name:
            <spring:bind path="command.firstname">                   
                    <input type="text" name="firstname" value="<c:out value="${status.value}"/>">
                    <span class="error"><c:out value="${status.errorMessage}"/></span>
            </spring:bind>
            <br />
            Last name:
            <spring:bind path="command.lastname">
                    <input type="text" name="lastname" value="<c:out value="${status.value}"/>">
                    <span class="error"><c:out value="${status.errorMessage}"/></span>
            </spring:bind>
            <br />
            email:
            <spring:bind path="command.email">
                    <input type="text" name="email" value="<c:out value="${status.value}"/>">
                    <span class="error"><c:out value="${status.errorMessage}"/></span>
            </spring:bind>
            <br />
            <spring:bind path="command.gender">                      
              <input type="radio" name="gender" value="M" <c:if test='${status.value == "M"}'>checked</c:if> > Male
              <span class="error"><c:out value="${status.errorMessage}"/></span>
              <br />
              <input type="radio" name="gender" value="F" <c:if test='${status.value == "F"}'>checked</c:if> > Female
              <br />

            </spring:bind>

          <input type="submit" value="Send"> <INPUT type="Reset"> <input type="submit" value="Cancel" name="_cancel">
          </p>
       </form>
  </body>
</html>

	Since we are using the Spring tags, we need to declare them to the JSP page.
	Here we print out the global errors that are not specific to a single property of the model object but are caused by the state of a combination of different properties. Note that each errors object is specific to a single object so here we wrap the error printing code in a spring tag that does nothing if the named object has no errors. Otherwise it sets the errors variable within the spring:hasBindErrors element to refer to the errors object specific to the model object named. Within the tag then, we can iterate, using the JSTL tags, over the list of global errors in the errors object, printing out the default message of each.
	For an actual input field, we surround it with a spring:bind tag and specify the "path" to the property we are concerned with, in this case command.firstname, to refer to the firstname property of the model object stored in the request object under the name command. There is a whole expression language for such paths which are more or less compatible with the JSTL EL. With this tag, we can refer to objects under the name, local to the spring:bind element, of status. In particular, status.value will hold the current value of the corresponding model property and status.errorMessage will hold the error message associated with this field if there is one. It seems a little inelegant that one has to specify the property associated with the input field twice: once for the path of the spring:bind tag, and once as the name of the input tag. In fact, this is not necessary as there is another property of status available: status.expression returns the expression name of the property, i.e., precisely the string that needs to be passed as the name value of the input tag. Thus we can remove the second specification of the property by writing the whole tag as: <spring:bind path="command.firstname"> <input type="text" name="<c:out value="${status.expression}"/>" value="<c:out value="${status.value}"/>"> <span class="error"><c:out value="${status.errorMessage}"/></span> </spring:bind> Finally the span element around the printing of the error message is there so that, using CSS, we can style all printing of error messages (for example to set them to print in red).
	We are faced with a slightly different problem when dealing with radio buttons and option groups. Here each input element is rendered separately but must be bound to the same model property. For a radio button, the input element corresponding to the chosen value must have the property checked, and the others must not. This is easily arranged with the use of the c:if element as shown.

A particular situation with respect to forms that frequently arises is where a sequence of forms have to be filled in and each form in the sequence contributes only some properties of the model object. In fact, AbstractWizardFormController extends AbstractFormController, which is almost all of SimpleFormController so most of the discussion of SimpleFormController also applies here. Therefore I will concentrate on the differences. These include

The model object itself is, as usual, just an ordinary Java bean. For the sake of the example, I assume that it has a number of String properties to represent various fields in a survey.

Unlike in the SimpleFormController case, we do not have a single form view but one for each page of the wizard. We set up the pages in the application context file, WEB-INF/controller-servlet.xml by setting the pages property of the controller bean to a list of views:

<bean id="surveyController" class="sprMVCFull.controller.SurveyController">
    <property name="pages">
        <list>
            <value>survey_colour_food</value>
            <value>survey_country_language</value>
            <value>survey_film_singer</value>
        </list>
    </property>
</bean>

The views in the list are just standard form views. I will show only the last one of the three:

<%@ page contentType="text/html;charset=UTF-8" language="java" session="false" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %>
<%@ taglib prefix="spring" uri="http://www.springframework.org/tags" %>

<html>
  <head>
    <title>Books Rn't Us</title>
  </head>
  <body>
    <h1>
        Test of a Wizard Controller
    </h1>
    <p>
       <form action='<c:url value="/survey.html"/>' method="post">   
          <p>
            <spring:hasBindErrors name="command">
              <c:forEach var="err" items="${errors.globalErrors}">
                <span class="error"><c:out value="${err.defaultMessage}"/></span><br />
              </c:forEach>

            </spring:hasBindErrors>
            What is your favourite film:
            <spring:bind path="command.film">
                    <input type="text" name="film" value="<c:out value="${status.value}"/>">
                    <span class="error"><c:out value="${status.errorMessage}"/></span>
            </spring:bind>
            <br />
            What is your favourite singer:
            <spring:bind path="command.singer">
                    <input type="text" name="singer" value="<c:out value="${status.value}"/>">
                    <span class="error"><c:out value="${status.errorMessage}"/></span>
            </spring:bind>
            <br />

          <input type="submit" value="Previous" name="_target1">     
          <input type="submit" value="Finish" name="_finish">        
          <input type="Reset">                                       
          <input type="submit" value="Cancel" name="_cancel">        
          </p>
       </form>
  </body>
</html>

	As with the SimpleFormController, it is important to submit the form using a POST method and not a GET method as Spring, by default, distinguishes between a request to display the initial form and a request to submit data from the form via the choice of submit method.
	You can have as many wizard page navigation buttons as you like. The name has to be "_targetN", where N is the number of the wizard page you wish to switch to. This number corresponds to the position (starting at 0) in the pages list property of the controller bean in the application context file. It is usual to provide a next and previous button on each page, with previous disabled or missing on the first page and next similarly on the last and with a finish button only on the last page of the wizard, but nothing except taste and good Human Computer Interaction design stops you from making any weird and wonderful wiring together of the pages of the wizard. It is, of course, quite reasonable to put a finish button on each page where suitable defaults exist for the unset input fields of the remaining pages.
	The "finish" button is a normal submit button which must have the name "_finish". The value of the button is not important to the controller but appears as the button text.
	The reset button is handled directly by the browser without submitting the form to the server. Note that it does not clear the fields but resets them to the initial values they had when the page was first displayed.
	The cancel button is handled in exactly the same way as for the SimpleFormController

We have seen how the navigation between pages is specified on each view, on the basis of the list of views set for the controller bean in the application context file. The actual processing of the navigation is done in the controller itself of course. However, the code to do so is in the AbstractWizardFormController superclass, and no code need to be added to your controller to make it work. In effect, navigation between pages is handled invisibly to your code in the same way that, in SimpleFormController, a submission of a form which fails validation gets redirected back to the form view which you having to write explicit code to make it so. You do have to write code to hand the final submission triggered by clicking the finish button however, and there is still the validation to consider (in sprMVCFull.controller.SurveyController):

package sprMVCFull.controller;
import org.springframework.web.servlet.mvc.AbstractWizardFormController;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.validation.BindException;
import org.springframework.validation.Errors;
import org.springframework.validation.ValidationUtils;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import sprMVCFull.model.Survey;

public class SurveyController extends AbstractWizardFormController
{
    public SurveyController()
    {
        setCommandClass(Survey.class);
    }

    protected ModelAndView processFinish(HttpServletRequest request, 
                                         HttpServletResponse response,
                                         Object command, BindException errors)
            throws Exception
    {
        Survey survey = (Survey) command ;
        return new ModelAndView("printCommand", "command", survey) ;
    }

    protected ModelAndView processCancel(HttpServletRequest request,
                                         HttpServletResponse response,
                                         Object command, BindException errors)
            throws Exception
    {
        return new ModelAndView("printCommand", "command",
                                "survey form submission cancelled") ;

    }

    protected void validatePage(Object command, Errors errors,       
                                int page, boolean finish)
    {
        Survey survey = (Survey) command ;

        switch (page)                                                
        {
        case 0:
            ValidationUtils.rejectIfEmptyOrWhitespace(
                errors,  "colour", "required.colour", "colour is required");
            ValidationUtils.rejectIfEmptyOrWhitespace(
                errors,  "food", "required.food", "food is required");
            break ;
        case 1:
            ValidationUtils.rejectIfEmptyOrWhitespace(
                errors,  "country", "required.country", "country is required");
            ValidationUtils.rejectIfEmptyOrWhitespace(
                errors,  "language", "required.language", "language is required");
            break ;
        case 2:
            ValidationUtils.rejectIfEmptyOrWhitespace(
                errors,  "film", "required.film", "film is required");
            ValidationUtils.rejectIfEmptyOrWhitespace(
                errors,  "singer", "required.singer", "singer is required");
            break ;
        default:
        }
        if (finish)                                                  
        {
            if (!"ireland".equals(survey.getCountry().toLowerCase()))
                errors.reject("invalid.country",
                              "bad choice of favourite country (try \"Ireland\")!") ;
        }
    }
}

	When the fully completed form is submitted (via the finish button), we handle it like any form submission.
	In an AbstractWizardFormController, the only method called automatically to validate the model object is this validatePage method.
	Validation is basically similar to SimpleFormController validation, except that, during the filling in of a wizard form, you only want to validate the data submitted on a page by page basis until the whole form is complete. This is done by switching on the page parameter of the validatePage method. This page parameter contains the page number of the page just submitted. If, on termination of this method, the errors collection is not empty, then the navigation requested will not take place but instead the same page will be redisplayed so that the user can correct his or her errors.
	If the finish parameter is true, then this submission was due to the wizard being finished, and you now have the opportunity to do some global validation of the submitted model data (the example shown is not very good because it does not involve the contents of multiple input fields from different pages).