1. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. Forms with Spring MVC Handling Form Input

2. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 2 Topics in this Session Form Workflow Primer Spring MVC Form Processing APIs –DataBinder –Validator –Form UI Tag Library SimpleFormController

3. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 3 Topics in this Session Form Workflow Primer Spring MVC Form Processing APIs –DataBinder –Validator –Form UI Tag Library SimpleFormController

4. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 4 Form Workflow Primer Forms often create or edit entities For example –Create a Reward –Edit a Reward

5. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 5 Common Form Workflows Simple Form –The user completes the form in a single POST request Wizard Form –The user completes the form over multiple POST requests –More complicated since state needs to be managed between requests

6. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 6 Simple Form Workflows Simple form flows typically execute two actions –A setup action To prepare the form for display –A submit action To process the form submission Both actions should be executed by the same Controller –They are two steps in a single cohesive workflow

7. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 7 Common Form Action Behaviors Form setup behaviors –Load the form model object –Load any supporting form “reference data” Form submit behaviors –Bind form input to the model –Perform model validation –Call an application layer service to persist edits

8. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 8 /reward/edit.jsp model={reward} Editing an Existing Reward - Setup Action RewardController handle GET /reward/edit.htm?id=1 1 RewardAdminService lookupReward(1) 2 reward

9. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 9 Editing an Existing Reward - Submit Action with a “Error” Result RewardController handle POST /reward/edit.htm {invalidInput} /reward/edit.jsp model={reward, errors} 1 Input Validation Failed

10. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 10 Editing an Existing Reward - Submit Action with a “Success” Result RewardController handle POST /reward/edit.htm {validInput} redirect:/reward/show.htm model={id} 1 RewardAdminService updateReward(reward) 2

11. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 11 Topics in this Session Form Workflow Primer Spring MVC Form Processing APIs –DataBinder –Validator –Form UI Tag Library SimpleFormController

12. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 12 Spring MVC Form Processing APIs Spring MVC provides several libraries to help implement common form action behaviors Libraries are included to –Automate the binding of request parameters to model objects –Implement form validation logic –Render form input controls such as text fields and select boxes

13. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 13 DataBinder Generic utility class for setting property values onto a target object –Useful for binding HTTP request parameters onto the form model object Key features –Type conversion –Error management

14. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 14 DataBinder Usage Example HttpServletRequest source = … RewardForm target = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(target); binder.bind(source); BindingResult result = binder.getBindingResult(); if (result.hasErrors()) { // do error processing } else { // do success processing } HttpServletRequest source = … RewardForm target = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(target); binder.bind(source); BindingResult result = binder.getBindingResult(); if (result.hasErrors()) { // do error processing } else { // do success processing } Copies source request parameters to target Returned BindingResult tracks bind errors

15. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 15 String creditCard String userName String reason Money amount Date date ChangeInfo changeInfo RewardForm rewardForm Data Binding Behavior creditCard=“1234123412341234” amount=“$50.00” date=“2006/12/29” changeInfo.userName=“colin” changeInfo.reason=“Correction” creditCard=“1234123412341234” amount=“$50.00” date=“2006/12/29” changeInfo.userName=“colin” changeInfo.reason=“Correction” Source Request Parameters Target RewardForm 12431234… $50.00 colin Correction 2006/12/29

16. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 16 Property Paths The name of the request parameter maps to a property path on the target Java Bean Map and indexed collection paths are also supported

17. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 17 Property Path Examples changeInfo.reason=“Correction” getChangeInfo().setReason(“Correction”); specialsMap[“spring”].discount=“.5”; getSpecialsMap().get(“spring”).setDiscount(“.5”); fileList[2].name=“readme.txt” getFileList().get(2).setName(“readme.txt”); customerMap[“bob”].addressList[0].city=“Oslo” getCustomerMap().get(“bob”).getAddressList().get(0). setCity(“Oslo”);

18. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 18 Useful Data Binder Configuration Options setRequiredFields(String[]) –Configures the properties that must be present for each binding attempt setAllowedFields(String[]) –Configures the only properties allowed for binding registerCustomEditor(Class, PropertyEditor) –Installs custom type converters setBindingErrorProcessor(BindingErrorProcessor) –Allows for control over how binding exceptions are handled

19. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 19 Bind Error Processing A Data Binder generates binding errors for –Missing required fields (“missingField”) –Type conversion failures (“typeMismatch”) Errors are resolvable to messages in a Spring MessageSource

20. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 20 Bind Error Processing Example RewardForm target = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(target, “rewardForm”); binder.setRequiredFields(new String[] { “creditCardNumber”, “amount”, “date” }); binder.registerCustomEditor(MonetaryAmount.class, new MonetaryAmountEditor()); RewardForm target = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(target, “rewardForm”); binder.setRequiredFields(new String[] { “creditCardNumber”, “amount”, “date” }); binder.registerCustomEditor(MonetaryAmount.class, new MonetaryAmountEditor()); class RewardForm { String creditCardNumber; MonetaryAmount amount; Date date; } class RewardForm { String creditCardNumber; MonetaryAmount amount; Date date; } All fields are required Will convert string values to MonetaryAmount objects

21. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 21 Missing Field Scenario ServletRequest DataBinder DefaultBinding ErrorProcessor DefaultBinding ErrorProcessor process MissingFieldError (“amount”, bindingResult) MessageCodes Resolver MessageCodes Resolver resolve MessageCodes( “missingField”, “rewardForm”, “amount”) errorMsgCodes FieldError new(”amount”, errorMsgCodes) addError(fieldError) bind(request) amount=null

22. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 22 Type Mismatch Scenario ServletRequest DataBinder DefaultBinding ErrorProcessor DefaultBinding ErrorProcessor process Property AccessException (exception, bindingResult) MessageCodes Resolver MessageCodes Resolver resolve MessageCodes( “typeMismatch”, “rewardForm”, “amount”) errorMsgCodes FieldError new(“amount”, errorMsgCodes, “bogus”) addError(fieldError) bind(request) amount=“bogus”

23. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 23 Error Message Codes Resolution DefaultMessage CodesResolver DefaultMessage CodesResolver resolveMessageCodes (“typeMismatch”, “rewardForm”, “amount”) new String[] { “typeMismatch.rewardForm.amount”, “typeMismatch.amount”, “typeMismatch” }

24. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 24 Error Message Resolution MessageSource getMessage(typeMismatch) typeMismatch.rewardForm.amount=Reward amount is of the wrong type typeMismatch.amount=The amount is of the wrong type typeMismatch=The type is wrong missingField=The field is required typeMismatch.rewardForm.amount=Reward amount is of the wrong type typeMismatch.amount=The amount is of the wrong type typeMismatch=The type is wrong missingField=The field is required errorMessages.properties_en “Reward amount is of the wrong type”

25. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 25 Validator Spring provides an API to perform form model validation –To exercise custom validation rules –To add errors on validation failures public interface Validator { void validate(Object target, Errors errors); }

26. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 26 Example Validator public class RewardFormValidator implements Validator { public boolean supports(Class clazz) { return RewardForm.class.isAssignableFrom(clazz); } public void validate(Object target, Errors errors) { RewardForm form = (RewardForm) target; String creditCardNumber = form.getCreditCardNumber(); if (!isNumeric(creditCardNumber)) { errors.rejectValue(“creditCardNumber”, “numeric”); } if (creditCardNumber.length() != 16) { errors.rejectValue(“creditCardNumber”, “length”, new Object[] { “16” }, “invalid creditCardNumber”); } } } FieldError code Error argumentDefault message

27. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 27 Pre-Built Validators Spring Validator integration is available for several popular validation frameworks Spring Modules is a good source for such extensions –http://springmodules.dev.java.net Available validation extensions include –Apache Commons Validator Support –Valang, a declarative validation language

28. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 28 Form Tag Library Spring MVC provides a tag library for form UI development Simplifies rendering of bound form controls –Text fields, select boxes, check boxes, etc Also capable of rendering form error messages –Resolves error messages using the configured MessageSource

29. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 29 Example JSP Form Tag Usage Credit Card Number: … Import form tag library The name of the backing “form object” Renders all errors associated with the target object Renders all errors associated with the “creditCardNumber” property Renders text field bound to the “creditCardNumber” property

30. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 30 Exposing the Form Model to your Form Views Form actions must expose a “form model” for the form tags to render bound form data –Contains the “form object” and any binding errors Spring’s SimpleFormController can handle this automatically Or you can use a DataBinder directly

31. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 31 Exposing the Form Model for the Initial Display of a Form View public class RewardController extends MultiActionController { public ModelAndView newForm(HttpServletRequest request, HttpServletResponse response) throws Exception { RewardForm form = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(form, “rewardForm”); binder.bind(request); ModelAndView result = new ModelAndView(“newReward”); result.addAllObjects(binder.getBindingResult().getModel()); return result; } public class RewardController extends MultiActionController { public ModelAndView newForm(HttpServletRequest request, HttpServletResponse response) throws Exception { RewardForm form = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(form, “rewardForm”); binder.bind(request); ModelAndView result = new ModelAndView(“newReward”); result.addAllObjects(binder.getBindingResult().getModel()); return result; } … Matches Exposes a form model

32. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 32 Exposing the Form Model after Binding and Validation public ModelAndView create(HttpServletRequest request, HttpServletResponse response) throws Exception { RewardForm form = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(form, “rewardForm”); binder.bind(request); BindingResult bindingResult = binder.getBindingResult(); ValidationUtils.invokeValidator(validator, form, bindingResult); Map model = bindingResult.getModel(); if (bindingResult.hasErrors()) { return new ModelAndView(“newReward”, model); } // we have valid input createNewReward(form); return new ModelAndView(“rewardCreated”, model); } public ModelAndView create(HttpServletRequest request, HttpServletResponse response) throws Exception { RewardForm form = new RewardForm(); ServletRequestDataBinder binder = new ServletRequestDataBinder(form, “rewardForm”); binder.bind(request); BindingResult bindingResult = binder.getBindingResult(); ValidationUtils.invokeValidator(validator, form, bindingResult); Map model = bindingResult.getModel(); if (bindingResult.hasErrors()) { return new ModelAndView(“newReward”, model); } // we have valid input createNewReward(form); return new ModelAndView(“rewardCreated”, model); } Prepares a form model Binds request parameters Redisplays form if errors occurred Validates form object

33. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 33 Available Form Tags

34. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 34 Topics in this Session Form Workflow Primer Spring MVC Form Processing APIs –DataBinder –Validator –Form UI Tag Library SimpleFormController

35. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 35 Implementing a Form Workflow Spring MVC provides the SimpleFormController as a base class for common form workflow MultiActionController may be used when more explicit control is needed Integration with Spring Web Flow is also available –Particularly suited for implementing wizards These classes make use of the data binding and validation building blocks previously discussed

36. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 36 Using SimpleFormController Extend SimpleFormController –Set properties in your constructor to configure it –Override hook methods as necessary to customize its workflow

37. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 37 Important SimpleFormController Properties setFormView(String) –Sets the view to render the form setSuccessView(String) –Sets the view to render after a successful form submit setCommandName(String) –Configures the name of the form model object referenced by the form view setCommandClass(Class) –Configures the form object class, for creating default instances to hold form values setValidator(Validator) –Configures the Validator to perform form validation

38. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 38 Important SimpleFormController Hooks formBackingObject(HttpServletRequest) – Returns the form object instance referenceData(HttpServletRequest) –Provides supporting data needed on the form initBinder(HttpServletRequest, ServletRequestDataBinder) –Configures the data binder used on setup and submit onSubmit(Object object) –Callback to persist edits of the “form backing object”

39. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 39 SimpleFormController Workflow request process form YES setup form NO isFormSubmission? protected boolean isFormSubmission(HttpServletRequest request) { return “POST”.equals(request.getMethod()); } protected boolean isFormSubmission(HttpServletRequest request) { return “POST”.equals(request.getMethod()); } Default implementation:

40. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 40 SimpleFormController: Setup Form GET request formBackingObject initBinder referenceData showForm create ‘commandClass’ instanceno-opreturn null (add nothing to model)display ‘formView’ Default implementations:

41. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. 41 SimpleFormController: Process Form POST request formBackingObject initBinder create ‘commandClass’ instance Default implementations: onBind onBindAndValidate binds validates hasErrors? showForm YES onSubmit NO no-op display ‘successView’

42. Copyright 2007 SpringSource. Copying, publishing or distributing without express written permission is prohibited. LAB Forms with Spring MVC