org.apache.commons.validator.routines.TimeValidator Maven / Gradle / Ivy
Show all versions of commons-validator Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.validator.routines;
import java.text.DateFormat;
import java.text.Format;
import java.util.Calendar;
import java.util.Locale;
import java.util.TimeZone;
/**
* Time Validation and Conversion routines (java.util.Calendar).
*
* This validator provides a number of methods for validating/converting
* a String time value to a java.util.Calendar using
* java.text.DateFormat to parse either:
*
* - using the default format for the default
Locale
* - using a specified pattern with the default
Locale
* - using the default format for a specified
Locale
* - using a specified pattern with a specified
Locale
*
*
* For each of the above mechanisms, conversion method (i.e the
* validate methods) implementations are provided which
* either use the default TimeZone or allow the
* TimeZone to be specified.
*
* Use one of the isValid() methods to just validate or
* one of the validate() methods to validate and receive a
* converted Calendar value for the time.
*
* Implementations of the validate() method are provided
* to create Calendar objects for different time zones
* if the system default is not appropriate.
*
* Alternatively the CalendarValidator's adjustToTimeZone() method
* can be used to adjust the TimeZone of the Calendar
* object afterwards.
*
* Once a value has been successfully converted the following
* methods can be used to perform various time comparison checks:
*
* compareTime() compares the hours, minutes, seconds
* and milliseconds of two calendars, returning 0, -1 or +1 indicating
* whether the first time is equal, before or after the second.compareSeconds() compares the hours, minutes and
* seconds of two times, returning 0, -1 or +1 indicating
* whether the first is equal to, before or after the second.compareMinutes() compares the hours and minutes
* two times, returning 0, -1 or +1 indicating
* whether the first is equal to, before or after the second.compareHours() compares the hours
* of two times, returning 0, -1 or +1 indicating
* whether the first is equal to, before or after the second.
*
* So that the same mechanism used for parsing an input value
* for validation can be used to format output, corresponding
* format() methods are also provided. That is you can
* format either:
*
* - using a specified pattern
* - using the format for a specified
Locale
* - using the format for the default
Locale
*
*
* @version $Revision: 1739356 $
* @since Validator 1.3.0
*/
public class TimeValidator extends AbstractCalendarValidator {
private static final long serialVersionUID = 3494007492269691581L;
private static final TimeValidator VALIDATOR = new TimeValidator();
/**
* Return a singleton instance of this validator.
* @return A singleton instance of the TimeValidator.
*/
public static TimeValidator getInstance() {
return VALIDATOR;
}
/**
* Construct a strict instance with short
* time style.
*/
public TimeValidator() {
this(true, DateFormat.SHORT);
}
/**
* Construct an instance with the specified strict
* and time style parameters.
*
* @param strict true if strict
* Format parsing should be used.
* @param timeStyle the time style to use for Locale validation.
*/
public TimeValidator(boolean strict, int timeStyle) {
super(strict, -1, timeStyle);
}
/**
* Validate/convert a time using the default Locale
* and TimeZone.
*
* @param value The value validation is being performed on.
* @return The parsed Calendar if valid or null
* if invalid.
*/
public Calendar validate(String value) {
return (Calendar)parse(value, (String)null, (Locale)null, (TimeZone)null);
}
/**
*
Validate/convert a time using the specified TimeZone
* and default Locale.
*
* @param value The value validation is being performed on.
* @param timeZone The Time Zone used to parse the time, system default if null.
* @return The parsed Calendar if valid or null if invalid.
*/
public Calendar validate(String value, TimeZone timeZone) {
return (Calendar)parse(value, (String)null, (Locale)null, timeZone);
}
/**
*
Validate/convert a time using the specified pattern and
* default TimeZone.
*
* @param value The value validation is being performed on.
* @param pattern The pattern used to validate the value against.
* @return The parsed Calendar if valid or null if invalid.
*/
public Calendar validate(String value, String pattern) {
return (Calendar)parse(value, pattern, (Locale)null, (TimeZone)null);
}
/**
*
Validate/convert a time using the specified pattern
* and TimeZone.
*
* @param value The value validation is being performed on.
* @param pattern The pattern used to validate the value against.
* @param timeZone The Time Zone used to parse the time, system default if null.
* @return The parsed Calendar if valid or null if invalid.
*/
public Calendar validate(String value, String pattern, TimeZone timeZone) {
return (Calendar)parse(value, pattern, (Locale)null, timeZone);
}
/**
*
Validate/convert a time using the specified Locale
* default TimeZone.
*
* @param value The value validation is being performed on.
* @param locale The locale to use for the time format, system default if null.
* @return The parsed Calendar if valid or null if invalid.
*/
public Calendar validate(String value, Locale locale) {
return (Calendar)parse(value, (String)null, locale, (TimeZone)null);
}
/**
*
Validate/convert a time using the specified specified Locale
* and TimeZone.
*
* @param value The value validation is being performed on.
* @param locale The locale to use for the time format, system default if null.
* @param timeZone The Time Zone used to parse the time, system default if null.
* @return The parsed Calendar if valid or null if invalid.
*/
public Calendar validate(String value, Locale locale, TimeZone timeZone) {
return (Calendar)parse(value, (String)null, locale, timeZone);
}
/**
*
Validate/convert a time using the specified pattern and Locale
* and the default TimeZone.
*
* @param value The value validation is being performed on.
* @param pattern The pattern used to validate the value against, or the
* default for the Locale if null.
* @param locale The locale to use for the date format, system default if null.
* @return The parsed Calendar if valid or null if invalid.
*/
public Calendar validate(String value, String pattern, Locale locale) {
return (Calendar)parse(value, pattern, locale, (TimeZone)null);
}
/**
*
Validate/convert a time using the specified pattern, Locale
* and TimeZone.
*
* @param value The value validation is being performed on.
* @param pattern The pattern used to validate the value against, or the
* default for the Locale if null.
* @param locale The locale to use for the date format, system default if null.
* @param timeZone The Time Zone used to parse the date, system default if null.
* @return The parsed Calendar if valid or null if invalid.
*/
public Calendar validate(String value, String pattern, Locale locale, TimeZone timeZone) {
return (Calendar)parse(value, pattern, locale, timeZone);
}
/**
*
Compare Times (hour, minute, second and millisecond - not date).
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @return Zero if the hours are equal, -1 if first
* time is less than the seconds and +1 if the first
* time is greater than.
*/
public int compareTime(Calendar value, Calendar compare) {
return compareTime(value, compare, Calendar.MILLISECOND);
}
/**
* Compare Seconds (hours, minutes and seconds).
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @return Zero if the hours are equal, -1 if first
* parameter's seconds are less than the seconds and +1 if the first
* parameter's seconds are greater than.
*/
public int compareSeconds(Calendar value, Calendar compare) {
return compareTime(value, compare, Calendar.SECOND);
}
/**
* Compare Minutes (hours and minutes).
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @return Zero if the hours are equal, -1 if first
* parameter's minutes are less than the seconds and +1 if the first
* parameter's minutes are greater than.
*/
public int compareMinutes(Calendar value, Calendar compare) {
return compareTime(value, compare, Calendar.MINUTE);
}
/**
* Compare Hours.
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @return Zero if the hours are equal, -1 if first
* parameter's hour is less than the seconds and +1 if the first
* parameter's hour is greater than.
*/
public int compareHours(Calendar value, Calendar compare) {
return compareTime(value, compare, Calendar.HOUR_OF_DAY);
}
/**
* Convert the parsed Date to a Calendar.
*
* @param value The parsed Date object created.
* @param formatter The Format used to parse the value with.
* @return The parsed value converted to a Calendar.
*/
@Override
protected Object processParsedValue(Object value, Format formatter) {
return ((DateFormat)formatter).getCalendar();
}
}