View Javadoc

1   /*
2    * $Id: TimeValidator.java 386637 2006-03-17 13:22:26Z niallp $
3    * $Revision: 386637 $
4    * $Date: 2006-03-17 13:22:26 +0000 (Fri, 17 Mar 2006) $
5    *
6    * ====================================================================
7    * Copyright 2006 The Apache Software Foundation
8    *
9    * Licensed under the Apache License, Version 2.0 (the "License");
10   * you may not use this file except in compliance with the License.
11   * You may obtain a copy of the License at
12   *
13   *     http://www.apache.org/licenses/LICENSE-2.0
14   *
15   * Unless required by applicable law or agreed to in writing, software
16   * distributed under the License is distributed on an "AS IS" BASIS,
17   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18   * See the License for the specific language governing permissions and
19   * limitations under the License.
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 }