Java Doc for FormAction.java in  » Workflow-Engines » spring-webflow-1.0.4 » org » springframework » webflow » action » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Several action execution methods are provided:

• FormAction.setupForm(RequestContext) - Prepares the form object for display on a form, FormAction.createFormObject(RequestContext) creating it and an associated Errors errors object if necessary, then caching them in the configured FormAction.getFormObjectScope() form object scope and FormAction.getFormErrorsScope() form errors scope , respectively. Also FormAction.registerPropertyEditors(PropertyEditorRegistry) installs any custom property editors for formatting form object field values. This action method will return the "success" event unless an exception is thrown.
• FormAction.bindAndValidate(RequestContext) - Binds all incoming request parameters to the form object and then validates the form object using a FormAction.setValidator(Validator) 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.
• FormAction.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.
• FormAction.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.
• FormAction.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:

1. Create a view state to display the form. In a render action of that state, invoke FormAction.setupForm(RequestContext) setupForm to prepare the new form for display.
2. On a matching "submit" transition execute an action that invokes FormAction.bindAndValidate(RequestContext) bindAndValidate to bind incoming request parameters to the form object and validate the form object.
3. If there are binding or validation errors, the transition will not be allowed and the view state will automatically be re-entered.
4. If binding and validation is 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.
5. If business processing is ok, continue to a view state to display the success view.

Here is an example implementation of such a compact form flow:

 <view-state id="displayCriteria" view="searchCriteria">
 <render-actions>
 <action bean="formAction" method="setupForm"/>
 </render-actions>
 <transition on="search" to="executeSearch">
 <action bean="formAction" method="bindAndValidate"/>
 </transition>
 </view-state>
 <action-state id="executeSearch">
 <action bean="formAction" method="executeSearch"/>
 <transition on="success" to="displayResults"/>
 </action-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 FormAction.createFormObject(RequestContext) 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 FormAction.initBinder(RequestContext,DataBinder) initBinder . This is called after a new data binder is created.
• Another optional ook method is FormAction.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 FormAction.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();
 }
 

 <view-state id="displayCriteria" view="searchCriteria">
 <render-actions>
 <action bean="searchFormAction" method="setupForm"/>
 <action bean="searchFormAction" method="setupReferenceData"/>
 </render-actions>
 ...
 </view-state>
 

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 FormAction.bind(RequestContext) instead of FormAction.bindAndValidate(RequestContext) or don't register a validator.
• If you want piecemeal validation, e.g. in a multi-page wizard, call FormAction.bindAndValidate(RequestContext) or FormAction.validate(RequestContext) and specify a FormAction.VALIDATOR_METHOD_ATTRIBUTE 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:

   <action bean="searchFormAction" method="bindAndValidate">
   <attribute name="validatorMethod" value="validateSearchCriteria"/>
   </action>
   

  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 org.springframework.validation.Validator.validate(java.lang.Objectorg.springframework.validation.Errors) validate method of the registered validator, call FormAction.bindAndValidate(RequestContext) or FormAction.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	org.springframework.webflow.execution.ScopeType.FLOW 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	org.springframework.webflow.execution.ScopeType.FLASH 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 FormAction.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.

See Also:   org.springframework.beans.PropertyEditorRegistrar
See Also:   org.springframework.validation.DataBinder
See Also:   ScopeType
author:
   Erwin Vervaet
author:
   Keith Donald

NOTE: This action method is not designed to be overidden and might become final in a future version of Spring Web Flow.

NOTE: This action method is not designed to be overidden and might become final in a future version of Spring Web Flow.

NOTE: This action method is not designed to be overidden and might become final in a future version of Spring Web Flow.

NOTE: This action method is not designed to be overidden and might become final in a future version of Spring Web Flow.

NOTE: This action method is not designed to be overidden 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 FormAction.doBind(RequestContext,DataBinder) hook.
Parameters:
  context - the action execution context, for accessing and settingdata in "flow scope" or "request scope" "success" if there are no binding errors, "error" otherwise
throws:
  Exception - an unrecoverable exception occured, eitherchecked or unchecked

NOTE: This action method is not designed to be overidden 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 FormAction.doBind(RequestContext,DataBinder) or FormAction.doValidate(RequestContext,Object,Errors) hooks.
Parameters:
  context - the action execution context, for accessing and settingdata in "flow scope" or "request scope" "success" when binding and validation is successful, "error" ifthere were binding and/or validation errors
throws:
  Exception - an unrecoverable exception occured, eitherchecked or unchecked

Default implementation creates a standard WebDataBinder, and invokes FormAction.initBinder(RequestContext,DataBinder) and FormAction.registerPropertyEditors(PropertyEditorRegistry) .
Parameters:
  context - the action execution context, for accessing and settingdata in "flow scope" or "request scope"
Parameters:
  formObject - the form object to bind onto the new binder instance
throws:
  Exception - when an unrecoverable exception occurs
See Also:   WebDataBinder
See Also:   FormAction.initBinder(RequestContext,DataBinder)
See Also:   FormAction.setMessageCodesResolver(MessageCodesResolver)

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.
Parameters:
  context - the action execution context for accessing flow data the form object
throws:
  IllegalStateException - if the FormAction.getFormObjectClass()property is not set and this method has not been overridden
throws:
  Exception - when an unrecoverable exception occurs

Keep in mind that an Errors instance wraps a form object, so a form object will also be created if required (see FormAction.getFormObject(RequestContext) ).
Parameters:
  context - the flow request context the form errors
throws:
  Exception - when an unrecoverable exception occurs

The returned form object will become the FormObjectAccessor.setCurrentFormObject(ObjectScopeType) current form object.
Parameters:
  context - the flow execution request context the form object
throws:
  Exception - when an unrecoverable exception occurs

Note that registration of custom property editors should be done in FormAction.registerPropertyEditors(PropertyEditorRegistry) , not here! This method will only be called when a new data binder is created.
Parameters:
  context - the action execution context, for accessing and settingdata in "flow scope" or "request scope"
Parameters:
  binder - new binder instance
See Also:   FormAction.createBinder(RequestContext,Object)

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 FormAction.registerPropertyEditors(PropertyEditorRegistry) simpler form of the method not taking a RequestContext parameter.
Parameters:
  context - the action execution context, for accessing and settingdata in "flow scope" or "request scope"
Parameters:
  registry - the property editor registry to register editors in
See Also:   FormAction.registerPropertyEditors(PropertyEditorRegistry)

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 FormAction.getPropertyEditorRegistrar() propertyEditorRegistrar object that has been set for the action, if any.
Parameters:
  registry - the property editor registry to register editors in

NOTE: This action method is not designed to be overidden 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.
Parameters:
  context - the request context "success" if the reset action completed successfully
throws:
  Exception - if an exception occured
See Also:   FormAction.createFormObject(RequestContext)

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) .

Default is null, i.e. using the default strategy of the data binder.
See Also:   FormAction.createBinder(RequestContext,Object)
See Also:   org.springframework.validation.DataBinder.setMessageCodesResolver(org.springframework.validation.MessageCodesResolver)

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

NOTE: This action method is not designed to be overidden 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.
Parameters:
  context - the action execution context, for accessing and settingdata in "flow scope" or "request scope" "success" when binding and validation is successful
throws:
  Exception - an unrecoverable exception occurs, eitherchecked or unchecked
See Also:   FormAction.createFormObject(RequestContext)

NOTE: This action method is not designed to be overidden 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 FormAction.doValidate(RequestContext,Object,Errors) hook.
Parameters:
  context - the action execution context, for accessing and settingdata in "flow scope" or "request scope" "success" if there are no validation errors, "error" otherwise
throws:
  Exception - an unrecoverable exception occured, eitherchecked or unchecked
See Also:   FormAction.getValidator()