0
# Formatting
1

2
Type conversion and formatting providing comprehensive support for converting between objects and their string representations. This includes Formatter interfaces, @DateTimeFormat and @NumberFormat annotations, and conversion services for web binding and data presentation.
3

4
## Capabilities
5

6
### Formatter Interfaces
7

8
```java { .api }
9
/**
10
 * Formats objects of type T for display.
11
 */
12
public interface Formatter<T> extends Printer<T>, Parser<T> {
13
    /**
14
     * Print the object of type T for display.
15
     * @param object the instance to print
16
     * @param locale the current user locale
17
     * @return the printed text string
18
     */
19
    String print(T object, Locale locale);
20
    
21
    /**
22
     * Parse a text String to produce an instance of T.
23
     * @param text the text string
24
     * @param locale the current user locale
25
     * @return an instance of T
26
     * @throws ParseException when a parse exception occurs
27
     * @throws IllegalArgumentException when a parse exception occurs
28
     */
29
    T parse(String text, Locale locale) throws ParseException;
30
}
31

32
/**
33
 * Prints objects of type T for display.
34
 */
35
public interface Printer<T> {
36
    /**
37
     * Print the object of type T for display.
38
     * @param object the instance to print
39
     * @param locale the current user locale
40
     * @return the printed text string
41
     */
42
    String print(T object, Locale locale);
43
}
44

45
/**
46
 * Parses text strings to produce instances of T.
47
 */
48
public interface Parser<T> {
49
    /**
50
     * Parse a text String to produce an instance of T.
51
     * @param text the text string
52
     * @param locale the current user locale
53
     * @return an instance of T
54
     * @throws ParseException when a parse exception occurs
55
     * @throws IllegalArgumentException when a parse exception occurs
56
     */
57
    T parse(String text, Locale locale) throws ParseException;
58
}
59
```
60

61
### Formatting Annotations
62

63
```java { .api }
64
/**
65
 * Declares that a field or method parameter should be formatted as a date or time.
66
 */
67
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
68
@Retention(RetentionPolicy.RUNTIME)
69
public @interface DateTimeFormat {
70
    /**
71
     * The style pattern to use to format the field.
72
     * @return the format style
73
     */
74
    String style() default "SS";
75
    
76
    /**
77
     * The ISO pattern to use to format the field.
78
     * @return the ISO format
79
     */
80
    ISO iso() default ISO.NONE;
81
    
82
    /**
83
     * The custom pattern to use to format the field.
84
     * @return the custom pattern
85
     */
86
    String pattern() default "";
87
    
88
    /**
89
     * The fallback patterns to use when parsing.
90
     * @return the fallback patterns
91
     */
92
    String[] fallbackPatterns() default {};
93
    
94
    /**
95
     * Common ISO date time format patterns.
96
     */
97
    enum ISO {
98
        /** The most common ISO Date Format (yyyy-MM-dd) */
99
        DATE,
100
        /** The most common ISO Time Format (HH:mm:ss.SSSXXX) */
101
        TIME,
102
        /** The most common ISO Date Time Format (yyyy-MM-dd'T'HH:mm:ss.SSSXXX) */
103
        DATE_TIME,
104
        /** Indicates that no ISO-based format pattern should be applied */
105
        NONE
106
    }
107
}
108

109
/**
110
 * Declares that a field should be formatted as a number.
111
 */
112
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
113
@Retention(RetentionPolicy.RUNTIME)
114
public @interface NumberFormat {
115
    /**
116
     * The style to use to format the field.
117
     * @return the number style
118
     */
119
    Style style() default Style.DEFAULT;
120
    
121
    /**
122
     * The custom pattern to use to format the field.
123
     * @return the custom pattern
124
     */
125
    String pattern() default "";
126
    
127
    /**
128
     * Common number format styles.
129
     */
130
    enum Style {
131
        /** The default format for the annotated type */
132
        DEFAULT,
133
        /** The general-purpose number format for the current locale */
134
        NUMBER,
135
        /** The integer number format for the current locale */
136
        INTEGER,
137
        /** The percent format for the current locale */
138
        PERCENT,
139
        /** The currency format for the current locale */
140
        CURRENCY
141
    }
142
}
143
```
144

145
### FormattingConversionService
146

147
```java { .api }
148
/**
149
 * A ConversionService implementation designed to be configured as a FormatterRegistry.
150
 */
151
public class FormattingConversionService extends GenericConversionService implements FormatterRegistry, EmbeddedValueResolverAware {
152
    /**
153
     * Create a new FormattingConversionService with default formatters.
154
     */
155
    public FormattingConversionService() {}
156
    
157
    /**
158
     * Set the StringValueResolver to use for resolving embedded definition values.
159
     * @param embeddedValueResolver the embedded value resolver
160
     */
161
    public void setEmbeddedValueResolver(StringValueResolver embeddedValueResolver) {}
162
    
163
    /**
164
     * Add a Printer to print instances of a particular type.
165
     * @param printer the printer to add
166
     */
167
    public void addPrinter(Printer<?> printer) {}
168
    
169
    /**
170
     * Add a Parser to parse instances of a particular type from a String.
171
     * @param parser the parser to add
172
     */
173
    public void addParser(Parser<?> parser) {}
174
    
175
    /**
176
     * Add a Formatter to format instances of a particular type.
177
     * @param formatter the formatter to add
178
     */
179
    public void addFormatter(Formatter<?> formatter) {}
180
    
181
    /**
182
     * Add a Formatter to format instances of a particular type.
183
     * @param fieldType the field type to format
184
     * @param formatter the formatter to add
185
     */
186
    public void addFormatterForFieldType(Class<?> fieldType, Formatter<?> formatter) {}
187
    
188
    /**
189
     * Add a Printer/Parser pair to format instances of a particular type.
190
     * @param fieldType the field type to format
191
     * @param printer the printer
192
     * @param parser the parser
193
     */
194
    public void addFormatterForFieldType(Class<?> fieldType, Printer<?> printer, Parser<?> parser) {}
195
    
196
    /**
197
     * Add a AnnotationFormatterFactory that configures Formatters from a particular Annotation.
198
     * @param annotationFormatterFactory the annotation formatter factory to add
199
     */
200
    public void addFormatterForFieldAnnotation(AnnotationFormatterFactory<? extends Annotation> annotationFormatterFactory) {}
201
}
202

203
/**
204
 * A FormattingConversionService configured with formatters appropriate for most applications.
205
 */
206
public class DefaultFormattingConversionService extends FormattingConversionService {
207
    /**
208
     * Create a new DefaultFormattingConversionService with the set of default formatters.
209
     */
210
    public DefaultFormattingConversionService() {}
211
    
212
    /**
213
     * Add default formatters to the specified FormatterRegistry.
214
     * @param formatterRegistry the FormatterRegistry to add to
215
     */
216
    public static void addDefaultFormatters(FormatterRegistry formatterRegistry) {}
217
}
218
```
219

220
### Usage Examples
221

222
**Basic Formatting:**
223

224
```java
225
@Entity
226
public class Event {
227
    @DateTimeFormat(pattern = "yyyy-MM-dd")
228
    private LocalDate eventDate;
229
    
230
    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
231
    private LocalDateTime createdAt;
232
    
233
    @NumberFormat(style = NumberFormat.Style.CURRENCY)
234
    private BigDecimal price;
235
    
236
    @NumberFormat(pattern = "#,##0.00")
237
    private Double rating;
238
    
239
    // Getters and setters
240
}
241
```