org.springframework.web.servlet.mvc
Class AbstractWizardFormController

public class AbstractWizardFormController
extends AbstractFormController
Form controller for typical wizard-style workflows.

In contrast to classic forms, wizards have more than one form view page. Therefore, there are various actions instead of one single submit action:

  • finish: trying to leave the wizard successfully, i.e. performing its final action, and thus needing a valid state;
  • cancel: leaving the wizard without performing its final action, and thus without regard to the validity of its current state;
  • page change: showing another wizard page, e.g. the next or previous one, with regard to "dirty back" and "dirty forward".

Finish and cancel actions can be triggered by request parameters, named PARAM_FINISH ("_finish") and PARAM_CANCEL ("_cancel"), ignoring parameter values to allow for HTML buttons. The target page for page changes can be specified by PARAM_TARGET, appending the page number to the parameter name (e.g. "_target1"). The action parameters are recognized when triggered by image buttons too (via "_finish.x", "_abort.x", or "_target1.x").

The current page number will be stored in the session. It can also be specified as request parameter PARAM_PAGE, to properly handle usage of the back button in a browser: In this case, a submission always contains the correct page number, even if the user submitted from an old view.

The page can only be changed if it validates correctly, except if a "dirty back" or "dirty forward" is allowed. At finish, all pages get validated again to guarantee a consistent state.

Note that a validator's default validate method is not executed when using this class! Rather, the validatePage implementation should call special validateXXX methods that the validator needs to provide, validating certain pieces of the object. These can be combined to validate the elements of individual pages.

Note: Page numbering starts with 0, to be able to pass an array consisting of the corresponding view names to the "pages" bean property.

Since25.04.2003
VersionNot specified.
AuthorJuergen Hoeller
Wiki javadoc Use textile entry format.
Add your comments here.
Field Summary
static String PARAM_CANCEL
Parameter triggering the cancel action.
static String PARAM_FINISH
Parameter triggering the finish action.
static String PARAM_PAGE
Parameter specifying the current page as value.
static String PARAM_TARGET
Parameter specifying the target page, appending the page number to the name.
Fields inherited from org.springframework.context.supportApplicationObjectSupport
Fields inherited from org.springframework.web.servlet.mvcBaseCommandController
Fields inherited from org.springframework.web.servlet.supportWebContentGenerator
Constructor Summary
AbstractWizardFormController()
Create a new AbstractWizardFormController.
Method Summary
protected int getCurrentPage( HttpServletRequest request )
Return the current page number.
protected int getInitialPage( HttpServletRequest request, Object command )
Return the initial page of the wizard, i.e.
protected int getInitialPage( HttpServletRequest request )
Return the initial page of the wizard, i.e.
String getPageAttribute()
Return the name of the page attribute in the model.
protected int getPageCount()
Return the number of wizard pages.
protected int getPageCount( HttpServletRequest request, Object command )
Return the page count for this wizard form controller.
String[] getPages()
Return the wizard pages, i.e.
protected String getPageSessionAttributeName( HttpServletRequest request )
Return the name of the HttpSession attribute that holds the page object for this wizard form controller.
protected String getPageSessionAttributeName()
Return the name of the HttpSession attribute that holds the page object for this wizard form controller.
protected int getTargetPage( HttpServletRequest request, Object command, Errors errors, int currentPage )
Return the target page specified in the request.
protected int getTargetPage( HttpServletRequest request, int currentPage )
Return the target page specified in the request.
protected String getViewName( HttpServletRequest request, Object command, int page )
Return the name of the view for the specified page of this wizard form controller.
protected ModelAndView handleInvalidSubmit( HttpServletRequest request, HttpServletResponse response )
Handle an invalid submit request, e.g.
boolean isAllowDirtyBack()
Return whether "dirty back" is allowed.
boolean isAllowDirtyForward()
Return whether "dirty forward" is allowed.
protected boolean isCancel( HttpServletRequest request )
No description provided.
protected boolean isCancelRequest( HttpServletRequest request )
Determine whether the incoming request is a request to cancel the processing of the current form.
protected boolean isFinish( HttpServletRequest request )
No description provided.
protected boolean isFinishRequest( HttpServletRequest request )
Determine whether the incoming request is a request to finish the processing of the current form.
protected boolean isFormSubmission( HttpServletRequest request )
Consider an explicit finish or cancel request as a form submission too.
protected void onBindAndValidate( HttpServletRequest request, Object command, BindException errors )
Calls page-specific onBindAndValidate method.
protected void onBindAndValidate( HttpServletRequest request, Object command, BindException errors, int page )
Callback for custom post-processing in terms of binding and validation.
protected void postProcessPage( HttpServletRequest request, Object command, Errors errors, int page )
Post-process the given page after binding and validation, potentially updating its command object.
protected ModelAndView processCancel( HttpServletRequest request, HttpServletResponse response, Object command, BindException errors )
Template method for processing the cancel action of this wizard.
protected ModelAndView processFinish( HttpServletRequest request, HttpServletResponse response, Object command, BindException errors )
Template method for processing the final action of this wizard.
protected ModelAndView processFormSubmission( HttpServletRequest request, HttpServletResponse response, Object command, BindException errors )
Apply wizard workflow: finish, cancel, page change.
protected Map referenceData( HttpServletRequest request, Object command, Errors errors )
Calls page-specific referenceData method.
protected Map referenceData( HttpServletRequest request, Object command, Errors errors, int page )
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
protected Map referenceData( HttpServletRequest request, int page )
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
void setAllowDirtyBack( boolean allowDirtyBack )
Set if "dirty back" is allowed, i.e.
void setAllowDirtyForward( boolean allowDirtyForward )
Set if "dirty forward" is allowed, i.e.
void setPageAttribute( String pageAttribute )
Set the name of the page attribute in the model, containing an Integer with the current page number.
void setPages( String [] pages )
Set the wizard pages, i.e.
protected ModelAndView showForm( HttpServletRequest request, HttpServletResponse response, BindException errors )
Show first page as form view.
protected ModelAndView showPage( HttpServletRequest request, BindException errors, int page )
Prepare the form model and view, including reference and error data, for the given page.
protected void validatePage( Object command, Errors errors, int page, boolean finish )
Template method for custom validation logic for individual pages.
protected void validatePage( Object command, Errors errors, int page )
Template method for custom validation logic for individual pages.
Methods inherited from org.springframework.contextApplicationContextAware
Methods inherited from org.springframework.web.servlet.mvcController
PARAM_CANCEL
public static String PARAM_CANCEL
Parameter triggering the cancel action. Can be called from any wizard page!
Wiki javadoc Use textile entry format.
Add your comments here.
PARAM_FINISH
public static String PARAM_FINISH
Parameter triggering the finish action. Can be called from any wizard page!
Wiki javadoc Use textile entry format.
Add your comments here.
PARAM_PAGE
public static String PARAM_PAGE
Parameter specifying the current page as value. Not necessary on form pages, but allows to properly handle usage of the back button.
Wiki javadoc Use textile entry format.
Add your comments here.
PARAM_TARGET
public static String PARAM_TARGET
Parameter specifying the target page, appending the page number to the name.
Wiki javadoc Use textile entry format.
Add your comments here.
AbstractWizardFormController
public AbstractWizardFormController ( )
Create a new AbstractWizardFormController.

"sessionForm" is automatically turned on, "validateOnBinding" turned off, and "cacheSeconds" set to 0 by the base class (-> no caching for all form controllers).

Wiki javadoc Use textile entry format.
Add your comments here.
getCurrentPage
protected int getCurrentPage ( HttpServletRequest request )
Return the current page number. Used by processFormSubmission.

The default implementation checks the page session attribute. Subclasses can override this for customized page determination.

Parameters
TypeNameDescription
HttpServletRequest request No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
getInitialPage
protected int getInitialPage ( HttpServletRequest request, Object command )
Return the initial page of the wizard, i.e. the page shown at wizard startup. Default implementation delegates to getInitialPage(HttpServletRequest).
Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Object command the command object as returned by formBackingObject
Wiki javadoc Use textile entry format.
Add your comments here.
getInitialPage
protected int getInitialPage ( HttpServletRequest request )
Return the initial page of the wizard, i.e. the page shown at wizard startup. Default implementation returns 0 for first page.
Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Wiki javadoc Use textile entry format.
Add your comments here.
getPageAttribute
public String getPageAttribute ( )
Return the name of the page attribute in the model.
Wiki javadoc Use textile entry format.
Add your comments here.
getPageCount
protected int getPageCount ( )
Return the number of wizard pages. Useful to check whether the last page has been reached.

Note that a concrete wizard form controller might override getPageCount(HttpServletRequest, Object) to determine the page count dynamically. The default implementation of that extended getPageCount variant returns the static page count as determined by this getPageCount() method.

Wiki javadoc Use textile entry format.
Add your comments here.
getPageCount
protected int getPageCount ( HttpServletRequest request, Object command )
Return the page count for this wizard form controller. Default implementation delegates to getPageCount().

Can be overridden to dynamically adapt the page count.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Object command the command object as returned by formBackingObject
See also
Wiki javadoc Use textile entry format.
Add your comments here.
getPages
public String[] getPages ( )
Return the wizard pages, i.e. the view names for the pages. The array index corresponds to the page number.

Note that a concrete wizard form controller might override getViewName(HttpServletRequest, Object, int) to determine the view name for each page dynamically.

Wiki javadoc Use textile entry format.
Add your comments here.
getPageSessionAttributeName
protected String getPageSessionAttributeName ( HttpServletRequest request )
Return the name of the HttpSession attribute that holds the page object for this wizard form controller.

Default implementation delegates to the getPageSessionAttributeName version without arguments.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Wiki javadoc Use textile entry format.
Add your comments here.
getPageSessionAttributeName
protected String getPageSessionAttributeName ( )
Return the name of the HttpSession attribute that holds the page object for this wizard form controller.

Default is an internal name, of no relevance to applications, as the form session attribute is not usually accessed directly. Can be overridden to use an application-specific attribute name, which allows other code to access the session attribute directly.

Wiki javadoc Use textile entry format.
Add your comments here.
getTargetPage
protected int getTargetPage ( HttpServletRequest request, Object command, Errors errors, int currentPage )
Return the target page specified in the request.

Default implementation delegates to getTargetPage(HttpServletRequest, int). Subclasses can override this for customized target page determination.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Object command form object with request parameters bound onto it
Errors errors validation errors holder
int currentPage the current page, to be returned as fallback if no target page specified
Wiki javadoc Use textile entry format.
Add your comments here.
getTargetPage
protected int getTargetPage ( HttpServletRequest request, int currentPage )
Return the target page specified in the request.

Default implementation examines "_target" parameter (e.g. "_target1"). Subclasses can override this for customized target page determination.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
int currentPage the current page, to be returned as fallback if no target page specified
See also
Wiki javadoc Use textile entry format.
Add your comments here.
getViewName
protected String getViewName ( HttpServletRequest request, Object command, int page )
Return the name of the view for the specified page of this wizard form controller. Default implementation takes the view name from the getPages() array.

Can be overridden to dynamically switch the page view or to return view names for dynamically defined pages.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Object command the command object as returned by formBackingObject
int page No description provided.
See also
Wiki javadoc Use textile entry format.
Add your comments here.
handleInvalidSubmit
protected ModelAndView handleInvalidSubmit ( HttpServletRequest request, HttpServletResponse response )
throws
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 for wizard form controllers simply shows the initial page of a new wizard form. If you want to show some "invalid submit" message, you need to override this method.

Overrides method in AbstractFormController
Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
HttpServletResponse response current HTTP response
Exceptions
Exception in case of errors
Wiki javadoc Use textile entry format.
Add your comments here.
isAllowDirtyBack
public boolean isAllowDirtyBack ( )
Return whether "dirty back" is allowed.
Wiki javadoc Use textile entry format.
Add your comments here.
isAllowDirtyForward
public boolean isAllowDirtyForward ( )
Return whether "dirty forward" is allowed.
Wiki javadoc Use textile entry format.
Add your comments here.
isCancel
protected boolean isCancel ( HttpServletRequest request )
No description provided.
Parameters
TypeNameDescription
HttpServletRequest request No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
isCancelRequest
protected boolean isCancelRequest ( HttpServletRequest request )
Determine whether the incoming request is a request to cancel the processing of the current form.

By default, this method returns true if a parameter matching the "_cancel" key is present in the request, otherwise it returns false. Subclasses may override this method to provide custom logic to detect a cancel request.

The parameter is recognized both when sent as a plain parameter ("_cancel") or when triggered by an image button ("_cancel.x").

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
See also
Wiki javadoc Use textile entry format.
Add your comments here.
isFinish
protected boolean isFinish ( HttpServletRequest request )
No description provided.
Parameters
TypeNameDescription
HttpServletRequest request No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
isFinishRequest
protected boolean isFinishRequest ( HttpServletRequest request )
Determine whether the incoming request is a request to finish the processing of the current form.

By default, this method returns true if a parameter matching the "_finish" key is present in the request, otherwise it returns false. Subclasses may override this method to provide custom logic to detect a finish request.

The parameter is recognized both when sent as a plain parameter ("_finish") or when triggered by an image button ("_finish.x").

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
See also
Wiki javadoc Use textile entry format.
Add your comments here.
isFormSubmission
protected boolean isFormSubmission ( HttpServletRequest request )
Consider an explicit finish or cancel request as a form submission too.
Overrides method in AbstractFormController
Parameters
TypeNameDescription
HttpServletRequest request No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
onBindAndValidate
protected void onBindAndValidate ( HttpServletRequest request, Object command, BindException errors )
throws
Calls page-specific onBindAndValidate method.
Overrides method in BaseCommandController
Parameters
TypeNameDescription
HttpServletRequest request No description provided.
Object command No description provided.
BindException errors No description provided.
Returns void No description provided.
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
onBindAndValidate
protected void onBindAndValidate ( HttpServletRequest request, Object command, BindException errors, int page )
throws
Callback for custom post-processing in terms of binding and validation. Called on each submit, after standard binding but before page-specific validation of this wizard form controller.

Note: AbstractWizardFormController does not perform standand validation on binding but rather applies page-specific validation on processing the form submission.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Object command bound command
BindException errors Errors instance for additional custom validation
int page current wizard page
Returns void No description provided.
Exceptions
Exception in case of invalid state or arguments
Wiki javadoc Use textile entry format.
Add your comments here.
postProcessPage
protected void postProcessPage ( HttpServletRequest request, Object command, Errors errors, int page )
throws
Post-process the given page after binding and validation, potentially updating its command object. The passed-in request might contain special parameters sent by the page.

Only invoked when displaying another page or the same page again, not when finishing or cancelling.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Object command form object with request parameters bound onto it
Errors errors validation errors holder
int page number of page to post-process
Returns void No description provided.
Exceptions
Exception in case of invalid state or arguments
Wiki javadoc Use textile entry format.
Add your comments here.
processCancel
protected ModelAndView processCancel ( HttpServletRequest request, HttpServletResponse response, Object command, BindException errors )
throws
Template method for processing the cancel action of this wizard.

Default implementation throws a ServletException, saying that a cancel operation is not supported by this controller. Thus, you do not need to implement this template method if you do not support a cancel operation.

Call errors.getModel() to populate the ModelAndView model with the command and the Errors instance, under the specified command name, as expected by the "spring:bind" tag.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
HttpServletResponse response current HTTP response
Object command form object with the current wizard state
BindException errors Errors instance containing errors
Exceptions
Exception in case of invalid state or arguments
See also
Wiki javadoc Use textile entry format.
Add your comments here.
processFinish
protected ModelAndView processFinish ( HttpServletRequest request, HttpServletResponse response, Object command, BindException errors )
throws
Template method for processing the final action of this wizard.

Call errors.getModel() to populate the ModelAndView model with the command and the Errors instance, under the specified command name, as expected by the "spring:bind" tag.

You can call the showPage method to return back to the wizard, in case of last-minute validation errors having been found that you would like to present to the user within the original wizard form.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
HttpServletResponse response current HTTP response
Object command form object with the current wizard state
BindException errors validation errors holder
Exceptions
Exception in case of invalid state or arguments
Wiki javadoc Use textile entry format.
Add your comments here.
processFormSubmission
protected ModelAndView processFormSubmission ( HttpServletRequest request, HttpServletResponse response, Object command, BindException errors )
throws
Apply wizard workflow: finish, cancel, page change.
Overrides method in AbstractFormController
Parameters
TypeNameDescription
HttpServletRequest request No description provided.
HttpServletResponse response No description provided.
Object command No description provided.
BindException errors No description provided.
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
referenceData
protected Map referenceData ( HttpServletRequest request, Object command, Errors errors )
throws
Calls page-specific referenceData method.
Overrides method in AbstractFormController
Parameters
TypeNameDescription
HttpServletRequest request No description provided.
Object command No description provided.
Errors errors No description provided.
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
referenceData
protected Map referenceData ( HttpServletRequest request, Object command, Errors errors, int page )
throws
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.

Default implementation delegates to referenceData(HttpServletRequest, int). Subclasses can override this to set reference data used in the view.

Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
Object command form object with request parameters bound onto it
Errors errors validation errors holder
int page current wizard page
Exceptions
Exception in case of invalid state or arguments
Wiki javadoc Use textile entry format.
Add your comments here.
referenceData
protected Map referenceData ( HttpServletRequest request, int page )
throws
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
TypeNameDescription
HttpServletRequest request current HTTP request
int page current wizard page
Exceptions
Exception in case of invalid state or arguments
See also
Wiki javadoc Use textile entry format.
Add your comments here.
setAllowDirtyBack
public void setAllowDirtyBack ( boolean allowDirtyBack )
Set if "dirty back" is allowed, i.e. if moving to a former wizard page is allowed in case of validation errors for the current page.
Parameters
TypeNameDescription
boolean allowDirtyBack if "dirty back" is allowed
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setAllowDirtyForward
public void setAllowDirtyForward ( boolean allowDirtyForward )
Set if "dirty forward" is allowed, i.e. if moving to a later wizard page is allowed in case of validation errors for the current page.
Parameters
TypeNameDescription
boolean allowDirtyForward if "dirty forward" is allowed
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setPageAttribute
public void setPageAttribute ( String pageAttribute )
Set the name of the page attribute in the model, containing an Integer with the current page number.

This will be necessary for single views rendering multiple view pages. It also allows for specifying the optional "_page" parameter.

Parameters
TypeNameDescription
String pageAttribute name of the page attribute
Returns void No description provided.
See also
Wiki javadoc Use textile entry format.
Add your comments here.
setPages
public void setPages ( String [] pages )
Set the wizard pages, i.e. the view names for the pages. The array index is interpreted as page number.
Parameters
TypeNameDescription
String [] pages view names for the pages
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
showForm
protected ModelAndView showForm ( HttpServletRequest request, HttpServletResponse response, BindException errors )
throws
Show first page as form view.
Overrides method in AbstractFormController
Parameters
TypeNameDescription
HttpServletRequest request No description provided.
HttpServletResponse response No description provided.
BindException errors No description provided.
Exceptions
Exception No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
showPage
protected ModelAndView showPage ( HttpServletRequest request, BindException errors, int page )
throws
Prepare the form model and view, including reference and error data, for the given page. Can be used in processFinish implementations, to show the corresponding page in case of validation errors.
Parameters
TypeNameDescription
HttpServletRequest request current HTTP request
BindException errors validation errors holder
int page number of page to show
Exceptions
Exception in case of invalid state or arguments
Wiki javadoc Use textile entry format.
Add your comments here.
validatePage
protected void validatePage ( Object command, Errors errors, int page, boolean finish )
Template method for custom validation logic for individual pages. Default implementation calls validatePage(command, errors, page).

Implementations will typically call fine-granular validateXXX methods of this instance's Validator, combining them to validation of the corresponding pages. The Validator's default validate method will not be called by a wizard form controller!

Parameters
TypeNameDescription
Object command form object with the current wizard state
Errors errors validation errors holder
int page number of page to validate
boolean finish whether this method is called during final revalidation on finish (else, it is called for validating the current page)
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
validatePage
protected void validatePage ( Object command, Errors errors, int page )
Template method for custom validation logic for individual pages. Default implementation is empty.

Implementations will typically call fine-granular validateXXX methods of this instance's validator, combining them to validation of the corresponding pages. The validator's default validate method will not be called by a wizard form controller!

Parameters
TypeNameDescription
Object command form object with the current wizard state
Errors errors validation errors holder
int page number of page to validate
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.