View Javadoc

    1   /*
    2    * $Id: TimeValidator.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
    22  package org.apache.commons.validator.routines;
    23
    24  import java.text.DateFormat;
    25  import java.text.Format;
    26  import java.util.Calendar;
    27  import java.util.Locale;
    28  import java.util.TimeZone;
    29
    30  /***
    31   * <p><b>Time Validation</b> and Conversion routines (<code>java.util.Calendar</code>).</p>
    32   *
    33   * <p>This validator provides a number of methods for validating/converting
    34   *    a <code>String</code> time value to a <code>java.util.Calendar</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>Calendar</code> value for the time.</p>
    51   *
    52   * <p>Implementations of the <code>validate()</code> method are provided
    53   *    to create <code>Calendar</code> objects for different <i>time zones</i>
    54   *    if the system default is not appropriate.</p>
    55   *
    56   * <p>Alternatively the CalendarValidator's <code>adjustToTimeZone()</code> method
    57   *    can be used to adjust the <code>TimeZone</code> of the <code>Calendar</code>
    58   *    object afterwards.</p>
    59   *
    60   * <p>Once a value has been sucessfully converted the following
    61   *    methods can be used to perform various time comparison checks:</p>
    62   *    <ul>
    63   *       <li><code>compareTime()</code> compares the hours, minutes, seconds
    64   *           and milliseconds of two calendars, returing 0, -1 or +1 indicating
    65   *           whether the first time is equal, before or after the second.</li>
    66   *       <li><code>compareSeconds()</code> compares the hours, minutes and
    67   *           seconds of two times, returing 0, -1 or +1 indicating
    68   *           whether the first is equal to, before or after the second.</li>
    69   *       <li><code>compareMinutes()</code> compares the hours and minutes
    70   *           two times, returing 0, -1 or +1 indicating
    71   *           whether the first is equal to, before or after the second.</li>
    72   *       <li><code>compareHours()</code> compares the hours
    73   *           of two times, returing 0, -1 or +1 indicating
    74   *           whether the first is equal to, before or after the second.</li>
    75   *    </ul>
    76   *
    77   * <p>So that the same mechanism used for parsing an <i>input</i> value
    78   *    for validation can be used to format <i>output</i>, corresponding
    79   *    <code>format()</code> methods are also provided. That is you can
    80   *    format either:</p>
    81   *    <ul>
    82   *       <li>using a specified pattern</li>
    83   *       <li>using the format for a specified <code>Locale</code></li>
    84   *       <li>using the format for the <i>default</i> <code>Locale</code></li>
    85   *    </ul>
    86   *
    87   * @version $Revision: 386637 $ $Date: 2006-03-17 13:22:26 +0000 (Fri, 17 Mar 2006) $
    88   * @since Validator 1.3.0
    89   */
    90  public class TimeValidator extends AbstractCalendarValidator {
    91
    92      private static final TimeValidator VALIDATOR = new TimeValidator();
    93
    94      /***
    95       * Return a singleton instance of this validator.
    96       * @return A singleton instance of the TimeValidator.
    97       */
    98      public static TimeValidator getInstance() {
    99          return VALIDATOR;
    100     }
    101
    102     /***
    103      * Construct a <i>strict</i> instance with <i>short</i>
    104      * time style.
    105      */
    106     public TimeValidator() {
    107         this(true, DateFormat.SHORT);
    108     }
    109
    110     /***
    111      * Construct an instance with the specified <i>strict</i>
    112      * and <i>time style</i> parameters.
    113      *
    114      * @param strict <code>true</code> if strict
    115      *        <code>Format</code> parsing should be used.
    116      * @param timeStyle the time style to use for Locale validation.
    117      */
    118     public TimeValidator(boolean strict, int timeStyle) {
    119         super(strict, -1, timeStyle);
    120     }
    121
    122     /***
    123      * <p>Validate/convert a time using the default <code>Locale</code>
    124      *    and <code>TimeZone</code>.
    125      *
    126      * @param value The value validation is being performed on.
    127      * @return The parsed <code>Calendar</code> if valid or <code>null</code>
    128      *  if invalid.
    129      */
    130     public Calendar validate(String value) {
    131         return (Calendar)parse(value, (String)null, (Locale)null, (TimeZone)null);
    132     }
    133
    134     /***
    135      * <p>Validate/convert a time using the specified <code>TimeZone</code>
    136      *    and default <code>Locale</code>.
    137      *
    138      * @param value The value validation is being performed on.
    139      * @param timeZone The Time Zone used to parse the time, system default if null.
    140      * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
    141      */
    142     public Calendar validate(String value, TimeZone timeZone) {
    143         return (Calendar)parse(value, (String)null, (Locale)null, timeZone);
    144     }
    145
    146     /***
    147      * <p>Validate/convert a time using the specified <i>pattern</i> and
    148      *    default <code>TimeZone</code>.
    149      *
    150      * @param value The value validation is being performed on.
    151      * @param pattern The pattern used to validate the value against.
    152      * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
    153      */
    154     public Calendar validate(String value, String pattern) {
    155         return (Calendar)parse(value, pattern, (Locale)null, (TimeZone)null);
    156     }
    157
    158     /***
    159      * <p>Validate/convert a time using the specified <i>pattern</i>
    160      *    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.
    164      * @param timeZone The Time Zone used to parse the time, system default if null.
    165      * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
    166      */
    167     public Calendar validate(String value, String pattern, TimeZone timeZone) {
    168         return (Calendar)parse(value, pattern, (Locale)null, timeZone);
    169     }
    170
    171     /***
    172      * <p>Validate/convert a time using the specified <code>Locale</code>
    173      *    default <code>TimeZone</code>.
    174      *
    175      * @param value The value validation is being performed on.
    176      * @param locale The locale to use for the time format, system default if null.
    177      * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
    178      */
    179     public Calendar validate(String value, Locale locale) {
    180         return (Calendar)parse(value, (String)null, locale, (TimeZone)null);
    181     }
    182
    183     /***
    184      * <p>Validate/convert a time using the specified specified <code>Locale</code>
    185      *    and <code>TimeZone</code>.
    186      *
    187      * @param value The value validation is being performed on.
    188      * @param locale The locale to use for the time format, system default if null.
    189      * @param timeZone The Time Zone used to parse the time, system default if null.
    190      * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
    191      */
    192     public Calendar validate(String value, Locale locale, TimeZone timeZone) {
    193         return (Calendar)parse(value, (String)null, locale, timeZone);
    194     }
    195
    196     /***
    197      * <p>Validate/convert a time using the specified pattern and <code>Locale</code>
    198      *    and the default <code>TimeZone</code>.
    199      *
    200      * @param value The value validation is being performed on.
    201      * @param pattern The pattern used to validate the value against, or the
    202      *        default for the <code>Locale</code> if <code>null</code>.
    203      * @param locale The locale to use for the date format, system default if null.
    204      * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
    205      */
    206     public Calendar validate(String value, String pattern, Locale locale) {
    207         return (Calendar)parse(value, pattern, locale, (TimeZone)null);
    208     }
    209
    210     /***
    211      * <p>Validate/convert a time using the specified pattern, <code>Locale</code>
    212      *    and <code>TimeZone</code>.
    213      *
    214      * @param value The value validation is being performed on.
    215      * @param pattern The pattern used to validate the value against, or the
    216      *        default for the <code>Locale</code> if <code>null</code>.
    217      * @param locale The locale to use for the date format, system default if null.
    218      * @param timeZone The Time Zone used to parse the date, system default if null.
    219      * @return The parsed <code>Calendar</code> if valid or <code>null</code> if invalid.
    220      */
    221     public Calendar validate(String value, String pattern, Locale locale, TimeZone timeZone) {
    222         return (Calendar)parse(value, pattern, locale, timeZone);
    223     }
    224
    225     /***
    226      * <p>Compare Times (hour, minute, second and millisecond - not date).</p>
    227      *
    228      * @param value The <code>Calendar</code> value to check.
    229      * @param compare The <code>Calendar</code> to compare the value to.
    230      * @return Zero if the hours are equal, -1 if first
    231      * time is less than the seconds and +1 if the first
    232      * time is greater than.
    233      */
    234     public int compareTime(Calendar value, Calendar compare) {
    235         return compareTime(value, compare, Calendar.MILLISECOND);
    236     }
    237
    238     /***
    239      * <p>Compare Seconds (hours, minutes and seconds).</p>
    240      *
    241      * @param value The <code>Calendar</code> value to check.
    242      * @param compare The <code>Calendar</code> to compare the value to.
    243      * @return Zero if the hours are equal, -1 if first
    244      * parameter's seconds are less than the seconds and +1 if the first
    245      * parameter's seconds are greater than.
    246      */
    247     public int compareSeconds(Calendar value, Calendar compare) {
    248         return compareTime(value, compare, Calendar.SECOND);
    249     }
    250
    251     /***
    252      * <p>Compare Minutes (hours and minutes).</p>
    253      *
    254      * @param value The <code>Calendar</code> value to check.
    255      * @param compare The <code>Calendar</code> to compare the value to.
    256      * @return Zero if the hours are equal, -1 if first
    257      * parameter's minutes are less than the seconds and +1 if the first
    258      * parameter's minutes are greater than.
    259      */
    260     public int compareMinutes(Calendar value, Calendar compare) {
    261         return compareTime(value, compare, Calendar.MINUTE);
    262     }
    263
    264     /***
    265      * <p>Compare Hours.</p>
    266      *
    267      * @param value The <code>Calendar</code> value to check.
    268      * @param compare The <code>Calendar</code> to compare the value to.
    269      * @return Zero if the hours are equal, -1 if first
    270      * parameter's hour is less than the seconds and +1 if the first
    271      * parameter's hour is greater than.
    272      */
    273     public int compareHours(Calendar value, Calendar compare) {
    274         return compareTime(value, compare, Calendar.HOUR_OF_DAY);
    275     }
    276
    277     /***
    278      * <p>Convert the parsed <code>Date</code> to a <code>Calendar</code>.</p>
    279      *
    280      * @param value The parsed <code>Date</code> object created.
    281      * @param formatter The Format used to parse the value with.
    282      * @return The parsed value converted to a <code>Calendar</code>.
    283      */
    284     protected Object processParsedValue(Object value, Format formatter) {
    285         return ((DateFormat)formatter).getCalendar();
    286     }
    287 }