From 7ed6c164b6c8b5c6de8304ed18dbacb084039843 Mon Sep 17 00:00:00 2001 From: Keith Donald Date: Mon, 9 Nov 2009 20:25:03 +0000 Subject: [PATCH] javadoc polishing --- .../format/annotation/DateTimeFormat.java | 44 +++++++++++++++++++ .../format/annotation/ISODateTimeFormat.java | 25 +++++++++-- ...eTimeFormatAnnotationFormatterFactory.java | 6 ++- .../joda/JodaTimeFormattingTests.java | 11 ++++- 4 files changed, 80 insertions(+), 6 deletions(-) diff --git a/org.springframework.context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java b/org.springframework.context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java index 49ebbe085a0..fcf430d5811 100644 --- a/org.springframework.context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java +++ b/org.springframework.context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java @@ -22,6 +22,18 @@ import java.lang.annotation.Target; /** * Declares that a field should be formatted as a date time. + * Supports formatting by {@link Style} or by pattern string. + *

+ * For style-based formatting: + *

+ * For pattern-based formatting, set the pattern attribute to be the DateTime pattern, such as yyyy/mm/dd h:mm:ss a. + *

+ * If no annotation attributes are specified, the default format applied is style-based with dateStyle={@link Style#SHORT} and timeStyle={@link Style#SHORT}. + * * @author Keith Donald * @since 3.0 */ @@ -51,26 +63,58 @@ public @interface DateTimeFormat { * Supported DateTimeFormat styles. */ public enum Style { + + /** + * The short format style. + *
Example short dateStyle: Locale.US="M/d/yy" e.g. 10/31/2009 + *
Example short timeStyle: Locale.US="h:mm a" e.g. 1:30 PM + */ SHORT { public String toString() { return "S"; } }, + + /** + * The medium format style. + *
Example medium dateStyle: Locale.US="MMM d, yyyy" e.g Oct 31, 2009 + *
Example medium timeStyle: Locale.US="h:mm:ss a" e.g. 1:30:00 PM + */ MEDIUM { public String toString() { return "M"; } }, + + /** + * The long format style. + *
Example long dateStyle: Locale.US="MMMM d, yyyy" e.g October 31, 2009 + *
Example long timeStyle: Locale.US="h:mm:ss a z" e.g. 1:30:00 PM Eastern Standard Time + */ LONG { public String toString() { return "L"; } }, + + /** + * The full format style. + *
Example full dateStyle: Locale.US="EEEE, MMMM d, yyyy" e.g. Saturday, October 31, 2009 + *
Example full timeStyle: Locale.US="h:mm:ss a z" e.g 1:30:00 PM Eastern Standard Time + */ FULL { public String toString() { return "F"; } }, + + /** + * The none format style. + * A dateStyle specified with this value results in date fields such as mm, dd, and yyyy being ignored. + * A timeStyle specified with this value results in time fields such as hh, mm being ignored. + * If both dateStyle and timeStyle are set to this value and the pattern attribute is also not specified, + * a default value for each is selected based on the type of field being annotated. + */ NONE { public String toString() { return "-"; diff --git a/org.springframework.context/src/main/java/org/springframework/format/annotation/ISODateTimeFormat.java b/org.springframework.context/src/main/java/org/springframework/format/annotation/ISODateTimeFormat.java index c510e0cfa04..71a32ae834e 100644 --- a/org.springframework.context/src/main/java/org/springframework/format/annotation/ISODateTimeFormat.java +++ b/org.springframework.context/src/main/java/org/springframework/format/annotation/ISODateTimeFormat.java @@ -29,10 +29,29 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) public @interface ISODateTimeFormat { - Style value(); + /** + * The ISO style to use to format the date time. + * Defaults to {@link Style#DATE_TIME}. + */ + Style value() default Style.DATE_TIME; public enum Style { - DATE, TIME, DATE_TIME + + /** + * The most common ISO Date Format yyyy-MM-dd e.g. 2000-10-31. + */ + DATE, + + /** + * The most common ISO Time Format hh:mm:ss.SSSZ e.g. 01:30:00.000-05:00. + */ + TIME, + + /** + * The most common ISO DateTime Format yyyy-MM-dd'T'hh:mm:ss.SSSZ e.g. 2000-10-31 01:30:00.000-05:00. + * The default if no annotation value is specified. + */ + DATE_TIME } - + } diff --git a/org.springframework.context/src/main/java/org/springframework/format/datetime/joda/DateTimeFormatAnnotationFormatterFactory.java b/org.springframework.context/src/main/java/org/springframework/format/datetime/joda/DateTimeFormatAnnotationFormatterFactory.java index 0340dfd91e4..58f2af0ba21 100644 --- a/org.springframework.context/src/main/java/org/springframework/format/datetime/joda/DateTimeFormatAnnotationFormatterFactory.java +++ b/org.springframework.context/src/main/java/org/springframework/format/datetime/joda/DateTimeFormatAnnotationFormatterFactory.java @@ -34,7 +34,11 @@ public final class DateTimeFormatAnnotationFormatterFactory extends AbstractDate } else { Style dateStyle = annotation.dateStyle(); Style timeStyle = annotation.timeStyle(); - return forDateTimeStyle(dateStyle, timeStyle); + if (Style.NONE == dateStyle && Style.NONE == timeStyle) { + return forDateTimeStyle(Style.SHORT, Style.SHORT); + } else { + return forDateTimeStyle(dateStyle, timeStyle); + } } } diff --git a/org.springframework.context/src/test/java/org/springframework/format/datetime/joda/JodaTimeFormattingTests.java b/org.springframework.context/src/test/java/org/springframework/format/datetime/joda/JodaTimeFormattingTests.java index b0e26d2ccc3..25368cb7c9e 100644 --- a/org.springframework.context/src/test/java/org/springframework/format/datetime/joda/JodaTimeFormattingTests.java +++ b/org.springframework.context/src/test/java/org/springframework/format/datetime/joda/JodaTimeFormattingTests.java @@ -19,7 +19,6 @@ import org.springframework.context.i18n.LocaleContextHolder; import org.springframework.format.annotation.DateTimeFormat; import org.springframework.format.annotation.ISODateTimeFormat; import org.springframework.format.annotation.DateTimeFormat.Style; -import org.springframework.format.datetime.joda.JodaTimeFormattingConfigurer; import org.springframework.format.support.FormattingConversionService; import org.springframework.validation.DataBinder; @@ -49,6 +48,14 @@ public class JodaTimeFormattingTests { JodaTimeContextHolder.setJodaTimeContext(null); } + @Test + public void testJodaTimePatternsForStyle() { + System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("SS", LocaleContextHolder.getLocale())); + System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("MM", LocaleContextHolder.getLocale())); + System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("LL", LocaleContextHolder.getLocale())); + System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("FF", LocaleContextHolder.getLocale())); + } + @Test public void testBindLocalDate() { MutablePropertyValues propertyValues = new MutablePropertyValues(); @@ -394,4 +401,4 @@ public class JodaTimeFormattingTests { } } -} +} \ No newline at end of file