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 */ 017package org.apache.commons.validator.routines; 018 019import java.text.DateFormat; 020import java.text.Format; 021import java.util.Calendar; 022import java.util.Locale; 023import 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 successfully 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, returning 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, returning 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, returning 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, returning 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$ 083 * @since Validator 1.3.0 084 */ 085public class TimeValidator extends AbstractCalendarValidator { 086 087 private static final long serialVersionUID = 3494007492269691581L; 088 089 private static final TimeValidator VALIDATOR = new TimeValidator(); 090 091 /** 092 * Return a singleton instance of this validator. 093 * @return A singleton instance of the TimeValidator. 094 */ 095 public static TimeValidator getInstance() { 096 return VALIDATOR; 097 } 098 099 /** 100 * Construct a <i>strict</i> instance with <i>short</i> 101 * time style. 102 */ 103 public TimeValidator() { 104 this(true, DateFormat.SHORT); 105 } 106 107 /** 108 * Construct an instance with the specified <i>strict</i> 109 * and <i>time style</i> parameters. 110 * 111 * @param strict <code>true</code> if strict 112 * <code>Format</code> parsing should be used. 113 * @param timeStyle the time style to use for Locale validation. 114 */ 115 public TimeValidator(boolean strict, int timeStyle) { 116 super(strict, -1, timeStyle); 117 } 118 119 /** 120 * <p>Validate/convert a time using the default <code>Locale</code> 121 * and <code>TimeZone</code>. 122 * 123 * @param value The value validation is being performed on. 124 * @return The parsed <code>Calendar</code> if valid or <code>null</code> 125 * if invalid. 126 */ 127 public Calendar validate(String value) { 128 return (Calendar)parse(value, (String)null, (Locale)null, (TimeZone)null); 129 } 130 131 /** 132 * <p>Validate/convert a time using the specified <code>TimeZone</code> 133 * and default <code>Locale</code>. 134 * 135 * @param value The value validation is being performed on. 136 * @param timeZone The Time Zone used to parse the time, system default if null. 137 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 138 */ 139 public Calendar validate(String value, TimeZone timeZone) { 140 return (Calendar)parse(value, (String)null, (Locale)null, 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, (TimeZone)null); 153 } 154 155 /** 156 * <p>Validate/convert a time using the specified <i>pattern</i> 157 * and <code>TimeZone</code>. 158 * 159 * @param value The value validation is being performed on. 160 * @param pattern The pattern used to validate the value against. 161 * @param timeZone The Time Zone used to parse the time, system default if null. 162 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 163 */ 164 public Calendar validate(String value, String pattern, TimeZone timeZone) { 165 return (Calendar)parse(value, pattern, (Locale)null, timeZone); 166 } 167 168 /** 169 * <p>Validate/convert a time using the specified <code>Locale</code> 170 * default <code>TimeZone</code>. 171 * 172 * @param value The value validation is being performed on. 173 * @param locale The locale to use for the time format, system default if null. 174 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 175 */ 176 public Calendar validate(String value, Locale locale) { 177 return (Calendar)parse(value, (String)null, locale, (TimeZone)null); 178 } 179 180 /** 181 * <p>Validate/convert a time using the specified specified <code>Locale</code> 182 * and <code>TimeZone</code>. 183 * 184 * @param value The value validation is being performed on. 185 * @param locale The locale to use for the time format, system default if null. 186 * @param timeZone The Time Zone used to parse the time, system default if null. 187 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 188 */ 189 public Calendar validate(String value, Locale locale, TimeZone timeZone) { 190 return (Calendar)parse(value, (String)null, locale, timeZone); 191 } 192 193 /** 194 * <p>Validate/convert a time using the specified pattern and <code>Locale</code> 195 * and the default <code>TimeZone</code>. 196 * 197 * @param value The value validation is being performed on. 198 * @param pattern The pattern used to validate the value against, or the 199 * default for the <code>Locale</code> if <code>null</code>. 200 * @param locale The locale to use for the date format, system default if null. 201 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 202 */ 203 public Calendar validate(String value, String pattern, Locale locale) { 204 return (Calendar)parse(value, pattern, locale, (TimeZone)null); 205 } 206 207 /** 208 * <p>Validate/convert a time using the specified pattern, <code>Locale</code> 209 * and <code>TimeZone</code>. 210 * 211 * @param value The value validation is being performed on. 212 * @param pattern The pattern used to validate the value against, or the 213 * default for the <code>Locale</code> if <code>null</code>. 214 * @param locale The locale to use for the date format, system default if null. 215 * @param timeZone The Time Zone used to parse the date, system default if null. 216 * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid. 217 */ 218 public Calendar validate(String value, String pattern, Locale locale, TimeZone timeZone) { 219 return (Calendar)parse(value, pattern, locale, timeZone); 220 } 221 222 /** 223 * <p>Compare Times (hour, minute, second and millisecond - not date).</p> 224 * 225 * @param value The <code>Calendar</code> value to check. 226 * @param compare The <code>Calendar</code> to compare the value to. 227 * @return Zero if the hours are equal, -1 if first 228 * time is less than the seconds and +1 if the first 229 * time is greater than. 230 */ 231 public int compareTime(Calendar value, Calendar compare) { 232 return compareTime(value, compare, Calendar.MILLISECOND); 233 } 234 235 /** 236 * <p>Compare Seconds (hours, minutes and seconds).</p> 237 * 238 * @param value The <code>Calendar</code> value to check. 239 * @param compare The <code>Calendar</code> to compare the value to. 240 * @return Zero if the hours are equal, -1 if first 241 * parameter's seconds are less than the seconds and +1 if the first 242 * parameter's seconds are greater than. 243 */ 244 public int compareSeconds(Calendar value, Calendar compare) { 245 return compareTime(value, compare, Calendar.SECOND); 246 } 247 248 /** 249 * <p>Compare Minutes (hours and minutes).</p> 250 * 251 * @param value The <code>Calendar</code> value to check. 252 * @param compare The <code>Calendar</code> to compare the value to. 253 * @return Zero if the hours are equal, -1 if first 254 * parameter's minutes are less than the seconds and +1 if the first 255 * parameter's minutes are greater than. 256 */ 257 public int compareMinutes(Calendar value, Calendar compare) { 258 return compareTime(value, compare, Calendar.MINUTE); 259 } 260 261 /** 262 * <p>Compare Hours.</p> 263 * 264 * @param value The <code>Calendar</code> value to check. 265 * @param compare The <code>Calendar</code> to compare the value to. 266 * @return Zero if the hours are equal, -1 if first 267 * parameter's hour is less than the seconds and +1 if the first 268 * parameter's hour is greater than. 269 */ 270 public int compareHours(Calendar value, Calendar compare) { 271 return compareTime(value, compare, Calendar.HOUR_OF_DAY); 272 } 273 274 /** 275 * <p>Convert the parsed <code>Date</code> to a <code>Calendar</code>.</p> 276 * 277 * @param value The parsed <code>Date</code> object created. 278 * @param formatter The Format used to parse the value with. 279 * @return The parsed value converted to a <code>Calendar</code>. 280 */ 281 @Override 282 protected Object processParsedValue(Object value, Format formatter) { 283 return ((DateFormat)formatter).getCalendar(); 284 } 285}