View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.validator.routines;
    18
    19  import java.text.DateFormat;
    20  import java.text.Format;
    21  import java.util.Calendar;
    22  import java.util.Locale;
    23  import java.util.TimeZone;
    24
    25  /***
    26   * <p><b>Time Validation</b> and Conversion routines (<code>java.util.Calendar</code>).</p>
    27   *
    28   * <p>This validator provides a number of methods for validating/converting
    29   *    a <code>String</code> time value to a <code>java.util.Calendar</code> using
    30   *    <code>java.text.DateFormat</code> to parse either:</p>
    31   *    <ul>
    32   *       <li>using the default format for the default <code>Locale</code></li>
    33   *       <li>using a specified pattern with the default <code>Locale</code></li>
    34   *       <li>using the default format for a specified <code>Locale</code></li>
    35   *       <li>using a specified pattern with a specified <code>Locale</code></li>
    36   *    </ul>
    37   *
    38   * <p>For each of the above mechanisms, conversion method (i.e the
    39   *    <code>validate</code> methods) implementations are provided which
    40   *    either use the default <code>TimeZone</code> or allow the
    41   *    <code>TimeZone</code> to be specified.</p>
    42   *
    43   * <p>Use one of the <code>isValid()</code> methods to just validate or
    44   *    one of the <code>validate()</code> methods to validate and receive a
    45   *    <i>converted</i> <code>Calendar</code> value for the time.</p>
    46   *
    47   * <p>Implementations of the <code>validate()</code> method are provided
    48   *    to create <code>Calendar</code> objects for different <i>time zones</i>
    49   *    if the system default is not appropriate.</p>
    50   *
    51   * <p>Alternatively the CalendarValidator's <code>adjustToTimeZone()</code> method
    52   *    can be used to adjust the <code>TimeZone</code> of the <code>Calendar</code>
    53   *    object afterwards.</p>
    54   *
    55   * <p>Once a value has been sucessfully converted the following
    56   *    methods can be used to perform various time comparison checks:</p>
    57   *    <ul>
    58   *       <li><code>compareTime()</code> compares the hours, minutes, seconds
    59   *           and milliseconds of two calendars, returing 0, -1 or +1 indicating
    60   *           whether the first time is equal, before or after the second.</li>
    61   *       <li><code>compareSeconds()</code> compares the hours, minutes and
    62   *           seconds of two times, returing 0, -1 or +1 indicating
    63   *           whether the first is equal to, before or after the second.</li>
    64   *       <li><code>compareMinutes()</code> compares the hours and minutes
    65   *           two times, returing 0, -1 or +1 indicating
    66   *           whether the first is equal to, before or after the second.</li>
    67   *       <li><code>compareHours()</code> compares the hours
    68   *           of two times, returing 0, -1 or +1 indicating
    69   *           whether the first is equal to, before or after the second.</li>
    70   *    </ul>
    71   *
    72   * <p>So that the same mechanism used for parsing an <i>input</i> value
    73   *    for validation can be used to format <i>output</i>, corresponding
    74   *    <code>format()</code> methods are also provided. That is you can
    75   *    format either:</p>
    76   *    <ul>
    77   *       <li>using a specified pattern</li>
    78   *       <li>using the format for a specified <code>Locale</code></li>
    79   *       <li>using the format for the <i>default</i> <code>Locale</code></li>
    80   *    </ul>
    81   *
    82   * @version $Revision: 478334 $ $Date: 2006-11-22 21:31:54 +0000 (Wed, 22 Nov 2006) $
    83   * @since Validator 1.3.0
    84   */
    85  public class TimeValidator extends AbstractCalendarValidator {
    86
    87      private static final TimeValidator VALIDATOR = new TimeValidator();
    88
    89      /***
    90       * Return a singleton instance of this validator.
    91       * @return A singleton instance of the TimeValidator.
    92       */
    93      public static TimeValidator getInstance() {
    94          return VALIDATOR;
    95      }
    96
    97      /***
    98       * Construct a <i>strict</i> instance with <i>short</i>
    99       * 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 }