Spring Framework 3.0 and Annotation-driven Formatting
Spring Framework 3.0 was released in late 2009 with many new and powerful features. While additions such as Spring Expression Language (SpEL), support for RESTful Web services, and the expansion of stereotype and annotated-based components get the lion's share of attention, not all the new features are as major. Some of the real convenience features take very little time to learn and you can incorporate them in your applications in no time. In this article, I introduce you to one such Spring 3 feature: annotation-driven formatting.
Introducing Formatting Annotations
Spring 3 offers two new annotations that you can use to format numbers, date, and time bean properties and method parameters:
@DateTimeFormat. You can use
@NumberFormat to format any numeric primitives or
java.lang.Number instances (such as
Short). You can use
@DateTimeFormat to format any
java.util.Long (representing a date/time in milliseconds since the epoch January 1, 1970, 00:00:00 GMT), or Joda Time field/parameter. Joda Time is an open source package that provides a "quality replacement for the Java date and time classes."
To specify the formatting of any numeric or date/time property in your Spring bean class, simply add
@DateTimeFormat to it. Take, for example, the Employee class in Listing 1. It is a simple unannotated POJO (plain old java object), the type often used as a command bean to collect and display data in HTML forms.
When used as a command bean to populate a form (using Spring Form tags), by default the form would display the data shown in Figure 1.
Figure 1. HTML Form Without Use of Formatting Annotations: When you use an unannotated Employee command bean, Spring uses its default formatting to populate the HTML form (using Spring Form tags), resulting in less than appealing form entry.
Not very pretty, is it? Prior to the formatting annotations, developers would need to develop special getters/setters and/or use PropertyEditors to make the display of numeric and data/time properties more usable.
@DateTimeFormat formatting annotations (both from the
org.springframework.format.annotation package) to the Employee class as demonstrated in Listing 2, causes the display to change dramatically (see Figure 2). Now, no special getters/setters or editors are necessary to get this type of data to display as users might expect.
Figure 2. HTML Form Displaying Numeric and Date/Time Information with Formatting: Using the formatting annotated Employee class, the same HTML form can be used to capture and display data in a more expected format.
Annotation attributes affect how both the
@DateTimeFormat annotations work. The
@NumberFormat annotation has two optional attributes: style and pattern. The style attribute allows you to select from one of three
org.springframework.format.annotation.NumberFormat.Style enums. The table below outlines the three choices and an example of each is used in the Employee class shown in Listing 2.
The style abides by the current locale. So, for example, a double field annotated with
@NumberFormat(style = Style.CURRENCY) displays with a proceeding
$ character in the en-us locale, but would probably be proceeded by a
for the fr-fr locale.
Use the pattern attribute to specify a custom pattern for numbers. The pattern follows Java's standard numeric formatting patterns. By default, an empty string defines the pattern (suggesting no pattern is to be applied).
@DateTimeFormat annotation also has optional attributes: style, pattern and iso. The style attribute allows you to provide a two-character string that dictates how the date and time should be formatted. The first character dictates the date formatting, and the second dictates time formatting. The table below provides a listing of the options and shows you example output.
|Short form (SS is the default style)||
|Use a dash to omit the date or time (omitting time in this example, with medium format for the date)||
The pattern attribute allows you to use a custom date/time pattern string to format the date and/or time. The pattern string follows the Java standard date/time formatting. Again, by default, the pattern string is empty. No formatting occurs when the pattern is an empty string.
Lastly, use the iso attribute with one of four
org.springframework.format.annotation.DateTimeFormat.ISO enums to format the field by the ISO standard date/time format patterns. The table below shows the ISO enum options and example output.