1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 package org.apache.commons.validator.routines;
23
24 import java.text.DateFormat;
25 import java.text.Format;
26 import java.util.Calendar;
27 import java.util.Locale;
28 import java.util.TimeZone;
29
30 /***
31 * <p><b>Time Validation</b> and Conversion routines (<code>java.util.Calendar</code>).</p>
32 *
33 * <p>This validator provides a number of methods for validating/converting
34 * a <code>String</code> time value to a <code>java.util.Calendar</code> using
35 * <code>java.text.DateFormat</code> to parse either:</p>
36 * <ul>
37 * <li>using the default format for the default <code>Locale</code></li>
38 * <li>using a specified pattern with the default <code>Locale</code></li>
39 * <li>using the default format for a specified <code>Locale</code></li>
40 * <li>using a specified pattern with a specified <code>Locale</code></li>
41 * </ul>
42 *
43 * <p>For each of the above mechanisms, conversion method (i.e the
44 * <code>validate</code> methods) implementations are provided which
45 * either use the default <code>TimeZone</code> or allow the
46 * <code>TimeZone</code> to be specified.</p>
47 *
48 * <p>Use one of the <code>isValid()</code> methods to just validate or
49 * one of the <code>validate()</code> methods to validate and receive a
50 * <i>converted</i> <code>Calendar</code> value for the time.</p>
51 *
52 * <p>Implementations of the <code>validate()</code> method are provided
53 * to create <code>Calendar</code> objects for different <i>time zones</i>
54 * if the system default is not appropriate.</p>
55 *
56 * <p>Alternatively the CalendarValidator's <code>adjustToTimeZone()</code> method
57 * can be used to adjust the <code>TimeZone</code> of the <code>Calendar</code>
58 * object afterwards.</p>
59 *
60 * <p>Once a value has been sucessfully converted the following
61 * methods can be used to perform various time comparison checks:</p>
62 * <ul>
63 * <li><code>compareTime()</code> compares the hours, minutes, seconds
64 * and milliseconds of two calendars, returing 0, -1 or +1 indicating
65 * whether the first time is equal, before or after the second.</li>
66 * <li><code>compareSeconds()</code> compares the hours, minutes and
67 * seconds of two times, returing 0, -1 or +1 indicating
68 * whether the first is equal to, before or after the second.</li>
69 * <li><code>compareMinutes()</code> compares the hours and minutes
70 * two times, returing 0, -1 or +1 indicating
71 * whether the first is equal to, before or after the second.</li>
72 * <li><code>compareHours()</code> compares the hours
73 * of two times, returing 0, -1 or +1 indicating
74 * whether the first is equal to, before or after the second.</li>
75 * </ul>
76 *
77 * <p>So that the same mechanism used for parsing an <i>input</i> value
78 * for validation can be used to format <i>output</i>, corresponding
79 * <code>format()</code> methods are also provided. That is you can
80 * format either:</p>
81 * <ul>
82 * <li>using a specified pattern</li>
83 * <li>using the format for a specified <code>Locale</code></li>
84 * <li>using the format for the <i>default</i> <code>Locale</code></li>
85 * </ul>
86 *
87 * @version $Revision: 386637 $ $Date: 2006-03-17 13:22:26 +0000 (Fri, 17 Mar 2006) $
88 * @since Validator 1.3.0
89 */
90 public class TimeValidator extends AbstractCalendarValidator {
91
92 private static final TimeValidator VALIDATOR = new TimeValidator();
93
94 /***
95 * Return a singleton instance of this validator.
96 * @return A singleton instance of the TimeValidator.
97 */
98 public static TimeValidator getInstance() {
99 return VALIDATOR;
100 }
101
102 /***
103 * Construct a <i>strict</i> instance with <i>short</i>
104 * time style.
105 */
106 public TimeValidator() {
107 this(true, DateFormat.SHORT);
108 }
109
110 /***
111 * Construct an instance with the specified <i>strict</i>
112 * and <i>time style</i> parameters.
113 *
114 * @param strict <code>true</code> if strict
115 * <code>Format</code> parsing should be used.
116 * @param timeStyle the time style to use for Locale validation.
117 */
118 public TimeValidator(boolean strict, int timeStyle) {
119 super(strict, -1, timeStyle);
120 }
121
122 /***
123 * <p>Validate/convert a time using the default <code>Locale</code>
124 * and <code>TimeZone</code>.
125 *
126 * @param value The value validation is being performed on.
127 * @return The parsed <code>Calendar</code> if valid or <code>null</code>
128 * if invalid.
129 */
130 public Calendar validate(String value) {
131 return (Calendar)parse(value, (String)null, (Locale)null, (TimeZone)null);
132 }
133
134 /***
135 * <p>Validate/convert a time using the specified <code>TimeZone</code>
136 * and default <code>Locale</code>.
137 *
138 * @param value The value validation is being performed on.
139 * @param timeZone The Time Zone used to parse the time, system default if null.
140 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
141 */
142 public Calendar validate(String value, TimeZone timeZone) {
143 return (Calendar)parse(value, (String)null, (Locale)null, timeZone);
144 }
145
146 /***
147 * <p>Validate/convert a time using the specified <i>pattern</i> and
148 * default <code>TimeZone</code>.
149 *
150 * @param value The value validation is being performed on.
151 * @param pattern The pattern used to validate the value against.
152 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
153 */
154 public Calendar validate(String value, String pattern) {
155 return (Calendar)parse(value, pattern, (Locale)null, (TimeZone)null);
156 }
157
158 /***
159 * <p>Validate/convert a time using the specified <i>pattern</i>
160 * and <code>TimeZone</code>.
161 *
162 * @param value The value validation is being performed on.
163 * @param pattern The pattern used to validate the value against.
164 * @param timeZone The Time Zone used to parse the time, system default if null.
165 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
166 */
167 public Calendar validate(String value, String pattern, TimeZone timeZone) {
168 return (Calendar)parse(value, pattern, (Locale)null, timeZone);
169 }
170
171 /***
172 * <p>Validate/convert a time using the specified <code>Locale</code>
173 * default <code>TimeZone</code>.
174 *
175 * @param value The value validation is being performed on.
176 * @param locale The locale to use for the time format, system default if null.
177 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
178 */
179 public Calendar validate(String value, Locale locale) {
180 return (Calendar)parse(value, (String)null, locale, (TimeZone)null);
181 }
182
183 /***
184 * <p>Validate/convert a time using the specified specified <code>Locale</code>
185 * and <code>TimeZone</code>.
186 *
187 * @param value The value validation is being performed on.
188 * @param locale The locale to use for the time format, system default if null.
189 * @param timeZone The Time Zone used to parse the time, system default if null.
190 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
191 */
192 public Calendar validate(String value, Locale locale, TimeZone timeZone) {
193 return (Calendar)parse(value, (String)null, locale, timeZone);
194 }
195
196 /***
197 * <p>Validate/convert a time using the specified pattern and <code>Locale</code>
198 * and the default <code>TimeZone</code>.
199 *
200 * @param value The value validation is being performed on.
201 * @param pattern The pattern used to validate the value against, or the
202 * default for the <code>Locale</code> if <code>null</code>.
203 * @param locale The locale to use for the date format, system default if null.
204 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
205 */
206 public Calendar validate(String value, String pattern, Locale locale) {
207 return (Calendar)parse(value, pattern, locale, (TimeZone)null);
208 }
209
210 /***
211 * <p>Validate/convert a time using the specified pattern, <code>Locale</code>
212 * and <code>TimeZone</code>.
213 *
214 * @param value The value validation is being performed on.
215 * @param pattern The pattern used to validate the value against, or the
216 * default for the <code>Locale</code> if <code>null</code>.
217 * @param locale The locale to use for the date format, system default if null.
218 * @param timeZone The Time Zone used to parse the date, system default if null.
219 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
220 */
221 public Calendar validate(String value, String pattern, Locale locale, TimeZone timeZone) {
222 return (Calendar)parse(value, pattern, locale, timeZone);
223 }
224
225 /***
226 * <p>Compare Times (hour, minute, second and millisecond - not date).</p>
227 *
228 * @param value The <code>Calendar</code> value to check.
229 * @param compare The <code>Calendar</code> to compare the value to.
230 * @return Zero if the hours are equal, -1 if first
231 * time is less than the seconds and +1 if the first
232 * time is greater than.
233 */
234 public int compareTime(Calendar value, Calendar compare) {
235 return compareTime(value, compare, Calendar.MILLISECOND);
236 }
237
238 /***
239 * <p>Compare Seconds (hours, minutes and seconds).</p>
240 *
241 * @param value The <code>Calendar</code> value to check.
242 * @param compare The <code>Calendar</code> to compare the value to.
243 * @return Zero if the hours are equal, -1 if first
244 * parameter's seconds are less than the seconds and +1 if the first
245 * parameter's seconds are greater than.
246 */
247 public int compareSeconds(Calendar value, Calendar compare) {
248 return compareTime(value, compare, Calendar.SECOND);
249 }
250
251 /***
252 * <p>Compare Minutes (hours and minutes).</p>
253 *
254 * @param value The <code>Calendar</code> value to check.
255 * @param compare The <code>Calendar</code> to compare the value to.
256 * @return Zero if the hours are equal, -1 if first
257 * parameter's minutes are less than the seconds and +1 if the first
258 * parameter's minutes are greater than.
259 */
260 public int compareMinutes(Calendar value, Calendar compare) {
261 return compareTime(value, compare, Calendar.MINUTE);
262 }
263
264 /***
265 * <p>Compare Hours.</p>
266 *
267 * @param value The <code>Calendar</code> value to check.
268 * @param compare The <code>Calendar</code> to compare the value to.
269 * @return Zero if the hours are equal, -1 if first
270 * parameter's hour is less than the seconds and +1 if the first
271 * parameter's hour is greater than.
272 */
273 public int compareHours(Calendar value, Calendar compare) {
274 return compareTime(value, compare, Calendar.HOUR_OF_DAY);
275 }
276
277 /***
278 * <p>Convert the parsed <code>Date</code> to a <code>Calendar</code>.</p>
279 *
280 * @param value The parsed <code>Date</code> object created.
281 * @param formatter The Format used to parse the value with.
282 * @return The parsed value converted to a <code>Calendar</code>.
283 */
284 protected Object processParsedValue(Object value, Format formatter) {
285 return ((DateFormat)formatter).getCalendar();
286 }
287 }