diff --git a/spring-framework-reference/src/validation.xml b/spring-framework-reference/src/validation.xml index 2df540a1fd5..938df2038cd 100644 --- a/spring-framework-reference/src/validation.xml +++ b/spring-framework-reference/src/validation.xml @@ -922,11 +922,11 @@ public class MyService { Now consider the type conversion requirements of a typical client environment such as a web or desktop application. In such environments, you typically convert from String to support the client postback process, as well as back to String to support the view rendering process. The more general core.convert Converter SPI does not address this scenario directly. - To directly address this, Spring 3 introduces a conveient format SPI that provides a simple and robust alternative to PropertyEditors for client environments. + To directly address this, Spring 3 introduces a convenient format SPI that provides a simple and robust alternative to PropertyEditors for client environments. In general, use the Converter SPI when you need to implement general-purpose type conversion logic. - Use Formatters when you're working in a client environment, such as a web application, and need to apply String parsing, printing, and localization logic to form field values. + Use Formatters when you're working in a client environment, such as a web application, and need to parse and print localized field values.
Formatter SPI @@ -934,6 +934,15 @@ public class MyService { The org.springframework.format SPI to implement field formatting logic is simple and strongly typed: extends Printer, Parser { +}]]> + + + Where Formatter extends from the Printer and Parser building-block interfaces: + + { String print(T fieldValue, Locale locale); }]]> @@ -943,24 +952,20 @@ import java.text.ParseException; public interface Parser { T parse(String clientValue, Locale locale) throws ParseException; -}]]> - - extends Printer, Parser { }]]> To create your own Formatter, simply implement the Formatter interface above. - Parameterize T to be the type of object you are formatting, for example, java.util.Date. + Parameterize T to be the type of object you wish to format, for example, java.util.Date. Implement the print operation to print an instance of T for display in the client locale. Implement the parse operation to parse an instance of T from the formatted representation returned from the client locale. Your Formatter should throw a ParseException or IllegalArgumentException if a parse attempt fails. Take care to ensure your Formatter implementation is thread-safe. - Several Formatter implementations are provided in formatsubpackages as a convenience. - The datetime package provides a DateFormatter to format java.util.Date objects with a java.text.DateFormat. + Several Formatter implementations are provided in format subpackages as a convenience. The number package provides a NumberFormatter, CurrencyFormatter, and PercentFormatter to format java.lang.Number objects using a java.text.NumberFormat. + The datetime package provides a DateFormatter to format java.util.Date objects with a java.text.DateFormat. The datetime.joda package provides comprehensive datetime formatting support based on the Joda Time library. @@ -1003,10 +1008,10 @@ public final class DateFormatter implements Formatter {
- Custom Format Annotations + Annotation-driven Formatting - Field formatting can be triggered by annotating model properties. - To bind a custom annotation to a Formatter instance, implement AnnotationFormatterFactory: + Field formatting can be triggered by field type or annotation. + To bind an annotation to a formatter, implement AnnotationFormatterFactory: { Implement the getFieldTypes operation return the types of fields the annotation may be used on. Implement the getPrinter operation to return the Printer to print the value of an annotated field. Implement the getParser operation to return the Parser to parse the value of an annotated field. - Take care to ensure your AnnotationFormatterFactory implementation is thread-safe. - The example implementation below binds a @NumberFormat instance to a Formatter instance. - This particular annotation allows the NumberFormat style or pattern to be specified: + The example AnnotationFormatterFactory implementation below binds a @NumberFormat Annotation to a formatter. + This annotation allows a number style or pattern to be specified: { - public Set> getFieldTypes() { - Set> fieldTypes = new HashSet>(7); - fieldTypes.add(Short.class); - fieldTypes.add(Integer.class); - fieldTypes.add(Long.class); - fieldTypes.add(Float.class); - fieldTypes.add(Double.class); - fieldTypes.add(BigDecimal.class); - fieldTypes.add(BigInteger.class); - return fieldTypes; - } + public Set> getFieldTypes() { + return new HashSet>(asList(new Class[] { + Short.class, Integer.class, Long.class, Float.class, Double.class, BigDecimal.class, BigInteger.class })); + } + + public Printer getPrinter(NumberFormat annotation, Class fieldType) { + return configureFormatterFrom(annotation, fieldType); + } + + public Parser getParser(NumberFormat annotation, Class fieldType) { + return configureFormatterFrom(annotation, fieldType); + } - public Printer getPrinter(NumberFormat annotation, Class fieldType) { - return configureFormatterFrom(annotation, fieldType); - } - - public Parser getParser(NumberFormat annotation, Class fieldType) { - return configureFormatterFrom(annotation, fieldType); - } - - private Formatter configureFormatterFrom(NumberFormat annotation, Class fieldType) { - if (!annotation.pattern().isEmpty()) { - return new NumberFormatter(annotation.pattern()); - } else { - Style style = annotation.style(); - if (style == Style.PERCENT) { - return new PercentFormatter(); - } else if (style == Style.CURRENCY) { - return new CurrencyFormatter(); - } else { - return new NumberFormatter(); - } - } - } + private Formatter configureFormatterFrom(NumberFormat annotation, Class fieldType) { + if (!annotation.pattern().isEmpty()) { + return new NumberFormatter(annotation.pattern()); + } else { + Style style = annotation.style(); + if (style == Style.PERCENT) { + return new PercentFormatter(); + } else if (style == Style.CURRENCY) { + return new CurrencyFormatter(); + } else { + return new NumberFormatter(); + } + } + } }]]> - Then, to trigger formatting, simply annotate a property with @NumberFormat in your model: + Then, to trigger formatting, annotate fields with @NumberFormat: - - A format annotation API exists in the org.springframework.format.annotation package. - Use the NumberFormat annotation to apply formatting to java.lang.Number fields. - Use the DateTimeFormat annotation to apply formatting to java.util.Date, java.util.Calendar, java.util.Long, or Joda Time fields. - - - The example below shows use of the DateTimeFormat annotation to format a java.util.Date as a ISO Date (yyyy-MM-dd): - - + Format Annotation API + + A portable format annotation API exists in the org.springframework.format.annotation package. + Use the @NumberFormat to apply formatting to java.lang.Number fields. + Use the @DateTimeFormat to apply formatting to java.util.Date, java.util.Calendar, java.util.Long, or Joda Time fields. + + + The example below shows use of the DateTimeFormat annotation to format a java.util.Date as a ISO Date (yyyy-MM-dd): + + - + +
FormatterRegistry SPI - When installed, Formatters are registered in a FormatterRegistry. + At runtime, Formatters are registered in a FormatterRegistry. A FormatterRegistry allows you to configure Formatting rules centrally, instead of duplicating such configuration across your Controllers. For example, you might want to enforce that all Date fields are formatted a certain way, or fields with a specific annotation are formatted in a certain way. With a shared FormatterRegistry, you define these rules once and they are applied whenever formatting is needed. @@ -1134,10 +1134,10 @@ public interface FormatterRegistry { In a Spring MVC application, you can configure a ConversionService instance explicity as an attribute of the annotation-driven element of the MVC namespace. This ConversionService will then be used any time type conversion is needed during Controller model binding. - If not configured explicitly, Spring MVC will configure a FormattingConversionService instance that registers default formatters for number and date types. + If not configured explicitly, Spring MVC will automatically register default formatters for common types such as numbers and dates. - To rely on default formatting rules, no explicit configuration is required in your Spring MVC config XML: + To rely on default formatting rules, no custom configuration is required in your Spring MVC config XML: @@ -1154,7 +1154,7 @@ public interface FormatterRegistry { With this one-line of configuation, default formatters for Numbers and Date types will be installed, including support for the @NumberFormat and @DateTimeFormat annotations. - This also includes full support for the Joda Time formatting library if Joda Time is present on the classpath. + 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/converters registered, set the conversion-service attribute: