setting up FormatterRegistrY

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@1800 50f2f4bb-b051-0410-bef5-90022cba6387

spring-framework-reference/src/validation.xml

@@ -951,7 +951,7 @@ public final class DateFormatter implements Formatter<Date> {
 			</programlisting>
 		</section>
 		<section id="ui-format-Formatted-Annotation">
-			<title>@Formatted Annotation</title>
+			<title>@Formatted</title>
 			<para>
 				The @Formatted annotation allows you to easily configure the Formatter implementation to use for one or more of your model classes.
 				To use this feature, simply annotate your class as @Formatted and specify the Formatter implementation to use as the annotation value:
@@ -1044,22 +1044,67 @@ public interface FormatterRegistry {
 		<section id="ui-format-configuring-FormatterRegistry">
 			<title>Configuring a FormatterRegistry</title>
 			<para>
+				A FormatterRegistry is a stateless object designed to be instantiated on application startup, then shared between multiple threads.
+				In a Spring MVC application, you configure a FormatterRegistry as a property of the WebBinderInitializer.
+				The FormatterRegistry will then be configured whenever a DataBinder is created by Spring MVC to bind model properties and render field values.
+				If no FormatterRegistry is configured, the original PropertyEditor-based system is used.
 			</para>
 			<para>
+				To register a FormatterRegistry with Spring MVC, simply configure it as a property of a custom WebBindingInitializer injected into the 
+				Spring MVC AnnotationMethodHandlerAdapter.
 			</para>
-			<programlisting language="java"><![CDATA[
+			<programlisting language="xml"><![CDATA[
-]]>
+<!-- Invokes Spring MVC @Controller methods -->
+<bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
+    <property name="webBindingInitializer">
+        <!-- Configures Spring MVC DataBinder instances -->
+        <bean class="org.springframework.web.bind.support.ConfigurableWebBindingInitializer">
+            <property name="formatterRegistry">
+                <bean class="org.springframework.ui.format.GenericFormatterRegistry">
+                    <property name="formatters">
+                        <list>
+	                        <!-- Register formatter beans here -->
+                        </list>	
+                    </property>
+                    <property name="annotationFormatterFactories">
+                        <list>
+	                        <!-- Register any AnnotationFormatterFactory beans here -->
+                        </list>	
+                    </property>
+                </bean>
+            </property>
+        </bean>
+    </property>
+</bean>]]>
 			</programlisting>
+			<para>
+				See the JavaDocs for GenericFormatterRegistry for more configuration options.
+			</para>
 		</section>
-		<section id="ui-format-customizing-DataBinder">
+		<section id="ui-format-registering-field-specific-Formatters">
 			<title>Registering field-specific Formatters</title>
 			<para>
+				In most cases, configuring a shared FormatterRegistry that selects Formatters based on model property type or annotation is sufficient.
+				When sufficient, special @Controller @InitBinder callbacks are NOT needed to apply custom formatting logic.
+				However, there are cases where field-specific formatting should be configured on a Controller-by-Controller basis.
+				For example, you may need to format a specific Date field in a way that differs from all the other Date fields in your application.
 			</para>
 			<para>
+				To apply a Formatter to a single field, create an @InitBinder callback on your @Controller, then call binder.registerFormatter(String, Formatter<?>):
 			</para>
 			<programlisting language="java"><![CDATA[
+    public class MyControler {
+        @InitBinder
+        public void initBinder(WebDataBinder binder) {
+            binder.registerFormatter("myfieldName", new MyCustomFieldFormatter());
+        }
+        ...
+    }
 ]]>
 			</programlisting>
+			<para>
+				This applies the Formatter to the specific field, overriding any Formatter that would have been applied by type or annotation.
+			</para>
 		</section>
 	</section>