This class is deprecated.
as of Spring 3.0, in favor of annotated controllers
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 current page number will be stored in the session. It can also be specified as request parameter PARAM_PAGE ("_page") in order to properly handle usage of the back button in a browser: In this case, a submission will always contain 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.
Parameters indicated with setPassRenderParameters
will be present
for each page. If there are render parameters you need in renderFinish
or renderCancel
, then you need to pass those forward from the
processFinish
or processCancel
methods, respectively.
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | PARAM_CANCEL | Parameter triggering the cancel action. | |||||||||
String | PARAM_FINISH | Parameter triggering the finish action. | |||||||||
String | PARAM_PAGE | Parameter specifying the current page as value. | |||||||||
String | PARAM_TARGET | Parameter specifying the target page, appending the page number to the name. |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.web.portlet.mvc.BaseCommandController
|
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.context.support.ApplicationObjectSupport
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a new AbstractWizardFormController.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Return the name of the page attribute in the model.
| |||||||||||
Return the wizard pages, i.e.
| |||||||||||
Return whether "dirty back" is allowed.
| |||||||||||
Return whether "dirty forward" is allowed.
| |||||||||||
Set if "dirty back" is allowed, i.e.
| |||||||||||
Set if "dirty forward" is allowed, i.e.
| |||||||||||
Set the name of the page attribute in the model, containing
an Integer with the current page number.
| |||||||||||
Set the wizard pages, i.e.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Return the current page number.
| |||||||||||
Return the initial page of the wizard, i.e.
| |||||||||||
Return the initial page of the wizard, i.e.
| |||||||||||
Return the page count for this wizard form controller.
| |||||||||||
Return the number of wizard pages.
| |||||||||||
Return the name of the PortletSession attribute that holds the page object
for this wizard form controller.
| |||||||||||
Return the name of the PortletSession attribute that holds the page object
for this wizard form controller.
| |||||||||||
Return the target page specified in the request.
| |||||||||||
Return the target page specified in the request.
| |||||||||||
Return the name of the view for the specified page of this wizard form controller.
| |||||||||||
Handle an invalid submit request, e.g.
| |||||||||||
Determine whether the incoming request is a request to cancel the
processing of the current form.
| |||||||||||
Determine whether the incoming request is a request to finish the
processing of the current form.
| |||||||||||
Consider an explicit finish or cancel request as a form submission too.
| |||||||||||
Callback for custom post-processing in terms of binding and validation.
| |||||||||||
Calls page-specific onBindAndValidate method.
| |||||||||||
Post-process the given page after binding and validation, potentially
updating its command object.
| |||||||||||
Template method for the action phase of the cancel action of this wizard.
| |||||||||||
Template method for the action phase of the finish action of this wizard.
| |||||||||||
Apply wizard workflow: finish, cancel, page change.
| |||||||||||
Create a reference data map for the given request, consisting of
bean name/bean instance pairs as expected by ModelAndView.
| |||||||||||
Calls page-specific referenceData method.
| |||||||||||
Create a reference data map for the given request, consisting of
bean name/bean instance pairs as expected by ModelAndView.
| |||||||||||
Template method for the render phase of the cancel action of this wizard.
| |||||||||||
Template method for the render phase of the finish action of this wizard.
| |||||||||||
Apply wizard workflow: finish, cancel, page change.
| |||||||||||
Handle an invalid submit request, e.g.
| |||||||||||
Pass the the parameter that indicates a cancel request forward to the
render phase.
| |||||||||||
Pass the the parameter that indicates a finish request forward to the
render phase.
| |||||||||||
Pass the page number to the render phase by setting a render parameter.
| |||||||||||
Pass the the parameter that indicates the target page of the request
forward to the render phase.
| |||||||||||
Show the first page as form view.
| |||||||||||
Prepare the form model and view, including reference and error data,
for the given page.
| |||||||||||
Template method for custom validation logic for individual pages.
| |||||||||||
Template method for custom validation logic for individual pages.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.web.portlet.mvc.AbstractFormController
| |||||||||||
From class
org.springframework.web.portlet.mvc.BaseCommandController
| |||||||||||
From class
org.springframework.web.portlet.mvc.AbstractController
| |||||||||||
From class
org.springframework.web.portlet.handler.PortletContentGenerator
| |||||||||||
From class
org.springframework.web.portlet.context.PortletApplicationObjectSupport
| |||||||||||
From class
org.springframework.context.support.ApplicationObjectSupport
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
org.springframework.context.ApplicationContextAware
| |||||||||||
From interface
org.springframework.web.portlet.context.PortletContextAware
| |||||||||||
From interface
org.springframework.web.portlet.mvc.Controller
|
Parameter triggering the cancel action. Can be called from any wizard page!
Parameter triggering the finish action. Can be called from any wizard page!
Parameter specifying the current page as value. Not necessary on form pages, but allows to properly handle usage of the back button.
Parameter specifying the target page, appending the page number to the name.
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).
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(PortletRequest, Object, int)
to
determine the view name for each page dynamically.
Return whether "dirty back" is allowed.
Return whether "dirty forward" is allowed.
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.
allowDirtyBack | if "dirty back" is allowed |
---|
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.
allowDirtyForward | if "dirty forward" is allowed |
---|
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.
pageAttribute | name of the page attribute |
---|
Set the wizard pages, i.e. the view names for the pages. The array index is interpreted as page number.
pages | view names for the pages |
---|
Return the current page number. Used by processFormSubmission(ActionRequest, ActionResponse, Object, BindException)
.
The default implementation checks the page session attribute. Subclasses can override this for customized page determination.
request | current portlet request |
---|
Return the initial page of the wizard, i.e. the page shown at wizard startup.
The default implementation delegates to getInitialPage(PortletRequest)
.
request | current portlet request |
---|---|
command | the command object as returned by formBackingObject |
Return the initial page of the wizard, i.e. the page shown at wizard startup.
The default implementation returns 0 for first page.
request | current portlet request |
---|
Return the page count for this wizard form controller.
The default implementation delegates to getPageCount()
.
Can be overridden to dynamically adapt the page count.
request | current portlet request |
---|---|
command | the command object as returned by formBackingObject |
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(PortletRequest, Object)
to determine
the page count dynamically.
Return the name of the PortletSession 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.
getFormSessionAttributeName()
Return the name of the PortletSession attribute that holds the page object for this wizard form controller.
The default implementation delegates to the getPageSessionAttributeName
version without arguments.
request | current portlet request |
---|
getPageSessionAttributeName()
getFormSessionAttributeName()
Return the target page specified in the request.
The default implementation examines "_target" parameter (e.g. "_target1"). Subclasses can override this for customized target page determination.
request | current portlet request |
---|---|
currentPage | the current page, to be returned as fallback if no target page specified |
Return the target page specified in the request.
The default implementation delegates to getTargetPage(PortletRequest, int)
.
Subclasses can override this for customized target page determination.
request | current portlet 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 |
Return the name of the view for the specified page of this wizard form controller.
The 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.
request | current portlet request |
---|---|
command | the command object as returned by formBackingObject |
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).
The default implementation for wizard form controllers simply shows the initial page of a new wizard form, so here in the action phase this method does nothing. If you want to take some action on an invalid submit, you need to override this method.
request | current portlet action request |
---|---|
response | current portlet action response |
Exception | in case of errors |
---|
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").
request | current portlet 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").
request | current portlet request |
---|
Consider an explicit finish or cancel request as a form submission too.
request | current request |
---|
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 standard validation on binding but rather applies page-specific validation on processing the form submission.
request | current portlet request |
---|---|
command | bound command |
errors | Errors instance for additional custom validation |
page | current wizard page |
Exception | in case of invalid state or arguments |
---|
Calls page-specific onBindAndValidate method.
request | current portlet request |
---|---|
command | the command object, still allowing for further binding |
errors | validation errors holder, allowing for additional custom validation |
Exception |
---|
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.
request | current action request |
---|---|
command | form object with request parameters bound onto it |
errors | validation errors holder |
page | number of page to post-process |
Exception | in case of invalid state or arguments |
---|
Template method for the action phase of the cancel action of this wizard.
The default implementation throws a PortletException, saying that a cancel action request is not supported by this controller. Thus, you do not need to implement this template method if you do not support a cancel operation.
request | current portlet action request |
---|---|
response | current portlet action response |
command | form object with the current wizard state |
errors | Errors instance containing errors |
Exception | in case of invalid state or arguments |
---|
Template method for the action phase of the finish action of this wizard.
The default implementation throws a PortletException, saying that a finish action request is not supported by this controller. You will almost certainly need to override this method.
request | current portlet action request |
---|---|
response | current portlet action response |
command | form object with the current wizard state |
errors | validation errors holder |
Exception | in case of invalid state or arguments |
---|
Apply wizard workflow: finish, cancel, page change.
request | current action request |
---|---|
response | current action response |
command | form object with request parameters bound onto it |
errors | errors holder (subclass can add errors if it wants to) |
Exception |
---|
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
The default implementation delegates to referenceData(PortletRequest, int)
.
Subclasses can override this to set reference data used in the view.
request | current portlet request |
---|---|
command | form object with request parameters bound onto it |
errors | validation errors holder |
page | current wizard page |
Exception | in case of invalid state or arguments |
---|
Calls page-specific referenceData method.
request | current render request |
---|---|
command | form object with request parameters bound onto it |
errors | validation errors holder |
Exception |
---|
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
The default implementation returns null
.
Subclasses can override this to set reference data used in the view.
request | current portlet request |
---|---|
page | current wizard page |
Exception | in case of invalid state or arguments |
---|
Template method for the render phase of the cancel action of this wizard.
The default implementation throws a PortletException, saying that a cancel render request 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.
request | current portlet render request |
---|---|
response | current portlet render response |
command | form object with the current wizard state |
errors | Errors instance containing errors |
Exception | in case of invalid state or arguments |
---|
Template method for the render phase of the finish action of this wizard.
The default implementation throws a PortletException, saying that a finish render request is not supported by this controller. Thus, you do not need to implement this template method if you do not need to render after a finish.
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.
request | current portlet render request |
---|---|
response | current portlet render response |
command | form object with the current wizard state |
errors | validation errors holder |
Exception | in case of invalid state or arguments |
---|
Apply wizard workflow: finish, cancel, page change.
request | current render request |
---|---|
response | current render response |
command | form object with request parameters bound onto it |
errors | errors holder |
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).
The 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.
request | current portlet render request |
---|---|
response | current portlet render response |
Exception | in case of errors |
---|
Pass the the parameter that indicates a cancel request forward to the
render phase. If the isCancelRequest
method
was overridden, this may need to be overriden as well.
request | the current action request |
---|---|
response | the current action response |
PARAM_CANCEL
isCancelRequest(PortletRequest)
Pass the the parameter that indicates a finish request forward to the
render phase. If the isFinishRequest
method
was overridden, this may need to be overriden as well.
request | the current action request |
---|---|
response | the current action response |
PARAM_FINISH
isFinishRequest(PortletRequest)
Pass the page number to the render phase by setting a render parameter. This method may not be called when the action calls javax.portlet.ActionResponse#sendRedirect(String).
response | the current action response |
---|---|
page | the page number |
Pass the the parameter that indicates the target page of the request
forward to the render phase. If the getTargetPage
method
was overridden, this may need to be overriden as well.
request | the current action request |
---|---|
response | the current action response |
PARAM_TARGET
getTargetPage(PortletRequest, int)
getTargetPage(PortletRequest, Object, Errors, int)
Show the first page as form view.
This can be overridden in subclasses, e.g. to prepare wizard-specific error views in case of an Exception.
request | current render request |
---|---|
response | current render response |
errors | validation errors holder |
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 corresponding page in case of validation errors.
request | current portlet render request |
---|---|
errors | validation errors holder |
page | number of page to show |
Exception | in case of invalid state or arguments |
---|
Template method for custom validation logic for individual pages. The 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!
command | form object with the current wizard state |
---|---|
errors | validation errors holder |
page | number of page to validate |
Template method for custom validation logic for individual pages.
The 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!
command | form object with the current wizard state |
---|---|
errors | validation errors holder |
page | number of page to validate |
finish | whether this method is called during final revalidation on finish (else, it is called for validating the current page) |