Spring 格式化注解

在2009年，Spring Framework 3.0发布了，带来了很多新的功能强大的特性。 除了支持RESTful Web service的Spring Expression Language（SpEL）等主要功能外，还有一些很方便的，而且不需要太多时间学习的新的特性。这里我们介绍其中的一个：用于格式化的注解。
简介

Spring 3 提供了两个可以用于格式化数字、日期和时间的注解@NumberFormat和@DateTimeFormat，这两个标签可以用于bean的属性或方法参数上。@NumberFormat可以用来格式化任何的数字的基本类型（如int，long）或java.lang.Number的实例（如 BigDecimal, Integer)。@DateTimeFormat可以用来格式化java.util.Date、java.util.Calendar和 java.util.Long类型，也可以用于Joda Time类型的字段或参数。（Joda Time是一个开源的包，提供了对date和time类的一些替代类）。

要指定数字或日期/时间类型的属性，只需要在其上添加 @NumberFormat或@DateTimeFormat注解接可以了。例如下面的代码：

1. import java.math.BigDecimal;
   
2. import java.util.Calendar;
   
3. import java.util.Date;
   
4. 
   
5. import org.joda.time.LocalTime;
   
6. 
   
7. public class Employee {
   
8. 
   
9. private String name;
   
10. 
    
11. private double salary;
    
12. private double w4AdditionalWithdraw;
    
13. private int dependents;
    
14. private BigDecimal visualAcuity;
    
15. 
    
16. private Date birthDate;
    
17. private Calendar hireDate;
    
18. private LocalTime startTime;
    
19. private long lastTimeEntry;
    
20. 
    
21. /**
    
22. * initialization block to provide sample data for display
    
23. */
    
24. {
    
25. this.name = "John Doe";
    
26. this.salary = 30100.50;
    
27. this.w4AdditionalWithdraw = 0.02;
    
28. this.dependents = 5;
    
29. this.visualAcuity = new BigDecimal(".1");
    
30. 
    
31. Calendar dob = Calendar.getInstance();
    
32. dob.set(1964, Calendar.AUGUST, 30);
    
33. this.birthDate = dob.getTime();
    
34. this.hireDate = Calendar.getInstance();
    
35. this.startTime = new LocalTime(8, 0);
    
36. this.lastTimeEntry = (new Date()).getTime() - 10000;
    
37. }
    
38. 
    
39. public String getName() {
    
40. return name;
    
41. }
    
42. 
    
43. public void setName(String name) {
    
44. this.name = name;
    
45. }
    
46. 
    
47. public double getSalary() {
    
48. return salary;
    
49. }
    
50. 
    
51. public void setSalary(double salary) {
    
52. this.salary = salary;
    
53. }
    
54. 
    
55. public double getW4AdditionalWithdraw() {
    
56. return w4AdditionalWithdraw;
    
57. }
    
58. 
    
59. public void setW4AdditionalWithdraw(double w4AdditionalWithdraw) {
    
60. this.w4AdditionalWithdraw = w4AdditionalWithdraw;
    
61. }
    
62. 
    
63. public int getDependents() {
    
64. return dependents;
    
65. }
    
66. 
    
67. public void setDependents(int dependents) {
    
68. this.dependents = dependents;
    
69. }
    
70. 
    
71. public BigDecimal getVisualAcuity() {
    
72. return visualAcuity;
    
73. }
    
74. 
    
75. public void setVisualAcuity(BigDecimal visualAcuity) {
    
76. this.visualAcuity = visualAcuity;
    
77. }
    
78. 
    
79. public Date getBirthDate() {
    
80. return birthDate;
    
81. }
    
82. 
    
83. public void setBirthDate(Date birthDate) {
    
84. this.birthDate = birthDate;
    
85. }
    
86. 
    
87. public LocalTime getStartTime() {
    
88. return startTime;
    
89. }
    
90. 
    
91. public void setStartTime(LocalTime startTime) {
    
92. this.startTime = startTime;
    
93. }
    
94. 
    
95. public Calendar getHireDate() {
    
96. return hireDate;
    
97. }
    
98. 
    
99. public void setHireDate(Calendar hireDate) {
    
100. this.hireDate = hireDate;
     
101. }
     
102. 
     
103. public long getLastTimeEntry() {
     
104. return lastTimeEntry;
     
105. }
     
106. 
     
107. public void setLastTimeEntry(long lastTimeEntry) {
     
108. this.lastTimeEntry = lastTimeEntry;
     
109. }
     
110. 
     
111. }

复制代码

这段代码中我们没有添加注解。如果我们使用Spring 份额Form 标签将这个bean中的数据用于显示的时候，我们会得到类似下图的结果：
 

可以看到，所有的数据都是以默认的格式显示的，Spring会使用默认的格式将数据显示在HTML表格中（其他的框架也大多如此）。如果想显示特殊的格式，开发人员必须编写特殊的getter/setter方法或使用PropertyEditors来显示特殊格式的数字或者日期/时间。
现在有了 @NumberFormat和@DateTimeFormat注解，我们可以使用这两个注解来完成同样的功能。如下面的代码所示：

1. import java.math.BigDecimal;
   
2. import java.util.Calendar;
   
3. import java.util.Date;
   
4. 
   
5. import org.joda.time.LocalTime;
   
6. import org.springframework.format.annotation.DateTimeFormat;
   
7. import org.springframework.format.annotation.NumberFormat;
   
8. import org.springframework.format.annotation.DateTimeFormat.ISO;
   
9. import org.springframework.format.annotation.NumberFormat.Style;
   
10. 
    
11. public class Employee {
    
12. 
    
13. private String name;
    
14. 
    
15. /**
    
16. * numeric fields using @NumberFormat annotation for formatting.
    
17. */
    
18. @NumberFormat(style = Style.CURRENCY)
    
19. private double salary;
    
20. @NumberFormat(style = Style.PERCENT)
    
21. private double w4AdditionalWithdraw;
    
22. @NumberFormat
    
23. private int dependents;
    
24. @NumberFormat(pattern = "0.00")
    
25. private BigDecimal visualAcuity;
    
26. 
    
27. /**
    
28. * date and time fields using @DateTimeFormat annotation for formatting.
    
29. */
    
30. @DateTimeFormat(style = "M-")
    
31. private Date birthDate;
    
32. @DateTimeFormat(pattern = "w:yyyy")
    
33. private Calendar hireDate;
    
34. @DateTimeFormat(style = "-S")
    
35. private LocalTime startTime;
    
36. @DateTimeFormat(iso = ISO.DATE_TIME)
    
37. private long lastTimeEntry;
    
38. 
    
39. /**
    
40. * initialization block to provide sample data for display
    
41. */
    
42. {
    
43. this.name = "John Doe";
    
44. this.salary = 30100.50;
    
45. this.w4AdditionalWithdraw = 0.02;
    
46. this.dependents = 5;
    
47. this.visualAcuity = new BigDecimal(".1");
    
48. 
    
49. Calendar dob = Calendar.getInstance();
    
50. dob.set(1964, Calendar.AUGUST, 30);
    
51. this.birthDate = dob.getTime();
    
52. this.hireDate = Calendar.getInstance();
    
53. this.startTime = new LocalTime(8, 0);
    
54. this.lastTimeEntry = (new Date()).getTime() - 10000;
    
55. }
    
56. 
    
57. public String getName() {
    
58. return name;
    
59. }
    
60. 
    
61. public void setName(String name) {
    
62. this.name = name;
    
63. }
    
64. 
    
65. public double getSalary() {
    
66. return salary;
    
67. }
    
68. 
    
69. public void setSalary(double salary) {
    
70. this.salary = salary;
    
71. }
    
72. 
    
73. public double getW4AdditionalWithdraw() {
    
74. return w4AdditionalWithdraw;
    
75. }
    
76. 
    
77. public void setW4AdditionalWithdraw(double w4AdditionalWithdraw) {
    
78. this.w4AdditionalWithdraw = w4AdditionalWithdraw;
    
79. }
    
80. 
    
81. public int getDependents() {
    
82. return dependents;
    
83. }
    
84. 
    
85. public void setDependents(int dependents) {
    
86. this.dependents = dependents;
    
87. }
    
88. 
    
89. public BigDecimal getVisualAcuity() {
    
90. return visualAcuity;
    
91. }
    
92. 
    
93. public void setVisualAcuity(BigDecimal visualAcuity) {
    
94. this.visualAcuity = visualAcuity;
    
95. }
    
96. 
    
97. public Date getBirthDate() {
    
98. return birthDate;
    
99. }
    
100. 
     
101. public void setBirthDate(Date birthDate) {
     
102. this.birthDate = birthDate;
     
103. }
     
104. 
     
105. public LocalTime getStartTime() {
     
106. return startTime;
     
107. }
     
108. 
     
109. public void setStartTime(LocalTime startTime) {
     
110. this.startTime = startTime;
     
111. }
     
112. 
     
113. public Calendar getHireDate() {
     
114. return hireDate;
     
115. }
     
116. 
     
117. public void setHireDate(Calendar hireDate) {
     
118. this.hireDate = hireDate;
     
119. }
     
120. 
     
121. public long getLastTimeEntry() {
     
122. return lastTimeEntry;
     
123. }
     
124. 
     
125. public void setLastTimeEntry(long lastTimeEntry) {
     
126. this.lastTimeEntry = lastTimeEntry;
     
127. }
     
128. 
     
129. }

复制代码

当在页面上显示的时候，我们会直接得到我们想要的格式，如下图所示：
 

注解的可选属性
注解的属性决定了@NumberFormat和@DateTimeFormat注解怎样格式化相应的属性。 @NumberFormat注解有两个可选的属性：style和pattern。style属性是一个NumberFormat.Style枚举值，可以是以下的三个值之一：

NumberFormat.Style 枚举值	是否缺省值
NUMBER	是
CURRENCY	否
PERCENT	否

这 3种style的应用我们在上面的代码中都有相应的例子。

具体的style的表现形式是与区域相关的。例如，一个double类型的字段，如果style是CURRENCY，那么在en-us的区域显示的时候前面会加上$，在zh-cn的区域显示的时候前面会加上￥。

如果以上的3中方式无法满足需求，我们可以使用pattern属性来指定特殊的输出格式。Pattern的值要遵循Java标准的numeric formatting pattern。对于@NumberFormat来说缺省的是没有pattern的。

@DateTimeFormat 注解有3个可选的属性：style，pattern和iso。属性style允许我们使用两个字符的字符串来表明怎样格式化日期和时间。第一个字符表明了日期的格式，第二个字符表明了时间的格式。下面的表格中列出了可用的选择以及相应的输出的例子：

描述	字符串值	示例输出
短格式（这是缺省值）	SS	8/30/64 11:24 AM
中等格式	MM	Aug 30, 1964 11:24:41 AM
长格式	LL	August 30, 1964 11:24:41 AM CDT
完整格式	FF	Sunday, August 30, 1964 11:24:41 AM CDT
使用短横线省略日期或时间	M-	Aug 30, 1964

Pattern 属性允许我们使用自定义的日期/时间格式。该属性的值遵循java标准的date/time格式规范。缺省的该属性的值为空，也就是不进行特殊的格式化。

最后，可以使用org.springframework.format.annotation.DateTimeFormat.ISO枚举值来使用ISO标准的日期/时间格式来格式化。下面的表格中列出了可能的值和相应的输出

ISO枚举值	输出
DATE	2000-10-31
TIME	01:30:00.000-05:00（最后的是时区)
DATE_TIME	2000-10-31 01:30:00.000-05:00.
NONE	不进行ISO标准的格式化

使用格式化注解的设置

要使用上面介绍的格式化注解，需要进行如下的配置：

1.下载Spring 3.0的jar包并加入到类路径中。

2. 将下面的配置信息加入到spring bean的XML配置文件中。
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mvc="http://www.springframework.org/schema/mvc" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd  http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd"> <mvc:annotation-driven /> </beans>
解析参数

我们也可以使用这些注解来告诉Spring怎样解析输入的数据。下面的例子显示了怎样使用@DateTimeFormat来解析以ISO格式输入的时间信息：
public String getEmployeesOnTheClock(@DateTimeFormat(iso=ISO.TIME) java.util.Date time) { ... }