org.springframework.webflow.action: public class: FormAction

org.springframework.webflow.action
public class: FormAction [javadoc | source]

java.lang.Object
   org.springframework.webflow.action.AbstractAction
      org.springframework.webflow.action.MultiAction
         org.springframework.webflow.action.FormAction

All Implemented Interfaces:
org.springframework.beans.factory.InitializingBean, Action, org.springframework.beans.factory.InitializingBean

Multi-action that implements common logic dealing with input forms. This class uses the Spring Web data binding code to do binding and validation.

Several action execution methods are provided:

#setupForm(RequestContext) - Prepares the form object for display on a form, creating it and an associated errors if necessary, then caching them in the configured form object scope and form errors scope , respectively. Also installs any custom property editors for formatting form object field values. This action method will return the "success" event unless an exception is thrown.
#bindAndValidate(RequestContext) - Binds all incoming request parameters to the form object and then validates the form object using a registered validator . This action method will return the "success" event if there are no binding or validation errors, otherwise it will return the "error" event.
#bind(RequestContext) - Binds all incoming request parameters to the form object. No additional validation is performed. This action method will return the "success" event if there are no binding errors, otherwise it will return the "error" event.
#validate(RequestContext) - Validates the form object using a registered validator. No data binding is performed. This action method will return the "success" event if there are no validation errors, otherwise it will return the "error" event.
#resetForm(RequestContext) - Resets the form by reloading the backing form object and reinstalling any custom property editors. Returns "success" on completion, an exception is thrown when a failure occurs.

Since this is a multi-action a subclass could add any number of additional action execution methods, e.g. "setupReferenceData(RequestContext)", or "processSubmit(RequestContext)".

Using this action, it becomes very easy to implement form preparation and submission logic in your flow. One way to do this follows:

Create a view state to display the form. In a render action of that state, invoke setupForm to prepare the new form for display.
On a matching "submit" transition execute an action that invokes bindAndValidate to bind incoming request parameters to the form object and validate the form object.
If there are binding or validation errors, the transition will not be allowed and the view state will automatically be re-entered.
If binding and validation are successful go to an action state called "processSubmit" (or any other appropriate name). This will invoke an action method called "processSubmit" you must provide on a subclass to process form submission, e.g. interacting with the business logic.
If business processing is ok, continue to a view state to display the success view.

Here is an example implementation of such a form flow:

<view-state id="displayCriteria">
<on-render>
<evaluate expression="formAction.setupForm"/>
</on-render>
<transition on="search" to="executeSearch">
<evaluate expression="formAction.bindAndValidate"/>
</transition>
</view-state>

When you need additional flexibility consider splitting the view state above acting as a single logical form state into multiple states. For example, you could have one action state handle form setup, a view state trigger form display, another action state handle data binding and validation, and another process form submission. This would be a bit more verbose but would also give you more control over how you respond to specific results of fine-grained actions that occur within the flow.

Subclassing hooks:

A important hook is createFormObject . You may override this to customize where the backing form object instance comes from (e.g instantiated transiently in memory or loaded from a database).
An optional hook method provided by this class is initBinder . This is called after a new data binder is created.
Another optional hook method is #registerPropertyEditors(PropertyEditorRegistry) . By overriding it you can register any required property editors for your form. Instead of overriding this method, consider setting an explicit org.springframework.beans.PropertyEditorRegistrar strategy as a more reusable way to encapsulate custom PropertyEditor installation logic.
Override #validationEnabled(RequestContext) to dynamically decide whether or not to do validation based on data available in the request context.

Note that this action does not provide a referenceData() hook method similar to that of Spring MVC's SimpleFormController. If you wish to expose reference data to populate form drop downs you can define a custom action method in your FormAction subclass that does just that. Simply invoke it as either a chained action as part of the setupForm state, or as a fine grained state definition itself.

For example, you might create this method in your subclass:

public Event setupReferenceData(RequestContext context) throws Exception {
MutableAttributeMap requestScope = context.getRequestScope();
requestScope.put("refData", lookupService.getSupportingFormData());
return success();
}

... and then invoke it like this:

<view-state id="displayCriteria">
<on-render>
<evaluate expression="formAction.setupForm"/>
<evaluate expression="formAction.setupReferenceData"/>
</on-render>
...
</view-state>

This style of calling multiple action methods in a chain (Chain of Responsibility) is preferred to overriding a single action method. In general, action method overriding is discouraged.

When it comes to validating submitted input data using a registered org.springframework.validation.Validator , this class offers the following options:

If you don't want validation at all, just call #bind(RequestContext) instead of #bindAndValidate(RequestContext) or don't register a validator.
If you want piecemeal validation, e.g. in a multi-page wizard, call #bindAndValidate(RequestContext) or #validate(RequestContext) and specify a validatorMethod action execution attribute. This will invoke the identified custom validator method on the validator. The validator method signature should follow the following pattern:
```
public void ${validateMethodName}(${formObjectClass}, Errors)
```
For instance, having a action definition like this:
```
<evaluate expression="formAction.bindAndValidate">
<attribute name="validatorMethod" value="validateSearchCriteria"/>
</evaluate>
```
Would result in the public void validateSearchCriteria(SearchCriteria, Errors) method of the registered validator being called if the form object class would be SearchCriteria.
If you want to do full validation using the validate method of the registered validator, call #bindAndValidate(RequestContext) or #validate(RequestContext) without specifying a "validatorMethod" action execution attribute.

FormAction configurable properties

name default description

formObjectName formObject The name of the form object. The form object will be set in the configured scope using this name.

formObjectClass null The form object class for this action. An instance of this class will get populated and validated. Required when using a validator.

formObjectScope flow The scope in which the form object will be put. If put in flow scope the object will be cached and reused over the life of the flow, preserving previous values. Request scope will cause a new fresh form object instance to be created on each request into the flow execution.

formErrorsScope flash The scope in which the form object errors instance will be put. If put in flash scope form errors will be cached until the next user event is signaled.

propertyEditorRegistrar null The strategy used to register custom property editors with the data binder. This is an alternative to overriding the #registerPropertyEditors(PropertyEditorRegistry) hook method.

validator null The validator for this action. The validator must support the specified form object class.

messageCodesResolver null Set the strategy to use for resolving errors into message codes.

Also see:

org.springframework.beans.PropertyEditorRegistrar

org.springframework.validation.DataBinder

ScopeType

author: Erwin - Vervaet

author: Keith - Donald

Field Summary
public static final String	DEFAULT_FORM_OBJECT_NAME	The default form object name ("formObject").
public static final String	VALIDATOR_METHOD_ATTRIBUTE	Optional attribute that identifies the method that should be invoked on the configured validator instance, to support piecemeal wizard page validation ("validatorMethod").

Fields inherited from org.springframework.webflow.action.AbstractAction:
logger

Constructor:

Constructor:
public FormAction() { } Bean-style default constructor; creates a initially unconfigured FormAction instance relying on default property values. Clients invoking this constructor directly must set the formObjectClass property or override #createFormObject(RequestContext) . Also see: setFormObjectClass(Class)
public FormAction(Class formObjectClass) { setFormObjectClass(formObjectClass); } Creates a new form action that manages instance(s) of the specified form object class. Parameters: `formObjectClass` - the class of the form object (must be instantiable)

 public FormAction() {

}

Bean-style default constructor; creates a initially unconfigured FormAction instance relying on default property values. Clients invoking this constructor directly must set the formObjectClass property or override

#createFormObject(RequestContext)

Also see:

setFormObjectClass(Class)

 public FormAction(Class formObjectClass) {
		setFormObjectClass(formObjectClass);
}

Creates a new form action that manages instance(s) of the specified form object class.

Parameters:

formObjectClass - the class of the form object (must be instantiable)

Method from org.springframework.webflow.action.FormAction Summary:
bind, bindAndValidate, createBinder, createFormObject, doBind, doValidate, getFormErrors, getFormErrorsScope, getFormObject, getFormObjectAccessor, getFormObjectClass, getFormObjectName, getFormObjectScope, getMessageCodesResolver, getPropertyEditorRegistrar, getValidateMethodInvoker, getValidator, initAction, initBinder, registerPropertyEditors, registerPropertyEditors, resetForm, setFormErrorsScope, setFormObjectClass, setFormObjectName, setFormObjectScope, setMessageCodesResolver, setPropertyEditorRegistrar, setValidator, setupForm, toString, validate, validationEnabled

Method from org.springframework.webflow.action.FormAction Summary:

bind, bindAndValidate, createBinder, createFormObject, doBind, doValidate, getFormErrors, getFormErrorsScope, getFormObject, getFormObjectAccessor, getFormObjectClass, getFormObjectName, getFormObjectScope, getMessageCodesResolver, getPropertyEditorRegistrar, getValidateMethodInvoker, getValidator, initAction, initBinder, registerPropertyEditors, registerPropertyEditors, resetForm, setFormErrorsScope, setFormObjectClass, setFormObjectName, setFormObjectScope, setMessageCodesResolver, setPropertyEditorRegistrar, setValidator, setupForm, toString, validate, validationEnabled

Methods from org.springframework.webflow.action.MultiAction:
doExecute, getMethodResolver, setMethodResolver, setTarget

Methods from org.springframework.webflow.action.AbstractAction:
afterPropertiesSet, doExecute, doPostExecute, doPreExecute, error, error, execute, getActionNameForLogging, getEventFactorySupport, initAction, no, result, result, result, result, success, success, yes

Methods from java.lang.Object:
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from org.springframework.webflow.action.FormAction Detail:
public Event bind(RequestContext context) throws Exception { if (logger.isDebugEnabled()) { logger.debug("Executing bind"); } Object formObject = getFormObject(context); DataBinder binder = createBinder(context, formObject); doBind(context, binder); putFormErrors(context, binder.getBindingResult()); return binder.getBindingResult().hasErrors() ? error() : success(); } Bind incoming request parameters to allowed fields of the form object. NOTE: This action method is not designed to be overridden and might become `final` in a future version of Spring Web Flow. If you need to execute custom data binding logic have your flow call this method along with your own custom methods as part of a single action chain. Alternatively, override the #doBind(RequestContext, DataBinder) hook.
public Event bindAndValidate(RequestContext context) throws Exception { if (logger.isDebugEnabled()) { logger.debug("Executing bind"); } Object formObject = getFormObject(context); DataBinder binder = createBinder(context, formObject); doBind(context, binder); if (getValidator() != null && validationEnabled(context)) { if (logger.isDebugEnabled()) { logger.debug("Executing validation"); } doValidate(context, formObject, binder.getBindingResult()); } else { if (logger.isDebugEnabled()) { if (getValidator() == null) { logger.debug("No validator is configured, no validation will occur after binding"); } else { logger.debug("Validation was disabled for this bindAndValidate request"); } } } putFormErrors(context, binder.getBindingResult()); return binder.getBindingResult().hasErrors() ? error() : success(); } Bind incoming request parameters to allowed fields of the form object and then validate the bound form object if a validator is configured. NOTE: This action method is not designed to be overridden and might become `final` in a future version of Spring Web Flow. If you need to execute custom bind and validate logic have your flow call this method along with your own custom methods as part of a single action chain. Alternatively, override the #doBind(RequestContext, DataBinder) or #doValidate(RequestContext, Object, Errors) hooks.
protected DataBinder createBinder(RequestContext context, Object formObject) throws Exception { DataBinder binder = new WebDataBinder(formObject, getFormObjectName()); if (getMessageCodesResolver() != null) { binder.setMessageCodesResolver(getMessageCodesResolver()); } initBinder(context, binder); registerPropertyEditors(context, binder); return binder; } Create a new binder instance for the given form object and request context. Can be overridden to plug in custom DataBinder subclasses. Default implementation creates a standard WebDataBinder, and invokes #initBinder(RequestContext, DataBinder) and #registerPropertyEditors(PropertyEditorRegistry) .
protected Object createFormObject(RequestContext context) throws Exception { if (getFormObjectClass() == null) { throw new IllegalStateException("Cannot create form object without formObjectClass property being set -- " + "either set formObjectClass or override createFormObject"); } if (logger.isDebugEnabled()) { logger.debug("Creating new instance of form object class [" + getFormObjectClass() + "]"); } return getFormObjectClass().newInstance(); } Create the backing form object instance that should be managed by this form action . By default, will attempt to instantiate a new form object instance of type #getFormObjectClass() transiently in memory. Subclasses should override if they need to load the form object from a specific location or resource such as a database or filesystem. Subclasses should override if they need to customize how a transient form object is assembled during creation.
protected void doBind(RequestContext context, DataBinder binder) throws Exception { if (logger.isDebugEnabled()) { logger.debug("Binding allowed request parameters in " + StylerUtils.style(context.getExternalContext().getRequestParameterMap()) + " to form object with name '" + binder.getObjectName() + "', pre-bind formObject toString = " + binder.getTarget()); if (binder.getAllowedFields() != null && binder.getAllowedFields().length > 0) { logger.debug("(Allowed fields are " + StylerUtils.style(binder.getAllowedFields()) + ")"); } else { logger.debug("(Any field is allowed)"); } } binder.bind(new MutablePropertyValues(context.getRequestParameters().asMap())); if (logger.isDebugEnabled()) { logger.debug("Binding completed for form object with name '" + binder.getObjectName() + "', post-bind formObject toString = " + binder.getTarget()); logger.debug("There are [" + binder.getBindingResult().getErrorCount() + "] errors, details: " + binder.getBindingResult().getAllErrors()); } } Bind allowed parameters in the external context request parameter map to the form object using given binder.
protected void doValidate(RequestContext context, Object formObject, Errors errors) throws Exception { Assert.notNull(getValidator(), "The validator must not be null when attempting validation -- programmer error"); String validatorMethodName = context.getAttributes().getString(VALIDATOR_METHOD_ATTRIBUTE); if (StringUtils.hasText(validatorMethodName)) { if (logger.isDebugEnabled()) { logger.debug("Invoking validation method '" + validatorMethodName + "' on validator " + getValidator()); } invokeValidatorMethod(validatorMethodName, formObject, errors); } else { if (logger.isDebugEnabled()) { logger.debug("Invoking validator " + getValidator()); } getValidator().validate(formObject, errors); } if (logger.isDebugEnabled()) { logger.debug("Validation completed for form object"); logger.debug("There are [" + errors.getErrorCount() + "] errors, details: " + errors.getAllErrors()); } } Validate given form object using a registered validator. If a "validatorMethod" action property is specified for the currently executing action, the identified validator method will be invoked. When no such property is found, the defualt `validate()` method is invoked.
protected Errors getFormErrors(RequestContext context) throws Exception { Object formObject = getFormObject(context); ensureFormErrorsExposed(context, formObject); return getFormObjectAccessor(context).getFormErrors(getFormObjectName(), getFormErrorsScope()); } Convenience method that returns the form object errors for this form action. If not found in the configured scope, a new form object errors will be created, initialized, and exposed in the confgured scope . Keep in mind that an Errors instance wraps a form object, so a form object will also be created if required (see #getFormObject(RequestContext) ).
public ScopeType getFormErrorsScope() { return formErrorsScope; } Get the scope in which the Errors object will be placed.
protected Object getFormObject(RequestContext context) throws Exception { FormObjectAccessor accessor = getFormObjectAccessor(context); Object formObject = accessor.getFormObject(getFormObjectName(), getFormObjectScope()); if (formObject == null) { formObject = initFormObject(context); } else { if (logger.isDebugEnabled()) { logger.debug("Found existing form object with name '" + getFormObjectName() + "' of type [" + formObject.getClass() + "] in scope " + getFormObjectScope()); } accessor.setCurrentFormObject(formObject, getFormObjectScope()); } return formObject; } Convenience method that returns the form object for this form action. If not found in the configured scope, a new form object will be created by a call to #createFormObject(RequestContext) and exposed in the configured scope . The returned form object will become the current form object.
protected FormObjectAccessor getFormObjectAccessor(RequestContext context) { return new FormObjectAccessor(context); } Factory method that returns a new form object accessor for accessing form objects in the provided request context.
public Class getFormObjectClass() { return formObjectClass; } Return the form object class for this action.
public String getFormObjectName() { return formObjectName; } Return the name of the form object in the configured scope.
public ScopeType getFormObjectScope() { return formObjectScope; } Get the scope in which the form object will be placed.
public MessageCodesResolver getMessageCodesResolver() { return messageCodesResolver; } Return the strategy to use for resolving errors into message codes.
public PropertyEditorRegistrar getPropertyEditorRegistrar() { return propertyEditorRegistrar; } Get the property editor registration strategy for this action's data binders.
protected DispatchMethodInvoker getValidateMethodInvoker() { return validateMethodInvoker; } Returns a dispatcher to invoke validation methods. Subclasses could override this to return a custom dispatcher.
public Validator getValidator() { return validator; } Returns the validator for this action.
protected void initAction() { if (getValidator() != null) { if (getFormObjectClass() != null && !getValidator().supports(getFormObjectClass())) { throw new IllegalArgumentException("Validator [" + getValidator() + "] does not support form object class [" + getFormObjectClass() + "]"); } // signature: public void ${validateMethodName}(${formObjectClass}, Errors) validateMethodInvoker = new DispatchMethodInvoker(getValidator(), new Class[] { getFormObjectClass(), Errors.class }); } }
protected void initBinder(RequestContext context, DataBinder binder) { } Initialize a new binder instance. This hook allows customization of binder settings such as the allowed fields , required fields and direct field access . Called by #createBinder(RequestContext, Object) . Note that registration of custom property editors should be done in #registerPropertyEditors(PropertyEditorRegistry) , not here! This method will only be called when a new data binder is created.
protected void registerPropertyEditors(PropertyEditorRegistry registry) { if (getPropertyEditorRegistrar() != null) { if (logger.isDebugEnabled()) { logger.debug("Registering custom property editors using configured registrar"); } getPropertyEditorRegistrar().registerCustomEditors(registry); } else { if (logger.isDebugEnabled()) { logger.debug("No property editor registrar set, no custom editors to register"); } } } Register custom editors to perform type conversion on fields of your form object during data binding and form display. This method is called on form errors initialization and data binder initialization. Property editors give you full control over how objects are transformed to and from a formatted String form for display on a user interface such as a HTML page. This default implementation will simply call `registerCustomEditors` on the propertyEditorRegistrar object that has been set for the action, if any.
protected void registerPropertyEditors(RequestContext context, PropertyEditorRegistry registry) { registerPropertyEditors(registry); } Register custom editors to perform type conversion on fields of your form object during data binding and form display. This method is called on form errors initialization and data binder initialization. Property editors give you full control over how objects are transformed to and from a formatted String form for display on a user interface such as a HTML page. This default implementation will call the simpler form of the method not taking a `RequestContext` parameter.
public Event resetForm(RequestContext context) throws Exception { Object formObject = initFormObject(context); initFormErrors(context, formObject); return success(); } Resets the form by clearing out the form object in the specified scope and recreating it. NOTE: This action method is not designed to be overridden and might become `final` in a future version of Spring Web Flow. If you need to execute custom reset logic have your flow call this method along with your own custom methods as part of a single action chain.
public void setFormErrorsScope(ScopeType errorsScope) { this.formErrorsScope = errorsScope; } Set the scope in which the Errors object will be placed. The default if not set is flash scope .
public void setFormObjectClass(Class formObjectClass) { this.formObjectClass = formObjectClass; // generate a default form object name if ((getFormObjectName() == null \|\| getFormObjectName() == DEFAULT_FORM_OBJECT_NAME) && formObjectClass != null) { setFormObjectName(ClassUtils.getShortNameAsProperty(formObjectClass)); } } Set the form object class for this action. An instance of this class will get populated and validated. This is a required property if you register a validator with the form action (#setValidator(Validator) )! If no form object name is set at the moment this method is called, a form object name will be automatically generated based on the provided form object class using ClassUtils#getShortNameAsProperty(java.lang.Class) .
public void setFormObjectName(String formObjectName) { this.formObjectName = formObjectName; } Set the name of the form object in the configured scope. The form object will be included in the configured scope under this name.
public void setFormObjectScope(ScopeType scopeType) { this.formObjectScope = scopeType; } Set the scope in which the form object will be placed. The default if not set is flow scope .
public void setMessageCodesResolver(MessageCodesResolver messageCodesResolver) { this.messageCodesResolver = messageCodesResolver; } Set the strategy to use for resolving errors into message codes. Applies the given strategy to all data binders used by this action. Default is null, i.e. using the default strategy of the data binder.
public void setPropertyEditorRegistrar(PropertyEditorRegistrar propertyEditorRegistrar) { this.propertyEditorRegistrar = propertyEditorRegistrar; } Set a property editor registration strategy for this action's data binders. This is an alternative to overriding the #registerPropertyEditors(PropertyEditorRegistry) method.
public void setValidator(Validator validator) { this.validator = validator; } Set the validator for this action. When setting a validator, you must also set the form object class . The validator must support the specified form object class.
public Event setupForm(RequestContext context) throws Exception { if (logger.isDebugEnabled()) { logger.debug("Executing setupForm"); } // retrieve the form object, creating it if necessary Object formObject = getFormObject(context); ensureFormErrorsExposed(context, formObject); return success(); } Prepares a form object for display in a new form, creating it and caching it in the #getFormObjectScope() if necessary. Also installs custom property editors for formatting form object values in UI controls such as text fields. A new form object instance will only be created (or more generally acquired) with a call to #createFormObject(RequestContext) , if the form object does not yet exist in the configured scope . If you want to reset the form handling machinery, including creation or loading of a fresh form object instance, call #resetForm(RequestContext) instead. NOTE: This action method is not designed to be overridden and might become `final` in a future version of Spring Web Flow. If you need to execute custom form setup logic have your flow call this method along with your own custom methods as part of a single action chain.
public String toString() { return new ToStringCreator(this).append("formObjectName", formObjectName).append("formObjectClass", formObjectClass).append("formObjectScope", formObjectScope).toString(); }
public Event validate(RequestContext context) throws Exception { if (getValidator() != null && validationEnabled(context)) { if (logger.isDebugEnabled()) { logger.debug("Executing validation"); } Object formObject = getFormObject(context); Errors errors = getFormErrors(context); doValidate(context, formObject, errors); return errors.hasErrors() ? error() : success(); } else { if (logger.isDebugEnabled()) { if (getValidator() == null) { logger.debug("No validator is configured, no validation will occur"); } else { logger.debug("Validation was disabled for this request"); } } return success(); } } Validate the form object by invoking the validator if configured. NOTE: This action method is not designed to be overridden and might become `final` in a future version of Spring Web Flow. If you need to execute custom validation logic have your flow call this method along with your own custom methods as part of a single action chain. Alternatively, override the #doValidate(RequestContext, Object, Errors) hook.
protected boolean validationEnabled(RequestContext context) { return true; } Return whether validation should be performed given the state of the flow request context. Default implementation always returns true.

Method from org.springframework.webflow.action.FormAction Detail:

 public Event bind(RequestContext context) throws Exception {
		if (logger.isDebugEnabled()) {
			logger.debug("Executing bind");
		}
		Object formObject = getFormObject(context);
		DataBinder binder = createBinder(context, formObject);
		doBind(context, binder);
		putFormErrors(context, binder.getBindingResult());
		return binder.getBindingResult().hasErrors() ? error() : success();
}

NOTE: This action method is not designed to be overridden and might become final in a future version of Spring Web Flow. If you need to execute custom data binding logic have your flow call this method along with your own custom methods as part of a single action chain. Alternatively, override the #doBind(RequestContext, DataBinder) hook.

 public Event bindAndValidate(RequestContext context) throws Exception {
		if (logger.isDebugEnabled()) {
			logger.debug("Executing bind");
		}
		Object formObject = getFormObject(context);
		DataBinder binder = createBinder(context, formObject);
		doBind(context, binder);
		if (getValidator() != null && validationEnabled(context)) {
			if (logger.isDebugEnabled()) {
				logger.debug("Executing validation");
			}
			doValidate(context, formObject, binder.getBindingResult());
		} else {
			if (logger.isDebugEnabled()) {
				if (getValidator() == null) {
					logger.debug("No validator is configured, no validation will occur after binding");
				} else {
					logger.debug("Validation was disabled for this bindAndValidate request");
				}
			}
		}
		putFormErrors(context, binder.getBindingResult());
		return binder.getBindingResult().hasErrors() ? error() : success();
}

NOTE: This action method is not designed to be overridden and might become final in a future version of Spring Web Flow. If you need to execute custom bind and validate logic have your flow call this method along with your own custom methods as part of a single action chain. Alternatively, override the #doBind(RequestContext, DataBinder) or #doValidate(RequestContext, Object, Errors) hooks.

 protected DataBinder createBinder(RequestContext context,
    Object formObject) throws Exception {
		DataBinder binder = new WebDataBinder(formObject, getFormObjectName());
		if (getMessageCodesResolver() != null) {
			binder.setMessageCodesResolver(getMessageCodesResolver());
		}
		initBinder(context, binder);
		registerPropertyEditors(context, binder);
		return binder;
}

Default implementation creates a standard WebDataBinder, and invokes #initBinder(RequestContext, DataBinder) and #registerPropertyEditors(PropertyEditorRegistry) .

 protected Object createFormObject(RequestContext context) throws Exception {
		if (getFormObjectClass() == null) {
			throw new IllegalStateException("Cannot create form object without formObjectClass property being set -- "
					+ "either set formObjectClass or override createFormObject");
		}
		if (logger.isDebugEnabled()) {
			logger.debug("Creating new instance of form object class [" + getFormObjectClass() + "]");
		}
		return getFormObjectClass().newInstance();
}

form action

#getFormObjectClass()

Subclasses should override if they need to load the form object from a specific location or resource such as a database or filesystem.

Subclasses should override if they need to customize how a transient form object is assembled during creation.

 protected  void doBind(RequestContext context,
    DataBinder binder) throws Exception {
		if (logger.isDebugEnabled()) {
			logger.debug("Binding allowed request parameters in "
					+ StylerUtils.style(context.getExternalContext().getRequestParameterMap())
					+ " to form object with name '" + binder.getObjectName() + "', pre-bind formObject toString = "
					+ binder.getTarget());
			if (binder.getAllowedFields() != null && binder.getAllowedFields().length  > 0) {
				logger.debug("(Allowed fields are " + StylerUtils.style(binder.getAllowedFields()) + ")");
			} else {
				logger.debug("(Any field is allowed)");
			}
		}
		binder.bind(new MutablePropertyValues(context.getRequestParameters().asMap()));
		if (logger.isDebugEnabled()) {
			logger.debug("Binding completed for form object with name '" + binder.getObjectName()
					+ "', post-bind formObject toString = " + binder.getTarget());
			logger.debug("There are [" + binder.getBindingResult().getErrorCount() + "] errors, details: "
					+ binder.getBindingResult().getAllErrors());
		}
}

Bind allowed parameters in the external context request parameter map to the form object using given binder.

 protected  void doValidate(RequestContext context,
    Object formObject,
    Errors errors) throws Exception {
		Assert.notNull(getValidator(), "The validator must not be null when attempting validation -- programmer error");
		String validatorMethodName = context.getAttributes().getString(VALIDATOR_METHOD_ATTRIBUTE);
		if (StringUtils.hasText(validatorMethodName)) {
			if (logger.isDebugEnabled()) {
				logger.debug("Invoking validation method '" + validatorMethodName + "' on validator " + getValidator());
			}
			invokeValidatorMethod(validatorMethodName, formObject, errors);
		} else {
			if (logger.isDebugEnabled()) {
				logger.debug("Invoking validator " + getValidator());
			}
			getValidator().validate(formObject, errors);
		}
		if (logger.isDebugEnabled()) {
			logger.debug("Validation completed for form object");
			logger.debug("There are [" + errors.getErrorCount() + "] errors, details: " + errors.getAllErrors());
		}
}

validate()

 protected Errors getFormErrors(RequestContext context) throws Exception {
		Object formObject = getFormObject(context);
		ensureFormErrorsExposed(context, formObject);
		return getFormObjectAccessor(context).getFormErrors(getFormObjectName(), getFormErrorsScope());
}

scope

Keep in mind that an Errors instance wraps a form object, so a form object will also be created if required (see #getFormObject(RequestContext) ).

 public ScopeType getFormErrorsScope() {
		return formErrorsScope;
}

Get the scope in which the Errors object will be placed.

 protected Object getFormObject(RequestContext context) throws Exception {
		FormObjectAccessor accessor = getFormObjectAccessor(context);
		Object formObject = accessor.getFormObject(getFormObjectName(), getFormObjectScope());
		if (formObject == null) {
			formObject = initFormObject(context);
		} else {
			if (logger.isDebugEnabled()) {
				logger.debug("Found existing form object with name '" + getFormObjectName() + "' of type ["
						+ formObject.getClass() + "] in scope " + getFormObjectScope());
			}
			accessor.setCurrentFormObject(formObject, getFormObjectScope());
		}
		return formObject;
}

#createFormObject(RequestContext)

scope

The returned form object will become the current form object.

 protected FormObjectAccessor getFormObjectAccessor(RequestContext context) {
		return new FormObjectAccessor(context);
}

Factory method that returns a new form object accessor for accessing form objects in the provided request context.

 public Class getFormObjectClass() {
		return formObjectClass;
}

Return the form object class for this action.

 public String getFormObjectName() {
		return formObjectName;
}

Return the name of the form object in the configured scope.

 public ScopeType getFormObjectScope() {
		return formObjectScope;
}

Get the scope in which the form object will be placed.

 public MessageCodesResolver getMessageCodesResolver() {
		return messageCodesResolver;
}

Return the strategy to use for resolving errors into message codes.

 public PropertyEditorRegistrar getPropertyEditorRegistrar() {
		return propertyEditorRegistrar;
}

Get the property editor registration strategy for this action's data binders.

 protected DispatchMethodInvoker getValidateMethodInvoker() {
		return validateMethodInvoker;
}

Returns a dispatcher to invoke validation methods. Subclasses could override this to return a custom dispatcher.

 public Validator getValidator() {
		return validator;
}

Returns the validator for this action.

 protected  void initAction() {
		if (getValidator() != null) {
			if (getFormObjectClass() != null && !getValidator().supports(getFormObjectClass())) {
				throw new IllegalArgumentException("Validator [" + getValidator()
						+ "] does not support form object class [" + getFormObjectClass() + "]");
			}
			// signature: public void ${validateMethodName}(${formObjectClass}, Errors)
			validateMethodInvoker = new DispatchMethodInvoker(getValidator(), new Class[] { getFormObjectClass(),
					Errors.class });
		}
}

 protected  void initBinder(RequestContext context,
    DataBinder binder) {

}

allowed fields

required fields

direct field access

#createBinder(RequestContext, Object)

Note that registration of custom property editors should be done in #registerPropertyEditors(PropertyEditorRegistry) , not here! This method will only be called when a new data binder is created.

 protected  void registerPropertyEditors(PropertyEditorRegistry registry) {
		if (getPropertyEditorRegistrar() != null) {
			if (logger.isDebugEnabled()) {
				logger.debug("Registering custom property editors using configured registrar");
			}
			getPropertyEditorRegistrar().registerCustomEditors(registry);
		} else {
			if (logger.isDebugEnabled()) {
				logger.debug("No property editor registrar set, no custom editors to register");
			}
		}
}

data binder

Property editors give you full control over how objects are transformed to and from a formatted String form for display on a user interface such as a HTML page.

This default implementation will simply call registerCustomEditors on the propertyEditorRegistrar object that has been set for the action, if any.

 protected  void registerPropertyEditors(RequestContext context,
    PropertyEditorRegistry registry) {
		registerPropertyEditors(registry);
}

data binder

Property editors give you full control over how objects are transformed to and from a formatted String form for display on a user interface such as a HTML page.

This default implementation will call the simpler form of the method not taking a RequestContext parameter.

 public Event resetForm(RequestContext context) throws Exception {
		Object formObject = initFormObject(context);
		initFormErrors(context, formObject);
		return success();
}

NOTE: This action method is not designed to be overridden and might become final in a future version of Spring Web Flow. If you need to execute custom reset logic have your flow call this method along with your own custom methods as part of a single action chain.

 public  void setFormErrorsScope(ScopeType errorsScope) {
		this.formErrorsScope = errorsScope;
}

flash scope

 public  void setFormObjectClass(Class formObjectClass) {
		this.formObjectClass = formObjectClass;
		// generate a default form object name
		if ((getFormObjectName() == null || getFormObjectName() == DEFAULT_FORM_OBJECT_NAME) && formObjectClass != null) {
			setFormObjectName(ClassUtils.getShortNameAsProperty(formObjectClass));
		}
}

#setValidator(Validator)

If no form object name is set at the moment this method is called, a form object name will be automatically generated based on the provided form object class using ClassUtils#getShortNameAsProperty(java.lang.Class) .

 public  void setFormObjectName(String formObjectName) {
		this.formObjectName = formObjectName;
}

Set the name of the form object in the configured scope. The form object will be included in the configured scope under this name.

 public  void setFormObjectScope(ScopeType scopeType) {
		this.formObjectScope = scopeType;
}

flow scope

 public  void setMessageCodesResolver(MessageCodesResolver messageCodesResolver) {
		this.messageCodesResolver = messageCodesResolver;
}

Default is null, i.e. using the default strategy of the data binder.

 public  void setPropertyEditorRegistrar(PropertyEditorRegistrar propertyEditorRegistrar) {
		this.propertyEditorRegistrar = propertyEditorRegistrar;
}

#registerPropertyEditors(PropertyEditorRegistry)

 public  void setValidator(Validator validator) {
		this.validator = validator;
}

form object class

 public Event setupForm(RequestContext context) throws Exception {
		if (logger.isDebugEnabled()) {
			logger.debug("Executing setupForm");
		}
		// retrieve the form object, creating it if necessary
		Object formObject = getFormObject(context);
		ensureFormErrorsExposed(context, formObject);
		return success();
}

#getFormObjectScope()

A new form object instance will only be created (or more generally acquired) with a call to #createFormObject(RequestContext) , if the form object does not yet exist in the configured scope . If you want to reset the form handling machinery, including creation or loading of a fresh form object instance, call #resetForm(RequestContext) instead.

NOTE: This action method is not designed to be overridden and might become final in a future version of Spring Web Flow. If you need to execute custom form setup logic have your flow call this method along with your own custom methods as part of a single action chain.

 public String toString() {
		return new ToStringCreator(this).append("formObjectName", formObjectName).append("formObjectClass",
				formObjectClass).append("formObjectScope", formObjectScope).toString();
}

 public Event validate(RequestContext context) throws Exception {
		if (getValidator() != null && validationEnabled(context)) {
			if (logger.isDebugEnabled()) {
				logger.debug("Executing validation");
			}
			Object formObject = getFormObject(context);
			Errors errors = getFormErrors(context);
			doValidate(context, formObject, errors);
			return errors.hasErrors() ? error() : success();
		} else {
			if (logger.isDebugEnabled()) {
				if (getValidator() == null) {
					logger.debug("No validator is configured, no validation will occur");
				} else {
					logger.debug("Validation was disabled for this request");
				}
			}
			return success();
		}
}

NOTE: This action method is not designed to be overridden and might become final in a future version of Spring Web Flow. If you need to execute custom validation logic have your flow call this method along with your own custom methods as part of a single action chain. Alternatively, override the #doValidate(RequestContext, Object, Errors) hook.

 protected boolean validationEnabled(RequestContext context) {
		return true;
}

Return whether validation should be performed given the state of the flow request context. Default implementation always returns true.

name	default	description
formObjectName	formObject	The name of the form object. The form object will be set in the configured scope using this name.
formObjectClass	null	The form object class for this action. An instance of this class will get populated and validated. Required when using a validator.
formObjectScope	flow	The scope in which the form object will be put. If put in flow scope the object will be cached and reused over the life of the flow, preserving previous values. Request scope will cause a new fresh form object instance to be created on each request into the flow execution.
formErrorsScope	flash	The scope in which the form object errors instance will be put. If put in flash scope form errors will be cached until the next user event is signaled.
propertyEditorRegistrar	null	The strategy used to register custom property editors with the data binder. This is an alternative to overriding the #registerPropertyEditors(PropertyEditorRegistry) hook method.
validator	null	The validator for this action. The validator must support the specified form object class.
messageCodesResolver	null	Set the strategy to use for resolving errors into message codes.