diff --git a/src/asciidoc/core-validation.adoc b/src/asciidoc/core-validation.adoc index 2bf93b8a09..8d873680cc 100644 --- a/src/asciidoc/core-validation.adoc +++ b/src/asciidoc/core-validation.adoc @@ -957,7 +957,7 @@ either of the Converter, ConverterFactory, or GenericConverter interfaces. ---- It is also common to use a ConversionService within a Spring MVC application. See -<> for details on use with ``. +<> in the Spring MVC chapter. In certain situations you may wish to apply formatting during conversion. See <> for details on using @@ -1308,85 +1308,8 @@ converter and formatter registration. [[format-configuring-formatting-mvc]] === Configuring Formatting in Spring MVC -In a Spring MVC application, you may configure a custom ConversionService instance -explicitly as an attribute of the `annotation-driven` element of the MVC namespace. This -ConversionService will then be used anytime a type conversion is required during -Controller model binding. If not configured explicitly, Spring MVC will automatically -register default formatters and converters for common types such as numbers and dates. -To rely on default formatting rules, no custom configuration is required in your Spring -MVC config XML: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - ----- - -With this one-line of configuration, default formatters for Numbers and Date types will -be installed, including support for the @NumberFormat and @DateTimeFormat annotations. -Full support for the Joda Time formatting library is also installed if Joda Time is -present on the classpath. - -To inject a ConversionService instance with custom formatters and converters registered, -set the conversion-service attribute and then specify custom converters, formatters, or -FormatterRegistrars as properties of the FormattingConversionServiceFactoryBean: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - - - - - - - - - - - - - - - - - - - ----- - -[NOTE] -==== -See <> and the `FormattingConversionServiceFactoryBean` -for more information on when to use FormatterRegistrars. -==== +See <> in the Spring MVC chapter. @@ -1479,7 +1402,7 @@ If you are using Spring MVC remember to explicitly configure the conversion serv is used. For Java based `@Configuration` this means extending the `WebMvcConfigurationSupport` class and overriding the `mvcConversionService()` method. For XML you should use the `'conversion-service'` attribute of the -`mvc:annotation-driven` element. See <> for details. +`mvc:annotation-driven` element. See <> for details. @@ -1707,131 +1630,6 @@ locally on a DataBinder instance. See <>. [[validation-mvc]] === Spring MVC 3 Validation -Beginning with Spring 3, Spring MVC has the ability to automatically validate -`@Controller` inputs. In previous versions it was up to the developer to manually invoke -validation logic. - -[[validation-mvc-triggering]] -==== Triggering @Controller Input Validation -To trigger validation of a `@Controller` input, simply annotate the input argument as -++@Valid++: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - @Controller - public class MyController { - - @RequestMapping(path="/foo", method=RequestMethod.POST) - public void processFoo(**@Valid** Foo foo) { /* ... */ } ----- - -Spring MVC will validate a @Valid object after binding so-long as an appropriate -Validator has been configured. - -[NOTE] -==== -The @Valid annotation is part of the standard JSR-303 Bean Validation API, and is not a -Spring-specific construct. -==== - - -[[validation-mvc-configuring]] -==== Configuring a Validator for use by Spring MVC -The `Validator` instance invoked when a `@Valid` method argument is encountered may be -configured in two ways. First, you may call `binder.setValidator(Validator)` within a -++@Controller++'s `@InitBinder` callback. This allows you to configure a `Validator` -instance per `@Controller` class: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - @Controller - public class MyController { - - @InitBinder - protected void initBinder(WebDataBinder binder) { - binder.setValidator(new FooValidator()); - } - - @RequestMapping(path="/foo", method=RequestMethod.POST) - public void processFoo(@Valid Foo foo) { ... } - - } ----- - -Second, you may call `setValidator(Validator)` on the global `WebBindingInitializer`. This -allows you to configure a `Validator` instance across all `@Controller` classes. This can be -achieved easily by using the Spring MVC namespace: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - ----- - -To combine a global and a local validator, configure the global validator as shown above -and then add a local validator: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - @Controller - public class MyController { - - @InitBinder - protected void initBinder(WebDataBinder binder) { - binder.addValidators(new FooValidator()); - } - - } ----- - - -[[validation-mvc-jsr303]] -==== Configuring a JSR-303/JSR-349 Validator for use by Spring MVC -With Bean Validation, a single `javax.validation.Validator` instance typically validates -__all__ model objects that declare validation constraints. To configure such a JSR-303 -backed Validator with Spring MVC, simply add a Bean Validation provider, such as -Hibernate Validator, to your classpath. Spring MVC will detect it and automatically -enable Bean Validation support across all Controllers. - -The Spring MVC configuration required to enable Bean Validation support is shown below: - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - - ----- - -With this minimal configuration, anytime a `@Valid` `@Controller` input is encountered, it -will be validated by the Bean Validation provider. That provider, in turn, will enforce -any constraints declared against the input. Any ++ConstraintViolation++s will automatically -be exposed as errors in the `BindingResult` renderable by standard Spring MVC form tags. +See <> in the Spring MVC chapter. diff --git a/src/asciidoc/web-mvc.adoc b/src/asciidoc/web-mvc.adoc index 6a1792c7b5..54b495982e 100644 --- a/src/asciidoc/web-mvc.adoc +++ b/src/asciidoc/web-mvc.adoc @@ -4567,10 +4567,34 @@ the classpath. === Customizing the Provided Configuration To customize the default configuration in Java you simply implement the `WebMvcConfigurer` interface or more likely extend the class `WebMvcConfigurerAdapter` -and override the methods you need. Below is an example of some of the available methods -to override. See -{javadoc-baseurl}/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.html[`WebMvcConfigurer`] -for a list of all methods and the javadocs for further details: +and override the methods you need: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + @Configuration + @EnableWebMvc + public class WebConfig extends WebMvcConfigurerAdapter { + + // Override configuration methods... + + } +---- + +To customize the default configuration of `` check what +attributes and sub-elements it supports. You can view the +http://schema.spring.io/mvc/spring-mvc.xsd[Spring MVC XML schema] or use the code +completion feature of your IDE to discover what attributes and sub-elements are +available. + + +[[mvc-config-conversion]] +=== Conversion and Formatting + +By default formatters for Numbers and Date types are installed, including support for the @NumberFormat +and @DateTimeFormat annotations. Full support for the Joda Time formatting library is also installed +if Joda Time is present on the classpath. To register custom formatters and converters override +the `addFormatters` method: [source,java,indent=0] [subs="verbatim,quotes"] @@ -4580,44 +4604,136 @@ for a list of all methods and the javadocs for further details: public class WebConfig extends WebMvcConfigurerAdapter { @Override - protected void addFormatters(FormatterRegistry registry) { + public void addFormatters(FormatterRegistry registry) { // Add formatters and/or converters } - @Override - public void configureMessageConverters(List> converters) { - // Configure the list of HttpMessageConverters to use - } - } ---- -To customize the default configuration of `` check what -attributes and sub-elements it supports. You can view the -http://schema.spring.io/mvc/spring-mvc.xsd[Spring MVC XML schema] or use the code -completion feature of your IDE to discover what attributes and sub-elements are -available. The sample below shows a subset of what is available: +In the MVC namespace the same defaults apply when `` is added. +To register custom formatters and converters simply supply a `ConversionService`: [source,xml,indent=0] [subs="verbatim,quotes"] ---- - - - - - - + + - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + ---- +[NOTE] +==== +See <> and the `FormattingConversionServiceFactoryBean` +for more information on when to use FormatterRegistrars. +==== + +[[mvc-config-validation]] +=== Validation + +Spring provides a <> that can be used for validation in all layers +of an application. In Spring MVC you can configure it for use as a global `Validator` instance, to be used +whenever an `@Valid` or `@Validated` controller method argument is encountered, and/or as a local +`Validator` within a controller through an `@InitBinder` method. Global and local validator +instances can be combined to provide composite validation. + +Spring also <> Bean Validation +via `LocalValidatorFactoryBean` which adapts the Spring `org.springframework.validation.Validator` +interface to the Bean Validation `javax.validation.Validator` contract. This class can be +plugged into Spring MVC as a global validator as described next. + +By default use of `@EnableWebMvc` or `` automatically registers Bean +Validation support in Spring MVC through the `LocalValidatorFactoryBean` when a Bean Validation +provider is such as Hibernate Validator is detected on the classpath. + +Alternatively you can configure your own global `Validator` instance: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + @Configuration + @EnableWebMvc + public class WebConfig extends WebMvcConfigurerAdapter { + + @Override + public Validator getValidator(); { + // return "global" validator + } + + } +---- + +and in XML: + +[source,xml,indent=0] +[subs="verbatim,quotes"] +---- + + + + + + +---- + +To combine global with local validation, simply add one or more local validator(s): + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + @Controller + public class MyController { + + @InitBinder + protected void initBinder(WebDataBinder binder) { + binder.addValidators(new FooValidator()); + } + + } +---- + +With this minimal configuration anytime an `@Valid` or `@Validated` method argument is encountered, it +will be validated by the configured validators. Any validation violations will automatically +be exposed as errors in the `BindingResult` accessible as a method argument and also renderable +in Spring MVC HTML views. + [[mvc-config-interceptors]]