com.interface21.web.servlet.mvc
Class AbstractFormController

java.lang.Object
  |
  +--com.interface21.context.support.ApplicationObjectSupport
        |
        +--com.interface21.web.servlet.mvc.WebContentGenerator
              |
              +--com.interface21.web.servlet.mvc.AbstractController
                    |
                    +--com.interface21.web.servlet.mvc.BaseCommandController
                          |
                          +--com.interface21.web.servlet.mvc.AbstractFormController
All Implemented Interfaces:
ApplicationContextAware, Controller
Direct Known Subclasses:
AbstractWizardFormController, SimpleFormController

public abstract class AbstractFormController
extends BaseCommandController

Form controller that autopopulates a form bean from the request, using a new bean instance per request. To achieve population of the same bean instance, "session form" can be activated. This is the common base class for both framework subclasses like SimpleFormController and AbstractWizardFormController, and custom application controllers.

Subclasses need to override showForm to prepare the form view, and processSubmit to handle submit requests. For the latter, binding errors like type mismatches will be reported via the given "errors" binder. For additional custom form validation, a validator (property inherited from BaseCommandController) can be used, reporting via the same "errors" instance.

Note: If you decide to have "formView" and "successView" properties specifying view names instead of programmatic handling, consider using SimpleFormController.

This approach is similar to the Struts approach, with the main difference that you can use any beans, with no need to derive from a form base class. Type mismatches are stored in Errors instances instead of forcing the form bean to have mostly String properties. A further difference is the decoupling of validation, not even coupling the validation logic to web usage.

Note that by default POST requests are treated as form submissions. This can be customized by overriding isFormSubmission. Custom binding can be achieved either by registering custom property editors before binding in an initBinder implementation, or by custom bean population from request parameters after binding in an onBindAndValidate implementation.

In session form mode, a submission without an existing form object in the session is considered invalid, like in case of a resubmit/reload by the browser. The handleInvalidSubmit method is invoked then, trying a resubmit by default. It can be overridden in subclasses to show respective messages or redirect to a new form, in order to avoid duplicate submissions. The form object in the session can be considered a transaction token in this case.

Note that views should never retrieve form beans from the session but always from the request, as prepared by the form controller. Remember that some view technologies like Velocity cannot even access a HTTP session.

Author:
Rod Johnson, Juergen Hoeller
See Also:
SimpleFormController, AbstractWizardFormController, setSessionForm(boolean), showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, com.interface21.validation.BindException), processSubmit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, com.interface21.validation.BindException), BaseCommandController.setValidator(com.interface21.validation.Validator), isFormSubmission(javax.servlet.http.HttpServletRequest), BaseCommandController.initBinder(javax.servlet.http.HttpServletRequest, com.interface21.web.bind.ServletRequestDataBinder), BaseCommandController.onBindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object, com.interface21.validation.BindException), handleInvalidSubmit(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

Fields inherited from class com.interface21.web.servlet.mvc.BaseCommandController
DEFAULT_BEAN_NAME
 
Fields inherited from class com.interface21.context.support.ApplicationObjectSupport
logger
 
Constructor Summary
AbstractFormController()
          Create a new AbstractFormController.
 
Method Summary
protected  java.lang.Object formBackingObject(javax.servlet.http.HttpServletRequest request)
          Retrieve a backing object for the current form from the given request.
protected  java.lang.String getFormSessionAttributeName()
          Return the name of the session attribute that holds the form object for this controller.
protected  ModelAndView handleInvalidSubmit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).
protected  ModelAndView handleRequestInternal(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Handles two cases: form submissions and showing a new form.
protected  boolean isBindOnNewForm()
          Return if request parameters should be bound in case of a new form.
protected  boolean isFormSubmission(javax.servlet.http.HttpServletRequest request)
          Determine if the given request represents a form submission.
protected  boolean isSessionForm()
          Return if session form mode is activated.
protected abstract  ModelAndView processSubmit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object command, BindException errors)
          Process submit request.
protected  java.util.Map referenceData(javax.servlet.http.HttpServletRequest request, java.lang.Object command, Errors errors)
          Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
 void setBindOnNewForm(boolean bindOnNewForm)
          Sets if request parameters should be bound to the form object in case of a non-submitting request, i.e. a new form.
 void setSessionForm(boolean sessionForm)
          Activates resp. deactivates session form mode.
protected  ModelAndView showForm(javax.servlet.http.HttpServletRequest request, BindException errors, java.lang.String viewName)
          Prepare model and view for the given form, including reference and errors.
protected  ModelAndView showForm(javax.servlet.http.HttpServletRequest request, BindException errors, java.lang.String viewName, java.util.Map controlModel)
          Prepare model and view for the given form, including reference and errors, adding a controller-specific control model.
protected abstract  ModelAndView showForm(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, BindException errors)
          Prepare the form model and view, including reference and error data.
protected  ModelAndView showNewForm(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Show a new form.
protected  java.lang.Object userObject(javax.servlet.http.HttpServletRequest request)
          Return the form object for the given request.
 
Methods inherited from class com.interface21.web.servlet.mvc.BaseCommandController
bindAndValidate, checkCommand, createBinder, createCommand, getBeanName, getCommandClass, getValidator, initBinder, isValidateOnBinding, onBindAndValidate, setBeanName, setCommandClass, setValidateOnBinding, setValidator
 
Methods inherited from class com.interface21.web.servlet.mvc.AbstractController
handleRequest, setCacheSeconds, setRequireSession, setSupportedMethods
 
Methods inherited from class com.interface21.web.servlet.mvc.WebContentGenerator
cacheForSeconds, preventCaching, setUseExpiresHeader
 
Methods inherited from class com.interface21.context.support.ApplicationObjectSupport
getApplicationContext, initApplicationContext, setApplicationContext
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractFormController

public AbstractFormController()
Create a new AbstractFormController.

Subclasses should set the following properties, either in the constructor or via a BeanFactory: beanName, commandClass, bindOnNewForm, sessionForm. Note that commandClass doesn't need to be set when overriding formBackingObject, as the latter determines the class anyway.

See Also:
BaseCommandController.setBeanName(java.lang.String), BaseCommandController.setCommandClass(java.lang.Class), setBindOnNewForm(boolean), setSessionForm(boolean)
Method Detail

setBindOnNewForm

public void setBindOnNewForm(boolean bindOnNewForm)
Sets if request parameters should be bound to the form object in case of a non-submitting request, i.e. a new form.

isBindOnNewForm

protected boolean isBindOnNewForm()
Return if request parameters should be bound in case of a new form.

setSessionForm

public final void setSessionForm(boolean sessionForm)
Activates resp. deactivates session form mode. In session form mode, the form is stored in the session to keep the form object instance between requests, instead of creating a new one on each request.

This is necessary for either wizard-style controllers that populate a single form object from multiple pages, or forms that populate a persistent object that needs to be identical to allow for tracking changes.


isSessionForm

protected final boolean isSessionForm()
Return if session form mode is activated.

getFormSessionAttributeName

protected final java.lang.String getFormSessionAttributeName()
Return the name of the session attribute that holds the form object for this controller.
Returns:
the name of the form session attribute, or null if not in session form mode.

handleRequestInternal

protected final ModelAndView handleRequestInternal(javax.servlet.http.HttpServletRequest request,
                                                   javax.servlet.http.HttpServletResponse response)
                                            throws javax.servlet.ServletException,
                                                   java.io.IOException
Handles two cases: form submissions and showing a new form. Delegates the decision between the two to isFormSubmission, always treating requests without existing form session attribute as new form when using session form mode.
Overrides:
handleRequestInternal in class AbstractController
Following copied from class: com.interface21.web.servlet.mvc.AbstractController
See Also:
AbstractController.handleRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

isFormSubmission

protected boolean isFormSubmission(javax.servlet.http.HttpServletRequest request)
Determine if the given request represents a form submission.

Default implementation treats a POST request as form submission. Note: If the form session attribute doesn't exist when using session form mode, the request is always treated as new form by handleRequestInternal.

Subclasses can override this to use a custom strategy, e.g. a specific request parameter (assumably a hidden field or submit button name).

Parameters:
request - current HTTP request
Returns:
if the request represents a form submission

showNewForm

protected final ModelAndView showNewForm(javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response)
                                  throws javax.servlet.ServletException,
                                         java.io.IOException
Show a new form. Prepares a backing object for the current form and the given request, including checking its validity.
Parameters:
request - current HTTP request
response - current HTTP response
Returns:
the prepared form view
Throws:
javax.servlet.ServletException - in case of an invalid new form object
java.io.IOException - in case of I/O errors

formBackingObject

protected java.lang.Object formBackingObject(javax.servlet.http.HttpServletRequest request)
                                      throws javax.servlet.ServletException
Retrieve a backing object for the current form from the given request.

Default implementation calls BaseCommandController.createCommand. Subclasses can override this to provide a preinitialized backing object.

Parameters:
request - current HTTP request
Returns:
the backing objact
Throws:
javax.servlet.ServletException - in case of invalid state or arguments
See Also:
BaseCommandController.createCommand()

showForm

protected abstract ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response,
                                         BindException errors)
                                  throws javax.servlet.ServletException,
                                         java.io.IOException
Prepare the form model and view, including reference and error data. Can show a configured form page, or generate a programmatic form view.

A typical implementation will call showForm(request,errors,"myView") to prepare the form view for a specific view name.

Note: If you decide to have a "formView" property specifying the view name, consider using SimpleFormController.

Parameters:
request - current HTTP request
response - current HTTP response
errors - binder containing errors
Returns:
the prepared form view, or null if handled directly
Throws:
javax.servlet.ServletException - in case of invalid state or arguments
See Also:
showForm(HttpServletRequest, BindException, String), SimpleFormController.setFormView(java.lang.String)

showForm

protected final ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                      BindException errors,
                                      java.lang.String viewName)
                               throws javax.servlet.ServletException
Prepare model and view for the given form, including reference and errors. In session form mode: Re-puts the form object in the session when returning to the form, as it has been removed by userObject. Can be used in subclasses to redirect back to a specific form page.
Parameters:
request - current HTTP request
errors - binder containing errors
viewName - name of the form view
Returns:
the prepared form view
Throws:
javax.servlet.ServletException - in case of invalid state or arguments

showForm

protected final ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                      BindException errors,
                                      java.lang.String viewName,
                                      java.util.Map controlModel)
                               throws javax.servlet.ServletException
Prepare model and view for the given form, including reference and errors, adding a controller-specific control model. In session form mode: Re-puts the form object in the session when returning to the form, as it has been removed by userObject. Can be used in subclasses to redirect back to a specific form page.
Parameters:
request - current HTTP request
errors - binder containing errors
viewName - name of the form view
controlModel - model map containing controller-specific control data (e.g. current page in wizard-style controllers).
Returns:
the prepared form view
Throws:
javax.servlet.ServletException - in case of invalid state or arguments

referenceData

protected java.util.Map referenceData(javax.servlet.http.HttpServletRequest request,
                                      java.lang.Object command,
                                      Errors errors)
                               throws javax.servlet.ServletException
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.

Default implementation returns null. Subclasses can override this to set reference data used in the view.

Parameters:
request - current HTTP request
command - form object with request parameters bound onto it
errors - binder containing current errors, if any
Returns:
a Map with reference data entries, or null if none
Throws:
javax.servlet.ServletException - in case of invalid state or arguments
See Also:
ModelAndView

handleInvalidSubmit

protected ModelAndView handleInvalidSubmit(javax.servlet.http.HttpServletRequest request,
                                           javax.servlet.http.HttpServletResponse response)
                                    throws javax.servlet.ServletException,
                                           java.io.IOException
Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).

Default implementation simply tries to resubmit the form with a new form object. This should also work if the user hit the back button, changed some form data, and resubmitted the form.

Note: To avoid duplicate submissions, you need to override this method. Either show some "invalid submit" message, or call showNewForm for resetting the form (prepopulating it with the current values if "bindOnNewForm" is true). In this case, the form object in the session serves as transaction token.

Parameters:
request - current HTTP request
response - current HTTP response
Returns:
a prepared view, or null if handled directly
Throws:
javax.servlet.ServletException - in case of invalid state
java.io.IOException - in case of I/O errors
See Also:
showNewForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), setBindOnNewForm(boolean)

userObject

protected final java.lang.Object userObject(javax.servlet.http.HttpServletRequest request)
                                     throws javax.servlet.ServletException
Return the form object for the given request. In session form mode: Retrieve the form object from the session. The form object gets removed from the session, but it will be re-added when showing the form for resubmission.
Overrides:
userObject in class BaseCommandController
Parameters:
request - current HTTP request
Returns:
object form to bind onto
Throws:
javax.servlet.ServletException - in case of invalid state or arguments

processSubmit

protected abstract ModelAndView processSubmit(javax.servlet.http.HttpServletRequest request,
                                              javax.servlet.http.HttpServletResponse response,
                                              java.lang.Object command,
                                              BindException errors)
                                       throws javax.servlet.ServletException,
                                              java.io.IOException
Process submit request. Called by handleRequestInternal in case of a form submission.

Subclasses can override this to provide custom submission handling like triggering a custom action. They can also provide custom validation and call showForm/super.onSubmit accordingly.

Parameters:
request - current servlet request
response - current servlet response
command - form object with request parameters bound onto it
errors - binder without errors (subclass can add errors if it wants to)
Returns:
the prepared model and view, or null
Throws:
javax.servlet.ServletException - in case of invalid state or arguments
java.io.IOException - in case of I/O errors
See Also:
showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, com.interface21.validation.BindException)


Rod Johnson and Spring contributors 2001-2003.