com.interface21.web.servlet.mvc
Class AbstractWizardFormController

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
                                |
                                +--com.interface21.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 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 hand 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, com.interface21.validation.Errors, int), processFinish(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, com.interface21.validation.BindException), processCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, com.interface21.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 com.interface21.web.servlet.mvc.BaseCommandController
DEFAULT_BEAN_NAME
 
Fields inherited from class com.interface21.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. the page shown at wizard startup.
protected  java.lang.String getPageSessionAttributeName()
          Return the name of the session attribute that holds the page object for this controller.
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 postprocessing 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 processSubmit(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, 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. if moving to a former wizard page is allowed in case of validation errors for the current page.
 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.
 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. the view names for the pages.
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 com.interface21.web.servlet.mvc.AbstractFormController
formBackingObject, getFormSessionAttributeName, handleInvalidSubmit, handleRequestInternal, isBindOnNewForm, isFormSubmission, isSessionForm, setBindOnNewForm, setSessionForm, showForm, showForm, showNewForm, userObject
 
Methods inherited from class com.interface21.web.servlet.mvc.BaseCommandController
bindAndValidate, checkCommand, createBinder, createCommand, getBeanName, getCommandClass, getValidator, initBinder, isValidateOnBinding, 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
 

Field Detail

PARAM_FINISH

public static final java.lang.String PARAM_FINISH
Parameter triggering the finish action. Can be called from any wizard page!

PARAM_CANCEL

public static final java.lang.String PARAM_CANCEL
Parameter triggering the cancel action. Can be called from any wizard page!

PARAM_TARGET

public static final java.lang.String PARAM_TARGET
Parameter specifying the target page, appending the page number to the name.
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 javax.servlet.ServletException
Call page-specific onBindAndValidate method.
Overrides:
onBindAndValidate in class BaseCommandController
Following copied from class: com.interface21.web.servlet.mvc.BaseCommandController
Parameters:
request - current HTTP request
command - bound command
errors - binder for additional custom validation
Throws:
javax.servlet.ServletException - in case of invalid state or arguments
See Also:
BaseCommandController.bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object)

onBindAndValidate

protected void onBindAndValidate(javax.servlet.http.HttpServletRequest request,
                                 java.lang.Object command,
                                 BindException errors,
                                 int page)
                          throws javax.servlet.ServletException
Callback for custom postprocessing 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 - binder for additional custom validation
page - current wizard page
Throws:
javax.servlet.ServletException - in case of invalid state or arguments
See Also:
BaseCommandController.bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object)

referenceData

protected final java.util.Map referenceData(javax.servlet.http.HttpServletRequest request,
                                            java.lang.Object command,
                                            Errors errors)
                                     throws javax.servlet.ServletException
Call page-specific referenceData method.
Overrides:
referenceData in class AbstractFormController
Following copied from class: com.interface21.web.servlet.mvc.AbstractFormController
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

referenceData

protected java.util.Map referenceData(javax.servlet.http.HttpServletRequest request,
                                      java.lang.Object command,
                                      Errors errors,
                                      int page)
                               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
page - current wizard page
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

showForm

protected final ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                      javax.servlet.http.HttpServletResponse response,
                                      BindException errors)
                               throws javax.servlet.ServletException
Show first page as form view.
Overrides:
showForm in class AbstractFormController
Following copied from class: com.interface21.web.servlet.mvc.AbstractFormController
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:
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 javax.servlet.ServletException
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 - binder containing errors
page - number of page to show
Returns:
the prepared form view
Throws:
javax.servlet.ServletException - in case of invalid state or arguments

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

getCurrentPage

protected final int getCurrentPage(javax.servlet.http.HttpServletRequest request)
                            throws java.lang.IllegalStateException
Return the current page number. Mainly useful for page-specific onBindAndValidate implementations, as methods like validatePage explicitly feature a page parameter.
Throws:
java.lang.IllegalStateException - if the page attribute isn't in the session anymore, i.e. when called after processSubmit.

processSubmit

protected final 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
Apply wizard workflow: finish, cancel, page change.
Overrides:
processSubmit in class AbstractFormController
Following copied from class: com.interface21.web.servlet.mvc.AbstractFormController
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:
AbstractFormController.showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, com.interface21.validation.BindException)

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 - binder containing errors
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 javax.servlet.ServletException,
                                              java.io.IOException
Template method for processing the final action of this wizard.
Parameters:
request - current HTTP request
response - current HTTP response
command - form object with the current wizard state
errors - binder containing errors
Returns:
the finish view
Throws:
javax.servlet.ServletException - in case of invalid state or arguments

processCancel

protected abstract ModelAndView processCancel(javax.servlet.http.HttpServletRequest request,
                                              javax.servlet.http.HttpServletResponse response,
                                              java.lang.Object command,
                                              BindException errors)
                                       throws javax.servlet.ServletException,
                                              java.io.IOException
Template method for processing the cancel action of this wizard.
Parameters:
request - current HTTP request
response - current HTTP response
command - form object with the current wizard state
errors - binder containing errors
Returns:
the finish view
Throws:
javax.servlet.ServletException - in case of invalid state or arguments


Rod Johnson and Spring contributors 2001-2003.