org.apache.commons.validator.routines.CalendarValidator 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;
/**
* Calendar Validation and Conversion routines (java.util.Calendar).
*
* This validator provides a number of methods for validating/converting
* a String date 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.
*
* 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 date comparison checks:
*
* compareDates() compares the day, month and
* year of two calendars, 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 calendars, 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 calendars, 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 calendars, returning 0, -1 or +1 indicating
* whether the first quarter is equal, before or after the second.compareYears() compares the
* year of two calendars, 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: 1739356 $
* @since Validator 1.3.0
*/
public class CalendarValidator extends AbstractCalendarValidator {
private static final long serialVersionUID = 9109652318762134167L;
private static final CalendarValidator VALIDATOR = new CalendarValidator();
/**
* Return a singleton instance of this validator.
* @return A singleton instance of the CalendarValidator.
*/
public static CalendarValidator getInstance() {
return VALIDATOR;
}
/**
* Construct a strict instance with short
* date style.
*/
public CalendarValidator() {
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 CalendarValidator(boolean strict, int dateStyle) {
super(strict, dateStyle, -1);
}
/**
* Validate/convert a Calendar 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 Calendar 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 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 Calendar 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 Calendar 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 date, 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 Calendar 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 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 Calendar 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 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 Calendar 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 Calendar 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 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);
}
/**
*
Adjusts a Calendar's value to a different TimeZone.
*
* @param value The value to adjust.
* @param timeZone The new time zone to use to adjust the Calendar to.
*/
public static void adjustToTimeZone(Calendar value, TimeZone timeZone) {
if (value.getTimeZone().hasSameRules(timeZone)) {
value.setTimeZone(timeZone);
} else {
int year = value.get(Calendar.YEAR);
int month = value.get(Calendar.MONTH);
int date = value.get(Calendar.DATE);
int hour = value.get(Calendar.HOUR_OF_DAY);
int minute = value.get(Calendar.MINUTE);
value.setTimeZone(timeZone);
value.set(year, month, date, hour, minute);
}
}
/**
* Compare Dates (day, month and year - not time).
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @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(Calendar value, Calendar compare) {
return compare(value, compare, Calendar.DATE);
}
/**
* Compare Weeks (week and year).
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @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(Calendar value, Calendar compare) {
return compare(value, compare, Calendar.WEEK_OF_YEAR);
}
/**
* Compare Months (month and year).
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @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(Calendar value, Calendar compare) {
return compare(value, compare, Calendar.MONTH);
}
/**
* Compare Quarters (quarter and year).
*
* @param value The Calendar value to check.
* @param compare The Calendar to check the value against.
* @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(Calendar value, Calendar compare) {
return compareQuarters(value, compare, 1);
}
/**
* Compare Quarters (quarter and year).
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @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.
*/
@Override
public int compareQuarters(Calendar value, Calendar compare, int monthOfFirstQuarter) {
return super.compareQuarters(value, compare, monthOfFirstQuarter);
}
/**
* Compare Years.
*
* @param value The Calendar value to check.
* @param compare The Calendar to compare the value to.
* @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(Calendar value, Calendar compare) {
return compare(value, compare, Calendar.YEAR);
}
/**
* 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();
}
}