001 package hirondelle.web4j.request;
002
003 import hirondelle.web4j.model.DateTime;
004 import java.util.Date;
005 import java.util.Locale;
006 import java.util.TimeZone;
007
008 /**
009 Convert text into a {@link DateTime} or {@link Date} object, and vice versa.
010
011 <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured.
012 {@link hirondelle.web4j.BuildImpl#forDateConverter()}
013 returns the configured implementation of this interface.
014
015 <P>This interface has methods which occur in pairs, one for a {@link DateTime}, and one for a {@link Date}.
016 The term 'date' used below refers to generically to both of these classes. WEB4J recommeds
017 {@link DateTime} as the preferred class for representing dates.
018
019 <P>The application programmer's implementation of this interface is used when WEB4J needs to
020 build a date from user input, or format an existing date. Here is an
021 <a href="http://www.javapractices.com/apps/fish/javadoc/src-html/hirondelle/web4j/config/DateConverterImpl.html">example implementation</a>.
022
023 <P><b><em>Design Notes</em></b><br>
024 Here are some forces concerning dates in Java web applications :
025 <ul>
026 <li>usually, users expect date input formats to be the same for all forms.
027 <li>an application may have only dates, only date-times, or a mixture of the two.
028 <li>user input of a date or date-time may be with a single control, or with many controls. For example,
029 the date may be entered with one control, and the hours and minutes with a second and third control, respectively.
030 (WEB4J works well with the one-control-only style. Using more than one control is still possible, since the application
031 programmer always has access to the underlying request parameters. But, when using WEB4J,
032 that style involves slightly more work for the application programmer.)
033 <li><span class="highlight">the needs of the eye differ from the needs of the hand.</span> That is, a date format
034 which is easy to <em>read</em> is usually not easy to <em>enter</em> into a control. Thus, applications should support <em>two</em> formats for
035 dates : a <em>hand-friendly</em> format (used for input), and an <em>eye-friendly</em> format, used for
036 presentation <em>and</em> for input as well (allowing user input with an eye-friendly format is
037 important for forms which change existing data).
038 <li>date formats may differ between Locales. For example, <tt>'01-31-2006'</tt> is natural for English speakers
039 (January 31, 2006), while <tt>'31-01-2006'</tt> is more natural for French speakers (le 31 janvier 2006).
040 <li>for <em>parsing</em> tasks, {@link java.text.SimpleDateFormat} is mediocre, and perhaps even untrustworthy. It should be used with great care.
041 One should also be aware that it's not thread-safe.
042 <li>if a new {@link Locale} is added to an application, then parsing and formatting of a date should not fail.
043 Instead, reasonable defaults should be defined for unknown <tt>Locale</tt>s.
044 </ul>
045 */
046 public interface DateConverter {
047
048 /**
049 Parse textual user input of a "hand-friendly" format into a {@link Date} object.
050
051 <P>A hand-friendly format might be <tt>'01312006'</tt>, while an eye-friendly format might be
052 <tt>'Jan 31, 2006'</tt>.
053 <P>The implementation must return <tt>null</tt> when the user input cannot be
054 successfully parsed into a {@link Date}. It is recommended that the implementation
055 have reasonable default behaviour for unexpected {@link Locale}s.
056 <P>This method is called by {@link RequestParser}.
057
058 @param aInputValue user input value, as returned by {@link hirondelle.web4j.model.ConvertParam#filter(String)}
059 (always has content).
060 @param aLocale is obtained from the configured {@link LocaleSource}, and passed to this method
061 by the framework.
062 @param aTimeZone is obtained from the configured {@link TimeZoneSource}, and passed to this method
063 by the framework.
064 */
065 Date parseHandFriendly(String aInputValue, Locale aLocale, TimeZone aTimeZone);
066
067 /**
068 Parse textual user input of an "eye-friendly" format into a {@link Date} object.
069
070 <P>A hand-friendly format might be <tt>'01312006'</tt>, while an eye-friendly format might be
071 <tt>'Jan 31, 2006'</tt>.
072 <P>The implementation must return <tt>null</tt> when the user input cannot be
073 successfully parsed into a {@link Date}. It is recommended that the implementation
074 have reasonable default behaviour for unexpected {@link Locale}s.
075 <P>This method is called by {@link RequestParser}.
076
077 @param aInputValue user input value, as returned by {@link hirondelle.web4j.model.ConvertParam#filter(String)}
078 (always has content).
079 @param aLocale is obtained from the configured {@link LocaleSource}, and passed to this method
080 by the framework.
081 @param aTimeZone is obtained from the configured {@link TimeZoneSource}, and passed to this method
082 by the framework.
083 */
084 Date parseEyeFriendly(String aInputValue, Locale aLocale, TimeZone aTimeZone);
085
086 /**
087 Format a {@link Date} into an eye-friendly, legible format.
088
089 <P>The implementation must return an empty <tt>String</tt> when the {@link Date} is null.
090 It is recommended that the implementation have reasonable default behaviour for unexpected {@link Locale}s.
091 <P>The framework will call this method when presenting listings using
092 {@link hirondelle.web4j.database.Report}, and when presenting a Model Object in a form
093 for a "change" operation.
094 <P>This method is called by {@link Formats}.
095
096 @param aDate to be presented to the user in a legible format
097 @param aLocale is obtained from the configured {@link LocaleSource}, and passed to this method
098 by the framework.
099 @param aTimeZone is obtained from the configured {@link TimeZoneSource}, and passed to this method
100 by the framework.
101 @return text compatible with {@link #parseEyeFriendly(String, Locale, TimeZone)}
102 */
103 String formatEyeFriendly(Date aDate, Locale aLocale, TimeZone aTimeZone);
104
105 /**
106 Parse textual user input of a "hand-friendly" format into a {@link DateTime} object.
107
108 <P>A hand-friendly format might be <tt>'01312006'</tt>, while an eye-friendly format might be
109 <tt>'Jan 31, 2006'</tt>.
110 <P>The implementation must return <tt>null</tt> when the user input cannot be
111 successfully parsed into a {@link DateTime}. It is recommended that the implementation
112 have reasonable default behaviour for unexpected {@link Locale}s.
113 <P>This method is called by {@link RequestParser}.
114
115 @param aInputValue user input value, as returned by {@link hirondelle.web4j.model.ConvertParam#filter(String)}
116 (always has content).
117 @param aLocale is obtained from the configured {@link LocaleSource}, and passed to this method
118 by the framework.
119 */
120 DateTime parseHandFriendlyDateTime(String aInputValue, Locale aLocale);
121
122 /**
123 Parse textual user input of an "eye-friendly" format into a {@link DateTime} object.
124
125 <P>A hand-friendly format might be <tt>'01312006'</tt>, while an eye-friendly format might be
126 <tt>'Jan 31, 2006'</tt>.
127 <P>The implementation must return <tt>null</tt> when the user input cannot be
128 successfully parsed into a {@link DateTime}. It is recommended that the implementation
129 have reasonable default behaviour for unexpected {@link Locale}s.
130 <P>This method is called by {@link RequestParser}.
131
132 @param aInputValue user input value, as returned by {@link hirondelle.web4j.model.ConvertParam#filter(String)}
133 (always has content).
134 @param aLocale is obtained from the configured {@link LocaleSource}, and passed to this method
135 by the framework.
136 */
137 DateTime parseEyeFriendlyDateTime(String aInputValue, Locale aLocale);
138
139 /**
140 Format a {@link DateTime} into an eye-friendly, legible format.
141
142 <P>The implementation must return an empty <tt>String</tt> when the {@link DateTime} is null.
143 It is recommended that the implementation have reasonable default behaviour for unexpected {@link Locale}s.
144 <P>The framework will call this method when presenting listings using
145 {@link hirondelle.web4j.database.Report}, and when presenting a Model Object in a form
146 for a "change" operation.
147 <P>This method is called by {@link Formats}.
148
149 @param aDateTime to be presented to the user in a legible format
150 @param aLocale is obtained from the configured {@link LocaleSource}, and passed to this method
151 by the framework.
152 @return text compatible with {@link #parseEyeFriendlyDateTime(String, Locale)}
153 */
154 String formatEyeFriendlyDateTime(DateTime aDateTime, Locale aLocale);
155
156
157
158 }