org.apache.commons.validator.routines.DateValidator Maven / Gradle / Ivy
/*
* 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.Date;
import java.util.Locale;
import java.util.TimeZone;
/**
* Date Validation and Conversion routines (java.util.Date
).
*
* This validator provides a number of methods for validating/converting
* a String
date value to a java.util.Date
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 Date
value.
*
* Implementations of the validate()
method are provided
* to create Date
objects for different time zones
* if the system default is not appropriate.
*
* Once a value has been successfully converted the following
* methods can be used to perform various date comparison checks:
*
* compareDates()
compares the day, month and
* year of two dates, returning 0, -1 or +1 indicating
* whether the first date is equal, before or after the second.
* compareWeeks()
compares the week and
* year of two dates, returning 0, -1 or +1 indicating
* whether the first week is equal, before or after the second.
* compareMonths()
compares the month and
* year of two dates, returning 0, -1 or +1 indicating
* whether the first month is equal, before or after the second.
* compareQuarters()
compares the quarter and
* year of two dates, returning 0, -1 or +1 indicating
* whether the first quarter is equal, before or after the second.
* compareYears()
compares the
* year of two dates, returning 0, -1 or +1 indicating
* whether the first year is equal, 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$
* @since Validator 1.3.0
*/
public class DateValidator extends AbstractCalendarValidator {
private static final long serialVersionUID = -3966328400469953190L;
private static final DateValidator VALIDATOR = new DateValidator();
/**
* Return a singleton instance of this validator.
* @return A singleton instance of the DateValidator.
*/
public static DateValidator getInstance() {
return VALIDATOR;
}
/**
* Construct a strict instance with short
* date style.
*/
public DateValidator() {
this(true, DateFormat.SHORT);
}
/**
* Construct an instance with the specified strict
* and date style parameters.
*
* @param strict true
if strict
* Format
parsing should be used.
* @param dateStyle the date style to use for Locale validation.
*/
public DateValidator(boolean strict, int dateStyle) {
super(strict, dateStyle, -1);
}
/**
* Validate/convert a Date
using the default
* Locale
and TimeZone
.
*
* @param value The value validation is being performed on.
* @return The parsed Date
if valid or null
* if invalid.
*/
public Date validate(String value) {
return (Date)parse(value, (String)null, (Locale)null, (TimeZone)null);
}
/**
*
Validate/convert a Date
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 date, system default if null.
* @return The parsed Date
if valid or null
if invalid.
*/
public Date validate(String value, TimeZone timeZone) {
return (Date)parse(value, (String)null, (Locale)null, timeZone);
}
/**
*
Validate/convert a Date
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, or the
* default for the Locale
if null
.
* @return The parsed Date
if valid or null
if invalid.
*/
public Date validate(String value, String pattern) {
return (Date)parse(value, pattern, (Locale)null, (TimeZone)null);
}
/**
*
Validate/convert a Date
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, or the
* default for the Locale
if null
.
* @param timeZone The Time Zone used to parse the date, system default if null.
* @return The parsed Date
if valid or null
if invalid.
*/
public Date validate(String value, String pattern, TimeZone timeZone) {
return (Date)parse(value, pattern, (Locale)null, timeZone);
}
/**
*
Validate/convert a Date
using the specified
* Locale
and default TimeZone
.
*
* @param value The value validation is being performed on.
* @param locale The locale to use for the date format, system default if null.
* @return The parsed Date
if valid or null
if invalid.
*/
public Date validate(String value, Locale locale) {
return (Date)parse(value, (String)null, locale, (TimeZone)null);
}
/**
*
Validate/convert a Date
using the specified
* Locale
and TimeZone
.
*
* @param value The value validation is being performed on.
* @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 Date
if valid or null
if invalid.
*/
public Date validate(String value, Locale locale, TimeZone timeZone) {
return (Date)parse(value, (String)null, locale, timeZone);
}
/**
*
Validate/convert a Date
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 Date
if valid or null
if invalid.
*/
public Date validate(String value, String pattern, Locale locale) {
return (Date)parse(value, pattern, locale, (TimeZone)null);
}
/**
*
Validate/convert a Date
using the specified
* pattern, and 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 Date
if valid or null
if invalid.
*/
public Date validate(String value, String pattern, Locale locale, TimeZone timeZone) {
return (Date)parse(value, pattern, locale, timeZone);
}
/**
*
Compare Dates (day, month and year - not time).
*
* @param value The Calendar
value to check.
* @param compare The Calendar
to compare the value to.
* @param timeZone The Time Zone used to compare the dates, system default if null.
* @return Zero if the dates are equal, -1 if first
* date is less than the seconds and +1 if the first
* date is greater than.
*/
public int compareDates(Date value, Date compare, TimeZone timeZone) {
Calendar calendarValue = getCalendar(value, timeZone);
Calendar calendarCompare = getCalendar(compare, timeZone);
return compare(calendarValue, calendarCompare, Calendar.DATE);
}
/**
* Compare Weeks (week and year).
*
* @param value The Date
value to check.
* @param compare The Date
to compare the value to.
* @param timeZone The Time Zone used to compare the dates, system default if null.
* @return Zero if the weeks are equal, -1 if first
* parameter's week is less than the seconds and +1 if the first
* parameter's week is greater than.
*/
public int compareWeeks(Date value, Date compare, TimeZone timeZone) {
Calendar calendarValue = getCalendar(value, timeZone);
Calendar calendarCompare = getCalendar(compare, timeZone);
return compare(calendarValue, calendarCompare, Calendar.WEEK_OF_YEAR);
}
/**
* Compare Months (month and year).
*
* @param value The Date
value to check.
* @param compare The Date
to compare the value to.
* @param timeZone The Time Zone used to compare the dates, system default if null.
* @return Zero if the months are equal, -1 if first
* parameter's month is less than the seconds and +1 if the first
* parameter's month is greater than.
*/
public int compareMonths(Date value, Date compare, TimeZone timeZone) {
Calendar calendarValue = getCalendar(value, timeZone);
Calendar calendarCompare = getCalendar(compare, timeZone);
return compare(calendarValue, calendarCompare, Calendar.MONTH);
}
/**
* Compare Quarters (quarter and year).
*
* @param value The Date
value to check.
* @param compare The Date
to compare the value to.
* @param timeZone The Time Zone used to compare the dates, system default if null.
* @return Zero if the months are equal, -1 if first
* parameter's quarter is less than the seconds and +1 if the first
* parameter's quarter is greater than.
*/
public int compareQuarters(Date value, Date compare, TimeZone timeZone) {
return compareQuarters(value, compare, timeZone, 1);
}
/**
* Compare Quarters (quarter and year).
*
* @param value The Date
value to check.
* @param compare The Date
to compare the value to.
* @param timeZone The Time Zone used to compare the dates, system default if null.
* @param monthOfFirstQuarter The month that the first quarter starts.
* @return Zero if the quarters are equal, -1 if first
* parameter's quarter is less than the seconds and +1 if the first
* parameter's quarter is greater than.
*/
public int compareQuarters(Date value, Date compare, TimeZone timeZone, int monthOfFirstQuarter) {
Calendar calendarValue = getCalendar(value, timeZone);
Calendar calendarCompare = getCalendar(compare, timeZone);
return super.compareQuarters(calendarValue, calendarCompare, monthOfFirstQuarter);
}
/**
* Compare Years.
*
* @param value The Date
value to check.
* @param compare The Date
to compare the value to.
* @param timeZone The Time Zone used to compare the dates, system default if null.
* @return Zero if the years are equal, -1 if first
* parameter's year is less than the seconds and +1 if the first
* parameter's year is greater than.
*/
public int compareYears(Date value, Date compare, TimeZone timeZone) {
Calendar calendarValue = getCalendar(value, timeZone);
Calendar calendarCompare = getCalendar(compare, timeZone);
return compare(calendarValue, calendarCompare, Calendar.YEAR);
}
/**
* Returns the parsed Date
unchanged.
*
* @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 value;
}
/**
* Convert a Date
to a Calendar
.
*
* @param value The date value to be converted.
* @return The converted Calendar
.
*/
private Calendar getCalendar(Date value, TimeZone timeZone) {
Calendar calendar = null;
if (timeZone != null) {
calendar = Calendar.getInstance(timeZone);
} else {
calendar = Calendar.getInstance();
}
calendar.setTime(value);
return calendar;
}
}