001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.commons.validator.routines;
018:
019: import java.text.DateFormat;
020: import java.text.Format;
021: import java.util.Calendar;
022: import java.util.Locale;
023: import java.util.TimeZone;
024:
025: /**
026: * <p><b>Time Validation</b> and Conversion routines (<code>java.util.Calendar</code>).</p>
027: *
028: * <p>This validator provides a number of methods for validating/converting
029: * a <code>String</code> time value to a <code>java.util.Calendar</code> using
030: * <code>java.text.DateFormat</code> to parse either:</p>
031: * <ul>
032: * <li>using the default format for the default <code>Locale</code></li>
033: * <li>using a specified pattern with the default <code>Locale</code></li>
034: * <li>using the default format for a specified <code>Locale</code></li>
035: * <li>using a specified pattern with a specified <code>Locale</code></li>
036: * </ul>
037: *
038: * <p>For each of the above mechanisms, conversion method (i.e the
039: * <code>validate</code> methods) implementations are provided which
040: * either use the default <code>TimeZone</code> or allow the
041: * <code>TimeZone</code> to be specified.</p>
042: *
043: * <p>Use one of the <code>isValid()</code> methods to just validate or
044: * one of the <code>validate()</code> methods to validate and receive a
045: * <i>converted</i> <code>Calendar</code> value for the time.</p>
046: *
047: * <p>Implementations of the <code>validate()</code> method are provided
048: * to create <code>Calendar</code> objects for different <i>time zones</i>
049: * if the system default is not appropriate.</p>
050: *
051: * <p>Alternatively the CalendarValidator's <code>adjustToTimeZone()</code> method
052: * can be used to adjust the <code>TimeZone</code> of the <code>Calendar</code>
053: * object afterwards.</p>
054: *
055: * <p>Once a value has been sucessfully converted the following
056: * methods can be used to perform various time comparison checks:</p>
057: * <ul>
058: * <li><code>compareTime()</code> compares the hours, minutes, seconds
059: * and milliseconds of two calendars, returing 0, -1 or +1 indicating
060: * whether the first time is equal, before or after the second.</li>
061: * <li><code>compareSeconds()</code> compares the hours, minutes and
062: * seconds of two times, returing 0, -1 or +1 indicating
063: * whether the first is equal to, before or after the second.</li>
064: * <li><code>compareMinutes()</code> compares the hours and minutes
065: * two times, returing 0, -1 or +1 indicating
066: * whether the first is equal to, before or after the second.</li>
067: * <li><code>compareHours()</code> compares the hours
068: * of two times, returing 0, -1 or +1 indicating
069: * whether the first is equal to, before or after the second.</li>
070: * </ul>
071: *
072: * <p>So that the same mechanism used for parsing an <i>input</i> value
073: * for validation can be used to format <i>output</i>, corresponding
074: * <code>format()</code> methods are also provided. That is you can
075: * format either:</p>
076: * <ul>
077: * <li>using a specified pattern</li>
078: * <li>using the format for a specified <code>Locale</code></li>
079: * <li>using the format for the <i>default</i> <code>Locale</code></li>
080: * </ul>
081: *
082: * @version $Revision: 478334 $ $Date: 2006-11-22 21:31:54 +0000 (Wed, 22 Nov 2006) $
083: * @since Validator 1.3.0
084: */
085: public class TimeValidator extends AbstractCalendarValidator {
086:
087: private static final TimeValidator VALIDATOR = new TimeValidator();
088:
089: /**
090: * Return a singleton instance of this validator.
091: * @return A singleton instance of the TimeValidator.
092: */
093: public static TimeValidator getInstance() {
094: return VALIDATOR;
095: }
096:
097: /**
098: * Construct a <i>strict</i> instance with <i>short</i>
099: * time style.
100: */
101: public TimeValidator() {
102: this (true, DateFormat.SHORT);
103: }
104:
105: /**
106: * Construct an instance with the specified <i>strict</i>
107: * and <i>time style</i> parameters.
108: *
109: * @param strict <code>true</code> if strict
110: * <code>Format</code> parsing should be used.
111: * @param timeStyle the time style to use for Locale validation.
112: */
113: public TimeValidator(boolean strict, int timeStyle) {
114: super (strict, -1, timeStyle);
115: }
116:
117: /**
118: * <p>Validate/convert a time using the default <code>Locale</code>
119: * and <code>TimeZone</code>.
120: *
121: * @param value The value validation is being performed on.
122: * @return The parsed <code>Calendar</code> if valid or <code>null</code>
123: * if invalid.
124: */
125: public Calendar validate(String value) {
126: return (Calendar) parse(value, (String) null, (Locale) null,
127: (TimeZone) null);
128: }
129:
130: /**
131: * <p>Validate/convert a time using the specified <code>TimeZone</code>
132: * and default <code>Locale</code>.
133: *
134: * @param value The value validation is being performed on.
135: * @param timeZone The Time Zone used to parse the time, system default if null.
136: * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
137: */
138: public Calendar validate(String value, TimeZone timeZone) {
139: return (Calendar) parse(value, (String) null, (Locale) null,
140: timeZone);
141: }
142:
143: /**
144: * <p>Validate/convert a time using the specified <i>pattern</i> and
145: * default <code>TimeZone</code>.
146: *
147: * @param value The value validation is being performed on.
148: * @param pattern The pattern used to validate the value against.
149: * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
150: */
151: public Calendar validate(String value, String pattern) {
152: return (Calendar) parse(value, pattern, (Locale) null,
153: (TimeZone) null);
154: }
155:
156: /**
157: * <p>Validate/convert a time using the specified <i>pattern</i>
158: * and <code>TimeZone</code>.
159: *
160: * @param value The value validation is being performed on.
161: * @param pattern The pattern used to validate the value against.
162: * @param timeZone The Time Zone used to parse the time, system default if null.
163: * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
164: */
165: public Calendar validate(String value, String pattern,
166: TimeZone timeZone) {
167: return (Calendar) parse(value, pattern, (Locale) null, timeZone);
168: }
169:
170: /**
171: * <p>Validate/convert a time using the specified <code>Locale</code>
172: * default <code>TimeZone</code>.
173: *
174: * @param value The value validation is being performed on.
175: * @param locale The locale to use for the time format, system default if null.
176: * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
177: */
178: public Calendar validate(String value, Locale locale) {
179: return (Calendar) parse(value, (String) null, locale,
180: (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,
193: TimeZone timeZone) {
194: return (Calendar) parse(value, (String) null, locale, timeZone);
195: }
196:
197: /**
198: * <p>Validate/convert a time using the specified pattern and <code>Locale</code>
199: * and the default <code>TimeZone</code>.
200: *
201: * @param value The value validation is being performed on.
202: * @param pattern The pattern used to validate the value against, or the
203: * default for the <code>Locale</code> if <code>null</code>.
204: * @param locale The locale to use for the date format, system default if null.
205: * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
206: */
207: public Calendar validate(String value, String pattern, Locale locale) {
208: return (Calendar) parse(value, pattern, locale, (TimeZone) null);
209: }
210:
211: /**
212: * <p>Validate/convert a time using the specified pattern, <code>Locale</code>
213: * and <code>TimeZone</code>.
214: *
215: * @param value The value validation is being performed on.
216: * @param pattern The pattern used to validate the value against, or the
217: * default for the <code>Locale</code> if <code>null</code>.
218: * @param locale The locale to use for the date format, system default if null.
219: * @param timeZone The Time Zone used to parse the date, system default if null.
220: * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
221: */
222: public Calendar validate(String value, String pattern,
223: Locale locale, TimeZone timeZone) {
224: return (Calendar) parse(value, pattern, locale, timeZone);
225: }
226:
227: /**
228: * <p>Compare Times (hour, minute, second and millisecond - not date).</p>
229: *
230: * @param value The <code>Calendar</code> value to check.
231: * @param compare The <code>Calendar</code> to compare the value to.
232: * @return Zero if the hours are equal, -1 if first
233: * time is less than the seconds and +1 if the first
234: * time is greater than.
235: */
236: public int compareTime(Calendar value, Calendar compare) {
237: return compareTime(value, compare, Calendar.MILLISECOND);
238: }
239:
240: /**
241: * <p>Compare Seconds (hours, minutes and seconds).</p>
242: *
243: * @param value The <code>Calendar</code> value to check.
244: * @param compare The <code>Calendar</code> to compare the value to.
245: * @return Zero if the hours are equal, -1 if first
246: * parameter's seconds are less than the seconds and +1 if the first
247: * parameter's seconds are greater than.
248: */
249: public int compareSeconds(Calendar value, Calendar compare) {
250: return compareTime(value, compare, Calendar.SECOND);
251: }
252:
253: /**
254: * <p>Compare Minutes (hours and minutes).</p>
255: *
256: * @param value The <code>Calendar</code> value to check.
257: * @param compare The <code>Calendar</code> to compare the value to.
258: * @return Zero if the hours are equal, -1 if first
259: * parameter's minutes are less than the seconds and +1 if the first
260: * parameter's minutes are greater than.
261: */
262: public int compareMinutes(Calendar value, Calendar compare) {
263: return compareTime(value, compare, Calendar.MINUTE);
264: }
265:
266: /**
267: * <p>Compare Hours.</p>
268: *
269: * @param value The <code>Calendar</code> value to check.
270: * @param compare The <code>Calendar</code> to compare the value to.
271: * @return Zero if the hours are equal, -1 if first
272: * parameter's hour is less than the seconds and +1 if the first
273: * parameter's hour is greater than.
274: */
275: public int compareHours(Calendar value, Calendar compare) {
276: return compareTime(value, compare, Calendar.HOUR_OF_DAY);
277: }
278:
279: /**
280: * <p>Convert the parsed <code>Date</code> to a <code>Calendar</code>.</p>
281: *
282: * @param value The parsed <code>Date</code> object created.
283: * @param formatter The Format used to parse the value with.
284: * @return The parsed value converted to a <code>Calendar</code>.
285: */
286: protected Object processParsedValue(Object value, Format formatter) {
287: return ((DateFormat) formatter).getCalendar();
288: }
289: }
|