March 1, 2021
Hot Topics:

Spring Framework 3.0 and Annotation-driven Formatting

  • By Jim White
  • Send Email »
  • More Articles »

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: @NumberFormat and @DateTimeFormat. You can use @NumberFormat to format any numeric primitives or java.lang.Number instances (such as BigDecimal, BigInteger, Byte, Double, Float, Integer, Long, and Short). You can use @DateTimeFormat to format any java.util.Date, java.util.Calendar, 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 @NumberFormat or @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.

Adding the @NumberFormat and @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 Options

Annotation attributes affect how both the @NumberFormat and @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.

NumberFormat.Style Enums Default

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).

The @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.

@DateTimeFormat Style (using the same character for both date and time) String Example Output
Short form (SS is the default style) SS 8/30/64 11:24 AM
Medium form MM Aug 30, 1964 11:24:41 AM
Long form LL August 30, 1964 11:24:41 AM CDT
Full form FF Sunday, August 30, 1964 11:24:41 AM CDT
Use a dash to omit the date or time (omitting time in this example, with medium format for the date) M- Aug 30, 1964

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.

Page 1 of 2

This article was originally published on April 30, 2010

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date