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 * https://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><strong>Calendar Validation</strong> and Conversion routines ({@code java.util.Calendar}).</p> 027 * 028 * <p>This validator provides a number of methods for validating/converting 029 * a {@link String} date value to a {@code java.util.Calendar} using 030 * {@link DateFormat} to parse either:</p> 031 * <ul> 032 * <li>using the default format for the default {@link Locale}</li> 033 * <li>using a specified pattern with the default {@link Locale}</li> 034 * <li>using the default format for a specified {@link Locale}</li> 035 * <li>using a specified pattern with a specified {@link Locale}</li> 036 * </ul> 037 * 038 * <p>For each of the above mechanisms, conversion method (that is, the 039 * {@code validate} methods) implementations are provided which 040 * either use the default {@code TimeZone} or allow the 041 * {@code TimeZone} to be specified.</p> 042 * 043 * <p>Use one of the {@code isValid()} methods to just validate or 044 * one of the {@code validate()} methods to validate and receive a 045 * <em>converted</em> {@link Calendar} value.</p> 046 * 047 * <p>Implementations of the {@code validate()} method are provided 048 * to create {@link Calendar} objects for different <em>time zones</em> 049 * if the system default is not appropriate.</p> 050 * 051 * <p>Alternatively the CalendarValidator's {@code adjustToTimeZone()} method 052 * can be used to adjust the {@code TimeZone} of the {@link Calendar} 053 * object afterward.</p> 054 * 055 * <p>Once a value has been successfully converted the following 056 * methods can be used to perform various date comparison checks:</p> 057 * <ul> 058 * <li>{@code compareDates()} compares the day, month and 059 * year of two calendars, returning 0, -1 or +1 indicating 060 * whether the first date is equal, before or after the second.</li> 061 * <li>{@code compareWeeks()} compares the week and 062 * year of two calendars, returning 0, -1 or +1 indicating 063 * whether the first week is equal, before or after the second.</li> 064 * <li>{@code compareMonths()} compares the month and 065 * year of two calendars, returning 0, -1 or +1 indicating 066 * whether the first month is equal, before or after the second.</li> 067 * <li>{@code compareQuarters()} compares the quarter and 068 * year of two calendars, returning 0, -1 or +1 indicating 069 * whether the first quarter is equal, before or after the second.</li> 070 * <li>{@code compareYears()} compares the 071 * year of two calendars, returning 0, -1 or +1 indicating 072 * whether the first year is equal, before or after the second.</li> 073 * </ul> 074 * 075 * <p>So that the same mechanism used for parsing an <em>input</em> value 076 * for validation can be used to format <em>output</em>, corresponding 077 * {@code format()} methods are also provided. That is you can 078 * format either:</p> 079 * <ul> 080 * <li>using a specified pattern</li> 081 * <li>using the format for a specified {@link Locale}</li> 082 * <li>using the format for the <em>default</em> {@link Locale}</li> 083 * </ul> 084 * 085 * @since 1.3.0 086 */ 087public class CalendarValidator extends AbstractCalendarValidator { 088 089 private static final long serialVersionUID = 9109652318762134167L; 090 091 private static final CalendarValidator VALIDATOR = new CalendarValidator(); 092 093 /** 094 * <p>Adjusts a Calendar's value to a different TimeZone.</p> 095 * 096 * @param value The value to adjust. 097 * @param timeZone The new time zone to use to adjust the Calendar to. 098 */ 099 public static void adjustToTimeZone(final Calendar value, final TimeZone timeZone) { 100 if (value.getTimeZone().hasSameRules(timeZone)) { 101 value.setTimeZone(timeZone); 102 } else { 103 final int year = value.get(Calendar.YEAR); 104 final int month = value.get(Calendar.MONTH); 105 final int date = value.get(Calendar.DATE); 106 final int hour = value.get(Calendar.HOUR_OF_DAY); 107 final int minute = value.get(Calendar.MINUTE); 108 value.setTimeZone(timeZone); 109 value.set(year, month, date, hour, minute); 110 } 111 } 112 113 /** 114 * Gets the singleton instance of this validator. 115 * @return A singleton instance of the CalendarValidator. 116 */ 117 public static CalendarValidator getInstance() { 118 return VALIDATOR; 119 } 120 121 /** 122 * Constructs a <em>strict</em> instance with <em>short</em> 123 * date style. 124 */ 125 public CalendarValidator() { 126 this(true, DateFormat.SHORT); 127 } 128 129 /** 130 * Constructs an instance with the specified <em>strict</em> 131 * and <em>date style</em> parameters. 132 * 133 * @param strict {@code true} if strict 134 * {@code Format} parsing should be used. 135 * @param dateStyle the date style to use for Locale validation. 136 */ 137 public CalendarValidator(final boolean strict, final int dateStyle) { 138 super(strict, dateStyle, -1); 139 } 140 141 /** 142 * <p>Compare Dates (day, month and year - not time).</p> 143 * 144 * @param value The {@link Calendar} value to check. 145 * @param compare The {@link Calendar} to compare the value to. 146 * @return Zero if the dates are equal, -1 if first 147 * date is less than the seconds and +1 if the first 148 * date is greater than. 149 */ 150 public int compareDates(final Calendar value, final Calendar compare) { 151 return compare(value, compare, Calendar.DATE); 152 } 153 154 /** 155 * <p>Compare Months (month and year).</p> 156 * 157 * @param value The {@link Calendar} value to check. 158 * @param compare The {@link Calendar} to compare the value to. 159 * @return Zero if the months are equal, -1 if first 160 * parameter's month is less than the seconds and +1 if the first 161 * parameter's month is greater than. 162 */ 163 public int compareMonths(final Calendar value, final Calendar compare) { 164 return compare(value, compare, Calendar.MONTH); 165 } 166 167 /** 168 * <p>Compare Quarters (quarter and year).</p> 169 * 170 * @param value The {@link Calendar} value to check. 171 * @param compare The {@link Calendar} to check the value against. 172 * @return Zero if the quarters are equal, -1 if first 173 * parameter's quarter is less than the seconds and +1 if the first 174 * parameter's quarter is greater than. 175 */ 176 public int compareQuarters(final Calendar value, final Calendar compare) { 177 return compareQuarters(value, compare, 1); 178 } 179 180 /** 181 * <p>Compare Quarters (quarter and year).</p> 182 * 183 * @param value The {@link Calendar} value to check. 184 * @param compare The {@link Calendar} to compare the value to. 185 * @param monthOfFirstQuarter The month that the first quarter starts. 186 * @return Zero if the quarters are equal, -1 if first 187 * parameter's quarter is less than the seconds and +1 if the first 188 * parameter's quarter is greater than. 189 */ 190 @Override 191 public int compareQuarters(final Calendar value, final Calendar compare, final int monthOfFirstQuarter) { 192 return super.compareQuarters(value, compare, monthOfFirstQuarter); 193 } 194 195 /** 196 * <p>Compare Weeks (week and year).</p> 197 * 198 * @param value The {@link Calendar} value to check. 199 * @param compare The {@link Calendar} to compare the value to. 200 * @return Zero if the weeks are equal, -1 if first 201 * parameter's week is less than the seconds and +1 if the first 202 * parameter's week is greater than. 203 */ 204 public int compareWeeks(final Calendar value, final Calendar compare) { 205 return compare(value, compare, Calendar.WEEK_OF_YEAR); 206 } 207 208 /** 209 * <p>Compare Years.</p> 210 * 211 * @param value The {@link Calendar} value to check. 212 * @param compare The {@link Calendar} to compare the value to. 213 * @return Zero if the years are equal, -1 if first 214 * parameter's year is less than the seconds and +1 if the first 215 * parameter's year is greater than. 216 */ 217 public int compareYears(final Calendar value, final Calendar compare) { 218 return compare(value, compare, Calendar.YEAR); 219 } 220 221 /** 222 * <p>Convert the parsed {@code Date} to a {@link Calendar}.</p> 223 * 224 * @param value The parsed {@code Date} object created. 225 * @param formatter The Format used to parse the value with. 226 * @return The parsed value converted to a {@link Calendar}. 227 */ 228 @Override 229 protected Object processParsedValue(final Object value, final Format formatter) { 230 return ((DateFormat) formatter).getCalendar(); 231 } 232 233 /** 234 * <p>Validate/convert a {@link Calendar} using the default 235 * {@link Locale} and {@code TimeZone}. 236 * 237 * @param value The value validation is being performed on. 238 * @return The parsed {@link Calendar} if valid or {@code null} 239 * if invalid. 240 */ 241 public Calendar validate(final String value) { 242 return (Calendar) parse(value, (String) null, (Locale) null, (TimeZone) null); 243 } 244 245 /** 246 * <p>Validate/convert a {@link Calendar} using the specified 247 * {@link Locale} and default {@code TimeZone}. 248 * 249 * @param value The value validation is being performed on. 250 * @param locale The locale to use for the date format, system default if null. 251 * @return The parsed {@link Calendar} if valid or {@code null} if invalid. 252 */ 253 public Calendar validate(final String value, final Locale locale) { 254 return (Calendar) parse(value, (String) null, locale, (TimeZone) null); 255 } 256 257 /** 258 * <p>Validate/convert a {@link Calendar} using the specified 259 * {@link Locale} and {@code TimeZone}. 260 * 261 * @param value The value validation is being performed on. 262 * @param locale The locale to use for the date format, system default if null. 263 * @param timeZone The Time Zone used to parse the date, system default if null. 264 * @return The parsed {@link Calendar} if valid or {@code null} if invalid. 265 */ 266 public Calendar validate(final String value, final Locale locale, final TimeZone timeZone) { 267 return (Calendar) parse(value, (String) null, locale, timeZone); 268 } 269 270 /** 271 * <p>Validate/convert a {@link Calendar} using the specified 272 * <em>pattern</em> and default {@code TimeZone}. 273 * 274 * @param value The value validation is being performed on. 275 * @param pattern The pattern used to validate the value against. 276 * @return The parsed {@link Calendar} if valid or {@code null} if invalid. 277 */ 278 public Calendar validate(final String value, final String pattern) { 279 return (Calendar) parse(value, pattern, (Locale) null, (TimeZone) null); 280 } 281 282 /** 283 * <p>Validate/convert a {@link Calendar} using the specified pattern 284 * and {@link Locale} and the default {@code TimeZone}. 285 * 286 * @param value The value validation is being performed on. 287 * @param pattern The pattern used to validate the value against, or the 288 * default for the {@link Locale} if {@code null}. 289 * @param locale The locale to use for the date format, system default if null. 290 * @return The parsed {@link Calendar} if valid or {@code null} if invalid. 291 */ 292 public Calendar validate(final String value, final String pattern, final Locale locale) { 293 return (Calendar) parse(value, pattern, locale, (TimeZone) null); 294 } 295 296 /** 297 * <p>Validate/convert a {@link Calendar} using the specified 298 * pattern, and {@link Locale} and {@code TimeZone}. 299 * 300 * @param value The value validation is being performed on. 301 * @param pattern The pattern used to validate the value against, or the 302 * default for the {@link Locale} if {@code null}. 303 * @param locale The locale to use for the date format, system default if null. 304 * @param timeZone The Time Zone used to parse the date, system default if null. 305 * @return The parsed {@link Calendar} if valid or {@code null} if invalid. 306 */ 307 public Calendar validate(final String value, final String pattern, final Locale locale, final TimeZone timeZone) { 308 return (Calendar) parse(value, pattern, locale, timeZone); 309 } 310 311 /** 312 * <p>Validate/convert a {@link Calendar} using the specified 313 * <em>pattern</em> and {@code TimeZone}. 314 * 315 * @param value The value validation is being performed on. 316 * @param pattern The pattern used to validate the value against. 317 * @param timeZone The Time Zone used to parse the date, system default if null. 318 * @return The parsed {@link Calendar} if valid or {@code null} if invalid. 319 */ 320 public Calendar validate(final String value, final String pattern, final TimeZone timeZone) { 321 return (Calendar) parse(value, pattern, (Locale) null, timeZone); 322 } 323 324 /** 325 * <p>Validate/convert a {@link Calendar} using the specified 326 * {@code TimeZone} and default {@link Locale}. 327 * 328 * @param value The value validation is being performed on. 329 * @param timeZone The Time Zone used to parse the date, system default if null. 330 * @return The parsed {@link Calendar} if valid or {@code null} 331 * if invalid. 332 */ 333 public Calendar validate(final String value, final TimeZone timeZone) { 334 return (Calendar) parse(value, (String) null, (Locale) null, timeZone); 335 } 336 337}