org.springframework.web.servlet.mvc
Class AbstractWizardFormController

java.lang.Object
  org.springframework.context.support.ApplicationObjectSupport
      org.springframework.web.context.support.WebApplicationObjectSupport
          org.springframework.web.servlet.support.WebContentGenerator
              org.springframework.web.servlet.mvc.AbstractController
                  org.springframework.web.servlet.mvc.BaseCommandController
                      org.springframework.web.servlet.mvc.AbstractFormController
                          org.springframework.web.servlet.mvc.AbstractWizardFormController

All Implemented Interfaces:

ApplicationContextAware, Controller

public abstract 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 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 respective view names to setPages.

Since:

25.04.2003

Author:

Juergen Hoeller

See Also:

setPages(java.lang.String[]), validatePage(java.lang.Object, org.springframework.validation.Errors, int), processFinish(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, org.springframework.validation.BindException), processCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, org.springframework.validation.BindException)

Field Summary

static java.lang.String	PARAM_CANCEL Parameter triggering the cancel action.
static java.lang.String	PARAM_FINISH Parameter triggering the finish action.
static java.lang.String	PARAM_TARGET Parameter specifying the target page, appending the page number to the name.

Fields inherited from class org.springframework.web.servlet.mvc.BaseCommandController

DEFAULT_COMMAND_NAME

Fields inherited from class org.springframework.web.servlet.support.WebContentGenerator

HEADER_CACHE_CONTROL, HEADER_EXPIRES, HEADER_PRAGMA, METHOD_GET, METHOD_POST

Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

logger

Constructor Summary

AbstractWizardFormController()
Create a new AbstractWizardFormController.

Method Summary

protected int	getCurrentPage(javax.servlet.http.HttpServletRequest request) Return the current page number.
protected int	getInitialPage(javax.servlet.http.HttpServletRequest request) Return the initial page of the wizard, i.e.
protected int	getInitialPage(javax.servlet.http.HttpServletRequest request, java.lang.Object command) Return the initial page of the wizard, i.e.
protected java.lang.String	getPageSessionAttributeName() Return the name of the session attribute that holds the page object for this controller.
protected int	getTargetPage(javax.servlet.http.HttpServletRequest request, int currentPage) Return the target page specified in the request.
protected int	getTargetPage(javax.servlet.http.HttpServletRequest request, java.lang.Object command, Errors errors, int currentPage) Return the target page specified in the request.
protected ModelAndView	handleInvalidSubmit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an invalid submit request, e.g.
protected boolean	isCancel(javax.servlet.http.HttpServletRequest request) Return if cancel action is specified in the request.
protected boolean	isFinish(javax.servlet.http.HttpServletRequest request) Return if finish action is specified in the request.
protected void	onBindAndValidate(javax.servlet.http.HttpServletRequest request, java.lang.Object command, BindException errors) Call page-specific onBindAndValidate method.
protected void	onBindAndValidate(javax.servlet.http.HttpServletRequest request, java.lang.Object command, BindException errors, int page) Callback for custom post-processing in terms of binding and validation.
protected abstract ModelAndView	processCancel(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object command, BindException errors) Template method for processing the cancel action of this wizard.
protected abstract ModelAndView	processFinish(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object command, BindException errors) Template method for processing the final action of this wizard.
protected ModelAndView	processFormSubmission(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object command, BindException errors) Apply wizard workflow: finish, cancel, page change.
protected java.util.Map	referenceData(javax.servlet.http.HttpServletRequest request, int page) Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
protected java.util.Map	referenceData(javax.servlet.http.HttpServletRequest request, java.lang.Object command, Errors errors) Call page-specific referenceData method.
protected java.util.Map	referenceData(javax.servlet.http.HttpServletRequest request, java.lang.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.
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(java.lang.String pageAttribute) Set the name of the page attribute in the model, containing an Integer with the current page number.
void	setPages(java.lang.String[] pages) Set the wizard pages, i.e.
protected ModelAndView	showForm(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, BindException errors) Show first page as form view.
protected ModelAndView	showPage(javax.servlet.http.HttpServletRequest request, BindException errors, int page) Prepare the form model and view, including reference and error data, for the given page.
protected abstract void	validatePage(java.lang.Object command, Errors errors, int page) Template method for custom validation logic for individual pages.

Methods inherited from class org.springframework.web.servlet.mvc.AbstractFormController

formBackingObject, getCommand, getFormSessionAttributeName, handleRequestInternal, isBindOnNewForm, isFormSubmission, isSessionForm, setBindOnNewForm, setSessionForm, showForm, showForm, showNewForm

Methods inherited from class org.springframework.web.servlet.mvc.BaseCommandController

bindAndValidate, checkCommand, createBinder, createCommand, getCommandClass, getCommandName, getValidator, initBinder, isValidateOnBinding, onBind, setCommandClass, setCommandName, setValidateOnBinding, setValidator

Methods inherited from class org.springframework.web.servlet.mvc.AbstractController

handleRequest, setSynchronizeOnSession

Methods inherited from class org.springframework.web.servlet.support.WebContentGenerator

applyCacheSeconds, applyCacheSeconds, cacheForSeconds, cacheForSeconds, checkAndPrepare, preventCaching, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseExpiresHeader

Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

getServletContext, getTempDir, getWebApplicationContext, requiredContextClass

Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

getApplicationContext, getMessageSourceAccessor, initApplicationContext, setApplicationContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PARAM_FINISH

public static final java.lang.String PARAM_FINISH

Parameter triggering the finish action. Can be called from any wizard page!

See Also:

Constant Field Values

PARAM_CANCEL

public static final java.lang.String PARAM_CANCEL

Parameter triggering the cancel action. Can be called from any wizard page!

See Also:

Constant Field Values

PARAM_TARGET

public static final java.lang.String PARAM_TARGET

Parameter specifying the target page, appending the page number to the name.

See Also:

Constant Field Values

Constructor Detail

AbstractWizardFormController

public AbstractWizardFormController()

Create a new AbstractWizardFormController.

Method Detail

setPages

public final void setPages(java.lang.String[] pages)

Set the wizard pages, i.e. the view names for the pages. The array index is interpreted as page number.

Parameters:

pages - view names for the pages

setPageAttribute

public final void setPageAttribute(java.lang.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.

Parameters:

pageAttribute - name of the page attribute

setAllowDirtyBack

public final 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:

allowDirtyBack - if "dirty back" is allowed

setAllowDirtyForward

public final 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:

allowDirtyForward - if "dirty forward" is allowed

onBindAndValidate

protected final void onBindAndValidate(javax.servlet.http.HttpServletRequest request,
                                       java.lang.Object command,
                                       BindException errors)
                                throws java.lang.Exception

Call page-specific onBindAndValidate method.

Overrides:

onBindAndValidate in class BaseCommandController

Parameters:

request - current HTTP request

command - command object, still allowing for further binding

errors - validation errors holder, allowing for additional custom validation

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

BaseCommandController.bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object), Errors

onBindAndValidate

protected void onBindAndValidate(javax.servlet.http.HttpServletRequest request,
                                 java.lang.Object command,
                                 BindException errors,
                                 int page)
                          throws java.lang.Exception

Callback for custom post-processing in terms of binding and validation. Called on each submit, after standard binding and validation, and before error evaluation.

Parameters:

request - current HTTP request

command - bound command

errors - Errors instance for additional custom validation

page - current wizard page

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

BaseCommandController.bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object), Errors

referenceData

protected final java.util.Map referenceData(javax.servlet.http.HttpServletRequest request,
                                            java.lang.Object command,
                                            Errors errors)
                                     throws java.lang.Exception

Call page-specific referenceData method.

Overrides:

referenceData in class AbstractFormController

Parameters:

request - current HTTP request

command - form object with request parameters bound onto it

errors - validation errors holder

Returns:

a Map with reference data entries, or null if none

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

ModelAndView

referenceData

protected java.util.Map referenceData(javax.servlet.http.HttpServletRequest request,
                                      java.lang.Object command,
                                      Errors errors,
                                      int page)
                               throws java.lang.Exception

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:

request - current HTTP request

command - form object with request parameters bound onto it

errors - validation errors holder

page - current wizard page

Returns:

a Map with reference data entries, or null if none

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

referenceData(HttpServletRequest, int), ModelAndView

referenceData

protected java.util.Map referenceData(javax.servlet.http.HttpServletRequest request,
                                      int page)
                               throws java.lang.Exception

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

page - current wizard page

Returns:

a Map with reference data entries, or null if none

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

ModelAndView

showForm

protected final ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                      javax.servlet.http.HttpServletResponse response,
                                      BindException errors)
                               throws java.lang.Exception

Show first page as form view.

Specified by:

showForm in class AbstractFormController

Parameters:

request - current HTTP request

response - current HTTP response

errors - validation errors holder

Returns:

the prepared form view, or null if handled directly

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

AbstractFormController.showForm(HttpServletRequest, BindException, String), SimpleFormController.setFormView(java.lang.String)

showPage

protected final ModelAndView showPage(javax.servlet.http.HttpServletRequest request,
                                      BindException errors,
                                      int page)
                               throws java.lang.Exception

Prepare the form model and view, including reference and error data, for the given page. Can be used in processFinish implementations, to show the respective page in case of validation errors.

Parameters:

request - current HTTP request

errors - validation errors holder

page - number of page to show

Returns:

the prepared form view

Throws:

java.lang.Exception - in case of invalid state or arguments

getInitialPage

protected int getInitialPage(javax.servlet.http.HttpServletRequest request,
                             java.lang.Object command)

Return the initial page of the wizard, i.e. the page shown at wizard startup. Default implementation delegates to getInitialPage(HttpServletRequest).

Parameters:

request - current HTTP request

command - the command object as returned by formBackingObject

Returns:

the initial page number

See Also:

getInitialPage(HttpServletRequest), AbstractFormController.formBackingObject(javax.servlet.http.HttpServletRequest)

getInitialPage

protected int getInitialPage(javax.servlet.http.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:

request - current HTTP request

Returns:

the initial page number

getPageSessionAttributeName

protected final java.lang.String getPageSessionAttributeName()

Return the name of the session attribute that holds the page object for this controller.

Returns:

the name of the page session attribute

handleInvalidSubmit

protected ModelAndView handleInvalidSubmit(javax.servlet.http.HttpServletRequest request,
                                           javax.servlet.http.HttpServletResponse response)
                                    throws java.lang.Exception

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:

handleInvalidSubmit in class AbstractFormController

Parameters:

request - current HTTP request

response - current HTTP response

Returns:

a prepared view, or null if handled directly

Throws:

java.lang.Exception - in case of errors

See Also:

AbstractFormController.showNewForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse), AbstractFormController.setBindOnNewForm(boolean)

processFormSubmission

protected final ModelAndView processFormSubmission(javax.servlet.http.HttpServletRequest request,
                                                   javax.servlet.http.HttpServletResponse response,
                                                   java.lang.Object command,
                                                   BindException errors)
                                            throws java.lang.Exception

Apply wizard workflow: finish, cancel, page change.

Specified by:

processFormSubmission in class AbstractFormController

Parameters:

request - current servlet request

response - current servlet response

command - form object with request parameters bound onto it

errors - holder without errors (subclass can add errors if it wants to)

Returns:

the prepared model and view, or null

Throws:

java.lang.Exception - in case of errors

See Also:

AbstractFormController.isFormSubmission(javax.servlet.http.HttpServletRequest), AbstractFormController.showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, org.springframework.validation.BindException), Errors

getCurrentPage

protected int getCurrentPage(javax.servlet.http.HttpServletRequest request)
                      throws java.lang.IllegalStateException

Return the current page number. Used by processFormSubmission. Can also be called by page-specific onBindAndValidate implementations, as methods like validatePage explicitly feature a page parameter.

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

Throws:

java.lang.IllegalStateException - if the page attribute isn't in the session anymore, i.e. when called after processFormSubmission.

See Also:

getPageSessionAttributeName()

isFinish

protected boolean isFinish(javax.servlet.http.HttpServletRequest request)

Return if finish action is specified in the request.

Parameters:

request - current HTTP request

isCancel

protected boolean isCancel(javax.servlet.http.HttpServletRequest request)

Return if cancel action is specified in the request.

Parameters:

request - current HTTP request

getTargetPage

protected int getTargetPage(javax.servlet.http.HttpServletRequest request,
                            java.lang.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:

request - current HTTP request

command - form object with request parameters bound onto it

errors - validation errors holder

currentPage - the current page, to be returned as fallback if no target page specified

Returns:

the page specified in the request, or current page if not found

See Also:

getTargetPage(HttpServletRequest, int)

getTargetPage

protected int getTargetPage(javax.servlet.http.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:

request - current HTTP request

currentPage - the current page, to be returned as fallback if no target page specified

Returns:

the page specified in the request, or current page if not found

See Also:

PARAM_TARGET

validatePage

protected abstract void validatePage(java.lang.Object command,
                                     Errors errors,
                                     int page)

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

Parameters:

command - form object with the current wizard state

errors - validation errors holder

page - number of page to show

processFinish

protected abstract ModelAndView processFinish(javax.servlet.http.HttpServletRequest request,
                                              javax.servlet.http.HttpServletResponse response,
                                              java.lang.Object command,
                                              BindException errors)
                                       throws java.lang.Exception

Template method for processing the final action of this wizard.

Can call errors.getModel() to populate the ModelAndView model with the command and the Errors instance, under the specified bean name.

Parameters:

request - current HTTP request

response - current HTTP response

command - form object with the current wizard state

errors - validation errors holder

Returns:

the finish view

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

Errors

processCancel

protected abstract ModelAndView processCancel(javax.servlet.http.HttpServletRequest request,
                                              javax.servlet.http.HttpServletResponse response,
                                              java.lang.Object command,
                                              BindException errors)
                                       throws java.lang.Exception

Template method for processing the cancel action of this wizard.

Can call errors.getModel() to populate the ModelAndView model with the command and the Errors instance, under the specified bean name.

Parameters:

request - current HTTP request

response - current HTTP response

command - form object with the current wizard state

errors - Errors instance containing errors

Returns:

the finish view

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

Errors