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: 493905 $ $Date: 2007-01-08 03:11:38 +0100 (Mo, 08. Jan 2007) $ 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, (TimeZone)null); 127 } 128 129 /** 130 * <p>Validate/convert a time using the specified <code>TimeZone</code> 131 * and default <code>Locale</code>. 132 * 133 * @param value The value validation is being performed on. 134 * @param timeZone The Time Zone used to parse the time, system default if null. 135 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 136 */ 137 public Calendar validate(String value, TimeZone timeZone) { 138 return (Calendar)parse(value, (String)null, (Locale)null, timeZone); 139 } 140 141 /** 142 * <p>Validate/convert a time using the specified <i>pattern</i> and 143 * default <code>TimeZone</code>. 144 * 145 * @param value The value validation is being performed on. 146 * @param pattern The pattern used to validate the value against. 147 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 148 */ 149 public Calendar validate(String value, String pattern) { 150 return (Calendar)parse(value, pattern, (Locale)null, (TimeZone)null); 151 } 152 153 /** 154 * <p>Validate/convert a time using the specified <i>pattern</i> 155 * and <code>TimeZone</code>. 156 * 157 * @param value The value validation is being performed on. 158 * @param pattern The pattern used to validate the value against. 159 * @param timeZone The Time Zone used to parse the time, system default if null. 160 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 161 */ 162 public Calendar validate(String value, String pattern, TimeZone timeZone) { 163 return (Calendar)parse(value, pattern, (Locale)null, timeZone); 164 } 165 166 /** 167 * <p>Validate/convert a time using the specified <code>Locale</code> 168 * default <code>TimeZone</code>. 169 * 170 * @param value The value validation is being performed on. 171 * @param locale The locale to use for the time format, system default if null. 172 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 173 */ 174 public Calendar validate(String value, Locale locale) { 175 return (Calendar)parse(value, (String)null, locale, (TimeZone)null); 176 } 177 178 /** 179 * <p>Validate/convert a time using the specified specified <code>Locale</code> 180 * and <code>TimeZone</code>. 181 * 182 * @param value The value validation is being performed on. 183 * @param locale The locale to use for the time format, system default if null. 184 * @param timeZone The Time Zone used to parse the time, system default if null. 185 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 186 */ 187 public Calendar validate(String value, Locale locale, TimeZone timeZone) { 188 return (Calendar)parse(value, (String)null, locale, timeZone); 189 } 190 191 /** 192 * <p>Validate/convert a time using the specified pattern and <code>Locale</code> 193 * and the default <code>TimeZone</code>. 194 * 195 * @param value The value validation is being performed on. 196 * @param pattern The pattern used to validate the value against, or the 197 * default for the <code>Locale</code> if <code>null</code>. 198 * @param locale The locale to use for the date format, system default if null. 199 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 200 */ 201 public Calendar validate(String value, String pattern, Locale locale) { 202 return (Calendar)parse(value, pattern, locale, (TimeZone)null); 203 } 204 205 /** 206 * <p>Validate/convert a time using the specified pattern, <code>Locale</code> 207 * and <code>TimeZone</code>. 208 * 209 * @param value The value validation is being performed on. 210 * @param pattern The pattern used to validate the value against, or the 211 * default for the <code>Locale</code> if <code>null</code>. 212 * @param locale The locale to use for the date format, system default if null. 213 * @param timeZone The Time Zone used to parse the date, system default if null. 214 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 215 */ 216 public Calendar validate(String value, String pattern, Locale locale, TimeZone timeZone) { 217 return (Calendar)parse(value, pattern, locale, timeZone); 218 } 219 220 /** 221 * <p>Compare Times (hour, minute, second and millisecond - not date).</p> 222 * 223 * @param value The <code>Calendar</code> value to check. 224 * @param compare The <code>Calendar</code> to compare the value to. 225 * @return Zero if the hours are equal, -1 if first 226 * time is less than the seconds and +1 if the first 227 * time is greater than. 228 */ 229 public int compareTime(Calendar value, Calendar compare) { 230 return compareTime(value, compare, Calendar.MILLISECOND); 231 } 232 233 /** 234 * <p>Compare Seconds (hours, minutes and seconds).</p> 235 * 236 * @param value The <code>Calendar</code> value to check. 237 * @param compare The <code>Calendar</code> to compare the value to. 238 * @return Zero if the hours are equal, -1 if first 239 * parameter's seconds are less than the seconds and +1 if the first 240 * parameter's seconds are greater than. 241 */ 242 public int compareSeconds(Calendar value, Calendar compare) { 243 return compareTime(value, compare, Calendar.SECOND); 244 } 245 246 /** 247 * <p>Compare Minutes (hours and minutes).</p> 248 * 249 * @param value The <code>Calendar</code> value to check. 250 * @param compare The <code>Calendar</code> to compare the value to. 251 * @return Zero if the hours are equal, -1 if first 252 * parameter's minutes are less than the seconds and +1 if the first 253 * parameter's minutes are greater than. 254 */ 255 public int compareMinutes(Calendar value, Calendar compare) { 256 return compareTime(value, compare, Calendar.MINUTE); 257 } 258 259 /** 260 * <p>Compare Hours.</p> 261 * 262 * @param value The <code>Calendar</code> value to check. 263 * @param compare The <code>Calendar</code> to compare the value to. 264 * @return Zero if the hours are equal, -1 if first 265 * parameter's hour is less than the seconds and +1 if the first 266 * parameter's hour is greater than. 267 */ 268 public int compareHours(Calendar value, Calendar compare) { 269 return compareTime(value, compare, Calendar.HOUR_OF_DAY); 270 } 271 272 /** 273 * <p>Convert the parsed <code>Date</code> to a <code>Calendar</code>.</p> 274 * 275 * @param value The parsed <code>Date</code> object created. 276 * @param formatter The Format used to parse the value with. 277 * @return The parsed value converted to a <code>Calendar</code>. 278 */ 279 protected Object processParsedValue(Object value, Format formatter) { 280 return ((DateFormat)formatter).getCalendar(); 281 } 282 }