com.interface21.web.servlet.mvc
Class AbstractFormController

java.lang.Object
  |
  +--com.interface21.context.support.ApplicationObjectSupport
        |
        +--com.interface21.web.servlet.mvc.WebContentGenerator
              |
              +--com.interface21.web.servlet.mvc.AbstractController
                    |
                    +--com.interface21.web.servlet.mvc.BaseCommandController
                          |
                          +--com.interface21.web.servlet.mvc.AbstractFormController

All Implemented Interfaces:

ApplicationContextAware, Controller

Direct Known Subclasses:

AbstractWizardFormController, SimpleFormController

public abstract class AbstractFormController

extends BaseCommandController

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

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

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

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

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

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

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

Author:

Rod Johnson, Juergen Hoeller

See Also:

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

Fields inherited from class com.interface21.web.servlet.mvc.BaseCommandController

DEFAULT_BEAN_NAME

Fields inherited from class com.interface21.context.support.ApplicationObjectSupport

logger

Constructor Summary

AbstractFormController()
Create a new AbstractFormController.

Method Summary

protected java.lang.Object	formBackingObject(javax.servlet.http.HttpServletRequest request) Retrieve a backing object for the current form from the given request.
protected java.lang.String	getFormSessionAttributeName() Return the name of the session attribute that holds the form object for this controller.
protected ModelAndView	handleInvalidSubmit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).
protected ModelAndView	handleRequestInternal(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handles two cases: form submissions and showing a new form.
protected boolean	isBindOnNewForm() Return if request parameters should be bound in case of a new form.
protected boolean	isFormSubmission(javax.servlet.http.HttpServletRequest request) Determine if the given request represents a form submission.
protected boolean	isSessionForm() Return if session form mode is activated.
protected abstract ModelAndView	processSubmit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object command, BindException errors) Process submit request.
protected java.util.Map	referenceData(javax.servlet.http.HttpServletRequest request, java.lang.Object command, Errors errors) Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
void	setBindOnNewForm(boolean bindOnNewForm) Sets if request parameters should be bound to the form object in case of a non-submitting request, i.e. a new form.
void	setSessionForm(boolean sessionForm) Activates resp. deactivates session form mode.
protected ModelAndView	showForm(javax.servlet.http.HttpServletRequest request, BindException errors, java.lang.String viewName) Prepare model and view for the given form, including reference and errors.
protected ModelAndView	showForm(javax.servlet.http.HttpServletRequest request, BindException errors, java.lang.String viewName, java.util.Map controlModel) Prepare model and view for the given form, including reference and errors, adding a controller-specific control model.
protected abstract ModelAndView	showForm(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, BindException errors) Prepare the form model and view, including reference and error data.
protected ModelAndView	showNewForm(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Show a new form.
protected java.lang.Object	userObject(javax.servlet.http.HttpServletRequest request) Return the form object for the given request.

Methods inherited from class com.interface21.web.servlet.mvc.BaseCommandController

bindAndValidate, checkCommand, createBinder, createCommand, getBeanName, getCommandClass, getValidator, initBinder, isValidateOnBinding, onBindAndValidate, setBeanName, setCommandClass, setValidateOnBinding, setValidator

Methods inherited from class com.interface21.web.servlet.mvc.AbstractController

handleRequest, setCacheSeconds, setRequireSession, setSupportedMethods

Methods inherited from class com.interface21.web.servlet.mvc.WebContentGenerator

cacheForSeconds, preventCaching, setUseExpiresHeader

Methods inherited from class com.interface21.context.support.ApplicationObjectSupport

getApplicationContext, initApplicationContext, setApplicationContext

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractFormController

public AbstractFormController()

Create a new AbstractFormController.

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

See Also:

BaseCommandController.setBeanName(java.lang.String), BaseCommandController.setCommandClass(java.lang.Class), setBindOnNewForm(boolean), setSessionForm(boolean)

Method Detail

setBindOnNewForm

public void setBindOnNewForm(boolean bindOnNewForm)

Sets if request parameters should be bound to the form object in case of a non-submitting request, i.e. a new form.

isBindOnNewForm

protected boolean isBindOnNewForm()

Return if request parameters should be bound in case of a new form.

setSessionForm

public final void setSessionForm(boolean sessionForm)

Activates resp. deactivates session form mode. In session form mode, the form is stored in the session to keep the form object instance between requests, instead of creating a new one on each request.

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

isSessionForm

protected final boolean isSessionForm()

Return if session form mode is activated.

getFormSessionAttributeName

protected final java.lang.String getFormSessionAttributeName()

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

Returns:

the name of the form session attribute, or null if not in session form mode.

handleRequestInternal

protected final ModelAndView handleRequestInternal(javax.servlet.http.HttpServletRequest request,
                                                   javax.servlet.http.HttpServletResponse response)
                                            throws javax.servlet.ServletException,
                                                   java.io.IOException

Handles two cases: form submissions and showing a new form. Delegates the decision between the two to isFormSubmission, always treating requests without existing form session attribute as new form when using session form mode.

Overrides:

handleRequestInternal in class AbstractController

Following copied from class: com.interface21.web.servlet.mvc.AbstractController

See Also:

AbstractController.handleRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

isFormSubmission

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

Determine if the given request represents a form submission.

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

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

Parameters:

request - current HTTP request

Returns:

if the request represents a form submission

showNewForm

protected final ModelAndView showNewForm(javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response)
                                  throws javax.servlet.ServletException,
                                         java.io.IOException

Show a new form. Prepares a backing object for the current form and the given request, including checking its validity.

Parameters:

request - current HTTP request

response - current HTTP response

Returns:

the prepared form view

Throws:

javax.servlet.ServletException - in case of an invalid new form object

java.io.IOException - in case of I/O errors

formBackingObject

protected java.lang.Object formBackingObject(javax.servlet.http.HttpServletRequest request)
                                      throws javax.servlet.ServletException

Retrieve a backing object for the current form from the given request.

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

Parameters:

request - current HTTP request

Returns:

the backing objact

Throws:

javax.servlet.ServletException - in case of invalid state or arguments

See Also:

BaseCommandController.createCommand()

showForm

protected abstract ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response,
                                         BindException errors)
                                  throws javax.servlet.ServletException,
                                         java.io.IOException

Prepare the form model and view, including reference and error data. Can show a configured form page, or generate a programmatic form view.

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

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

Parameters:

request - current HTTP request

response - current HTTP response

errors - binder containing errors

Returns:

the prepared form view, or null if handled directly

Throws:

javax.servlet.ServletException - in case of invalid state or arguments

See Also:

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

showForm

protected final ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                      BindException errors,
                                      java.lang.String viewName)
                               throws javax.servlet.ServletException

Prepare model and view for the given form, including reference and errors. In session form mode: Re-puts the form object in the session when returning to the form, as it has been removed by userObject. Can be used in subclasses to redirect back to a specific form page.

Parameters:

request - current HTTP request

errors - binder containing errors

viewName - name of the form view

Returns:

the prepared form view

Throws:

javax.servlet.ServletException - in case of invalid state or arguments

showForm

protected final ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                      BindException errors,
                                      java.lang.String viewName,
                                      java.util.Map controlModel)
                               throws javax.servlet.ServletException

Prepare model and view for the given form, including reference and errors, adding a controller-specific control model. In session form mode: Re-puts the form object in the session when returning to the form, as it has been removed by userObject. Can be used in subclasses to redirect back to a specific form page.

Parameters:

request - current HTTP request

errors - binder containing errors

viewName - name of the form view

controlModel - model map containing controller-specific control data (e.g. current page in wizard-style controllers).

Returns:

the prepared form view

Throws:

javax.servlet.ServletException - in case of invalid state or arguments

referenceData

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

Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.

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

Parameters:

request - current HTTP request

command - form object with request parameters bound onto it

errors - binder containing current errors, if any

Returns:

a Map with reference data entries, or null if none

Throws:

javax.servlet.ServletException - in case of invalid state or arguments

See Also:

ModelAndView

handleInvalidSubmit

protected ModelAndView handleInvalidSubmit(javax.servlet.http.HttpServletRequest request,
                                           javax.servlet.http.HttpServletResponse response)
                                    throws javax.servlet.ServletException,
                                           java.io.IOException

Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).

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

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

Parameters:

request - current HTTP request

response - current HTTP response

Returns:

a prepared view, or null if handled directly

Throws:

javax.servlet.ServletException - in case of invalid state

java.io.IOException - in case of I/O errors

See Also:

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

userObject

protected final java.lang.Object userObject(javax.servlet.http.HttpServletRequest request)
                                     throws javax.servlet.ServletException

Return the form object for the given request. In session form mode: Retrieve the form object from the session. The form object gets removed from the session, but it will be re-added when showing the form for resubmission.

Overrides:

userObject in class BaseCommandController

Parameters:

request - current HTTP request

Returns:

object form to bind onto

Throws:

javax.servlet.ServletException - in case of invalid state or arguments

processSubmit

protected abstract ModelAndView processSubmit(javax.servlet.http.HttpServletRequest request,
                                              javax.servlet.http.HttpServletResponse response,
                                              java.lang.Object command,
                                              BindException errors)
                                       throws javax.servlet.ServletException,
                                              java.io.IOException

Process submit request. Called by handleRequestInternal in case of a form submission.

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

Parameters:

request - current servlet request

response - current servlet response

command - form object with request parameters bound onto it

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

Returns:

the prepared model and view, or null

Throws:

javax.servlet.ServletException - in case of invalid state or arguments

java.io.IOException - in case of I/O errors

See Also:

showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, com.interface21.validation.BindException)