View Javadoc

    1   /*
    2    * $Id: DateValidator.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  package org.apache.commons.validator.routines;
    22
    23  import java.text.DateFormat;
    24  import java.text.Format;
    25  import java.util.Calendar;
    26  import java.util.Date;
    27  import java.util.Locale;
    28  import java.util.TimeZone;
    29
    30  /***
    31   * <p><b>Date Validation</b> and Conversion routines (<code>java.util.Date</code>).</p>
    32   *
    33   * <p>This validator provides a number of methods for validating/converting
    34   *    a <code>String</code> date value to a <code>java.util.Date</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>Date</code> value.</p>
    51   *
    52   * <p>Implementations of the <code>validate()</code> method are provided
    53   *    to create <code>Date</code> objects for different <i>time zones</i>
    54   *    if the system default is not appropriate.</p>
    55   *
    56   * <p>Once a value has been sucessfully converted the following
    57   *    methods can be used to perform various date comparison checks:</p>
    58   *    <ul>
    59   *       <li><code>compareDates()</code> compares the day, month and
    60   *           year of two dates, returing 0, -1 or +1 indicating
    61   *           whether the first date is equal, before or after the second.</li>
    62   *       <li><code>compareWeeks()</code> compares the week and
    63   *           year of two dates, returing 0, -1 or +1 indicating
    64   *           whether the first week is equal, before or after the second.</li>
    65   *       <li><code>compareMonths()</code> compares the month and
    66   *           year of two dates, returing 0, -1 or +1 indicating
    67   *           whether the first month is equal, before or after the second.</li>
    68   *       <li><code>compareQuarters()</code> compares the quarter and
    69   *           year of two dates, returing 0, -1 or +1 indicating
    70   *           whether the first quarter is equal, before or after the second.</li>
    71   *       <li><code>compareYears()</code> compares the
    72   *           year of two dates, returing 0, -1 or +1 indicating
    73   *           whether the first year is equal, before or after the second.</li>
    74   *    </ul>
    75   *
    76   * <p>So that the same mechanism used for parsing an <i>input</i> value
    77   *    for validation can be used to format <i>output</i>, corresponding
    78   *    <code>format()</code> methods are also provided. That is you can
    79   *    format either:</p>
    80   *    <ul>
    81   *       <li>using a specified pattern</li>
    82   *       <li>using the format for a specified <code>Locale</code></li>
    83   *       <li>using the format for the <i>default</i> <code>Locale</code></li>
    84   *    </ul>
    85   *
    86   * @version $Revision: 386637 $ $Date: 2006-03-17 13:22:26 +0000 (Fri, 17 Mar 2006) $
    87   * @since Validator 1.3.0
    88   */
    89  public class DateValidator extends AbstractCalendarValidator {
    90
    91      private static final DateValidator VALIDATOR = new DateValidator();
    92
    93      /***
    94       * Return a singleton instance of this validator.
    95       * @return A singleton instance of the DateValidator.
    96       */
    97      public static DateValidator getInstance() {
    98          return VALIDATOR;
    99      }
    100
    101     /***
    102      * Construct a <i>strict</i> instance with <i>short</i>
    103      * date style.
    104      */
    105     public DateValidator() {
    106         this(true, DateFormat.SHORT);
    107     }
    108
    109     /***
    110      * Construct an instance with the specified <i>strict</i>
    111      * and <i>date style</i> parameters.
    112      *
    113      * @param strict <code>true</code> if strict
    114      *        <code>Format</code> parsing should be used.
    115      * @param dateStyle the date style to use for Locale validation.
    116      */
    117     public DateValidator(boolean strict, int dateStyle) {
    118         super(strict, dateStyle, -1);
    119     }
    120
    121     /***
    122      * <p>Validate/convert a <code>Date</code> using the default
    123      *    <code>Locale</code> and <code>TimeZone</code>.
    124      *
    125      * @param value The value validation is being performed on.
    126      * @return The parsed <code>Date</code> if valid or <code>null</code>
    127      *  if invalid.
    128      */
    129     public Date validate(String value) {
    130         return (Date)parse(value, (String)null, (Locale)null, (TimeZone)null);
    131     }
    132
    133     /***
    134      * <p>Validate/convert a <code>Date</code> using the specified
    135      *    <code>TimeZone</code> and default <code>Locale</code>.
    136      *
    137      * @param value The value validation is being performed on.
    138      * @param timeZone The Time Zone used to parse the date, system default if null.
    139      * @return The parsed <code>Date</code> if valid or <code>null</code> if invalid.
    140      */
    141     public Date validate(String value, TimeZone timeZone) {
    142         return (Date)parse(value, (String)null, (Locale)null, timeZone);
    143     }
    144
    145     /***
    146      * <p>Validate/convert a <code>Date</code> using the specified
    147      *    <i>pattern</i> and default <code>TimeZone</code>.
    148      *
    149      * @param value The value validation is being performed on.
    150      * @param pattern The pattern used to validate the value against, or the
    151      *        default for the <code>Locale</code> if <code>null</code>.
    152      * @return The parsed <code>Date</code> if valid or <code>null</code> if invalid.
    153      */
    154     public Date validate(String value, String pattern) {
    155         return (Date)parse(value, pattern, (Locale)null, (TimeZone)null);
    156     }
    157
    158     /***
    159      * <p>Validate/convert a <code>Date</code> using the specified
    160      *    <i>pattern</i> 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, or the
    164      *        default for the <code>Locale</code> if <code>null</code>.
    165      * @param timeZone The Time Zone used to parse the date, system default if null.
    166      * @return The parsed <code>Date</code> if valid or <code>null</code> if invalid.
    167      */
    168     public Date validate(String value, String pattern, TimeZone timeZone) {
    169         return (Date)parse(value, pattern, (Locale)null, timeZone);
    170     }
    171
    172     /***
    173      * <p>Validate/convert a <code>Date</code> using the specified
    174      *    <code>Locale</code> and default <code>TimeZone</code>.
    175      *
    176      * @param value The value validation is being performed on.
    177      * @param locale The locale to use for the date format, system default if null.
    178      * @return The parsed <code>Date</code> if valid or <code>null</code> if invalid.
    179      */
    180     public Date validate(String value, Locale locale) {
    181         return (Date)parse(value, (String)null, locale, (TimeZone)null);
    182     }
    183
    184     /***
    185      * <p>Validate/convert a <code>Date</code> using the specified
    186      *    <code>Locale</code> and <code>TimeZone</code>.
    187      *
    188      * @param value The value validation is being performed on.
    189      * @param locale The locale to use for the date format, system default if null.
    190      * @param timeZone The Time Zone used to parse the date, system default if null.
    191      * @return The parsed <code>Date</code> if valid or <code>null</code> if invalid.
    192      */
    193     public Date validate(String value, Locale locale, TimeZone timeZone) {
    194         return (Date)parse(value, (String)null, locale, timeZone);
    195     }
    196
    197     /***
    198      * <p>Validate/convert a <code>Date</code> using the specified pattern
    199      *    and <code>Locale</code> 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>Date</code> if valid or <code>null</code> if invalid.
    206      */
    207     public Date validate(String value, String pattern, Locale locale) {
    208         return (Date)parse(value, pattern, locale, (TimeZone)null);
    209     }
    210
    211     /***
    212      * <p>Validate/convert a <code>Date</code> using the specified
    213      *    pattern, and <code>Locale</code> 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>Date</code> if valid or <code>null</code> if invalid.
    221      */
    222     public Date validate(String value, String pattern, Locale locale, TimeZone timeZone) {
    223         return (Date)parse(value, pattern, locale, timeZone);
    224     }
    225
    226     /***
    227      * <p>Compare Dates (day, month and year - not time).</p>
    228      *
    229      * @param value The <code>Calendar</code> value to check.
    230      * @param compare The <code>Calendar</code> to compare the value to.
    231      * @param timeZone The Time Zone used to compare the dates, system default if null.
    232      * @return Zero if the dates are equal, -1 if first
    233      * date is less than the seconds and +1 if the first
    234      * date is greater than.
    235      */
    236     public int compareDates(Date value, Date compare, TimeZone timeZone) {
    237         Calendar calendarValue   = getCalendar(value, timeZone);
    238         Calendar calendarCompare = getCalendar(compare, timeZone);
    239         return compare(calendarValue, calendarCompare, Calendar.DATE);
    240     }
    241
    242     /***
    243      * <p>Compare Weeks (week and year).</p>
    244      *
    245      * @param value The <code>Date</code> value to check.
    246      * @param compare The <code>Date</code> to compare the value to.
    247      * @param timeZone The Time Zone used to compare the dates, system default if null.
    248      * @return Zero if the weeks are equal, -1 if first
    249      * parameter's week is less than the seconds and +1 if the first
    250      * parameter's week is greater than.
    251      */
    252     public int compareWeeks(Date value, Date compare, TimeZone timeZone) {
    253         Calendar calendarValue   = getCalendar(value, timeZone);
    254         Calendar calendarCompare = getCalendar(compare, timeZone);
    255         return compare(calendarValue, calendarCompare, Calendar.WEEK_OF_YEAR);
    256     }
    257
    258     /***
    259      * <p>Compare Months (month and year).</p>
    260      *
    261      * @param value The <code>Date</code> value to check.
    262      * @param compare The <code>Date</code> to compare the value to.
    263      * @param timeZone The Time Zone used to compare the dates, system default if null.
    264      * @return Zero if the months are equal, -1 if first
    265      * parameter's month is less than the seconds and +1 if the first
    266      * parameter's month is greater than.
    267      */
    268     public int compareMonths(Date value, Date compare, TimeZone timeZone) {
    269         Calendar calendarValue   = getCalendar(value, timeZone);
    270         Calendar calendarCompare = getCalendar(compare, timeZone);
    271         return compare(calendarValue, calendarCompare, Calendar.MONTH);
    272     }
    273
    274     /***
    275      * <p>Compare Quarters (quarter and year).</p>
    276      *
    277      * @param value The <code>Date</code> value to check.
    278      * @param compare The <code>Date</code> to compare the value to.
    279      * @param timeZone The Time Zone used to compare the dates, system default if null.
    280      * @return Zero if the months are equal, -1 if first
    281      * parameter's quarter is less than the seconds and +1 if the first
    282      * parameter's quarter is greater than.
    283      */
    284     public int compareQuarters(Date value, Date compare, TimeZone timeZone) {
    285         return compareQuarters(value, compare, timeZone, 1);
    286     }
    287
    288     /***
    289      * <p>Compare Quarters (quarter and year).</p>
    290      *
    291      * @param value The <code>Date</code> value to check.
    292      * @param compare The <code>Date</code> to compare the value to.
    293      * @param timeZone The Time Zone used to compare the dates, system default if null.
    294      * @param monthOfFirstQuarter The  month that the first quarter starts.
    295      * @return Zero if the quarters are equal, -1 if first
    296      * parameter's quarter is less than the seconds and +1 if the first
    297      * parameter's quarter is greater than.
    298      */
    299     public int compareQuarters(Date value, Date compare, TimeZone timeZone, int monthOfFirstQuarter) {
    300         Calendar calendarValue   = getCalendar(value, timeZone);
    301         Calendar calendarCompare = getCalendar(compare, timeZone);
    302         return super.compareQuarters(calendarValue, calendarCompare, monthOfFirstQuarter);
    303     }
    304
    305     /***
    306      * <p>Compare Years.</p>
    307      *
    308      * @param value The <code>Date</code> value to check.
    309      * @param compare The <code>Date</code> to compare the value to.
    310      * @param timeZone The Time Zone used to compare the dates, system default if null.
    311      * @return Zero if the years are equal, -1 if first
    312      * parameter's year is less than the seconds and +1 if the first
    313      * parameter's year is greater than.
    314      */
    315     public int compareYears(Date value, Date compare, TimeZone timeZone) {
    316         Calendar calendarValue   = getCalendar(value, timeZone);
    317         Calendar calendarCompare = getCalendar(compare, timeZone);
    318         return compare(calendarValue, calendarCompare, Calendar.YEAR);
    319     }
    320
    321     /***
    322      * <p>Returns the parsed <code>Date</code> unchanged.</p>
    323      *
    324      * @param value The parsed <code>Date</code> object created.
    325      * @param formatter The Format used to parse the value with.
    326      * @return The parsed value converted to a <code>Calendar</code>.
    327      */
    328     protected Object processParsedValue(Object value, Format formatter) {
    329         return value;
    330     }
    331
    332     /***
    333      * <p>Convert a <code>Date</code> to a <code>Calendar</code>.</p>
    334      *
    335      * @param value The date value to be converted.
    336      * @return The converted <code>Calendar</code>.
    337      */
    338     private Calendar getCalendar(Date value, TimeZone timeZone) {
    339
    340         Calendar calendar = null;
    341         if (timeZone != null) {
    342             calendar = Calendar.getInstance(timeZone);
    343         } else {
    344             calendar = Calendar.getInstance();
    345         }
    346         calendar.setTime(value);
    347         return calendar;
    348
    349     }
    350
    351 }