This package contains
independant validation routines.
Table of Contents
2. Numeric Validators
1. Overview
Commons Validator serves two purposes:
- To provide standard, independant validation routines/functions.
- To provide a mini framework for Validation.
This package has been created, since version 1.3.0, in an attempt to clearly
separate these two concerns and is the location for the standard, independant
validation routines/functions in
Commons Validator.
The contents of this package have no dependencies on the framework aspect of
Commons Validator and can be used on their own.
2. Date and Time Validators
2.1 Overview
The date and time validators either validate according to a specified
format
or use a standard
format for a specified
Locale
.
2.2 Validating a Date Value
You can either use one of the
isValid()
methods to just determine
if a date is valid, or use one of the
validate()
methods to
validate a date and convert it to a
java.util.Date
...
// Get the Date validator
DateValidator validator = DateValidator.getInstance();
// Validate/Convert the date
Date fooDate = validator.validate(fooString, "dd/MM/yyyy");
if (fooDate == null) {
// error...not a valid date
return;
}
The following methods are provided to validate a date/time (return a boolean result):
isValid(value)
isValid(value, pattern)
isValid(value, Locale)
isValid(value, pattern, Locale)
The following methods are provided to validate a date/time and convert it to either a
java.util.Date
or
java.util.Calendar
:
validate(value)
validate(value, pattern)
validate(value, Locale)
validate(value, pattern, Locale)
2.3 Formatting
Formatting and validating are two sides of the same coin. Typically
input values which are converted from Strings according to a
specified
format also have to be rendered for
output in
the same format. These validators provide the mechanism for formatting from
date/time objects to Strings. The following methods are provided to format
date/time values as Strings:
format(date/calendar)
format(date/calendar, pattern)
format(date/calendar, Locale)
format(date/calendar, pattern, Locale)
2.4 Time Zones
If the date being parsed relates to a different time zone than the
system default, you can specify the
TimeZone
to use when
validating/converting:
// Get the GMT time zone
TimeZone GMT = TimeZone.getInstance("GMT");
// Validate/Convert the date using GMT
Date fooDate = validator.validate(fooString, "dd/MM/yyyy", GMT);
The followng Time Zone
flavours of the Validation/Conversion methods
are provided:
validate(value, TimeZone)
validate(value, pattern, TimeZone)
validate(value, Locale, TimeZone)
validate(value, pattern, Locale, TimeZone)
2.5 Comparing Dates and Times
As well as validating that a value is a valid date or time, these validators
also provide
date comparison functions. The
DateValidator
and
CalendarValidator
provide functions for comparing years,
quarters, months, weeks and dates and the
TimeValidator
provides
functions for comparing hours, minutes, seconds and milliseconds.
For example, to check that a date is in the current month, you could use
the
compareMonths()
method, which compares the year and month
components of a date:
// Check if the date is in the current month
int compare = validator.compareMonths(fooDate, new Date(), null);
if (compare == 0) {
// do current month processing
return;
}
// Check if the date is in the previous quarter
compare = validator.compareQuarters(fooDate, new Date(), null);
if (compare <320) {
// do previous quarter processing
return;
}
// Check if the date is in the next year
compare = validator.compareYears(fooDate, new Date(), null);
if (compare > 0) {
// do next year processing
return;
}
3 Numeric Validators
3.1 Overview
The numeric validators either validate according to a specified
format
or use a standard
format for a specified
Locale
or use
a
custom format for a specified
Locale
.
3.2 Validating a Numeric Value
You can either use one of the
isValid()
methods to just determine
if a number is valid, or use one of the
validate()
methods to
validate a number and convert it to an appropriate type.
The following example validates an integer against a custom pattern
for the
German locale. Please note the format is specified using
the standard symbols for java.text.DecimalFormat so although
the decimal separator is indicated as a period (".") in the format, the
validator will check using the German decimal separator - which is a comma (",").
// Get the Integer validator
IntegerValidator validator = IntegerValidator.getInstance();
// Validate/Convert the number
Integer fooInteger = validator.validate(fooString, "#,##0.00", Locale.GERMAN);
if (fooInteger == null) {
// error...not a valid Integer
return;
}
The following methods are provided to validate a number (return a boolean result):
isValid(value)
isValid(value, pattern)
isValid(value, Locale)
isValid(value, pattern, Locale)
The following methods are provided to validate a number and convert it one of
the
java.lang.Number
implementations:
validate(value)
validate(value, pattern)
validate(value, Locale)
validate(value, pattern, Locale)
3.3 Formatting
Formatting and validating are two sides of the same coin. Typically
input values which are converted from Strings according to a
specified
format also have to be rendered for
output in
the same format. These validators provide the mechanism for formatting from
numeric objects to Strings. The following methods are provided to format
numeric values as Strings:
format(number)
format(number, pattern)
format(number, Locale)
format(number, pattern, Locale)
3.4 Comparing Numbers
As well as validating that a value is a valid number, these validators
also provide functions for validating the
minimum,
maximum
and
range of a value.
// Check the number is between 25 and 75
if (validator.isInRange(fooInteger, 25, 75) {
// valid...in the specified range
return;
}
3.5 Currency Validation
A default
Currency Validator
implementation is provided, although all the
numeric validators
support currency validation. The default implementation converts
currency amounts to a
java.math.BigDecimal
and additionally
it provides
lenient currency symbol validation. That is, currency
amounts are valid with
or without the currency symbol.
BigDecimalValidator validator = CurrencyValidator.getInstance();
BigDecimal fooAmount = validator.validate("$12,500.00", Locale.US);
if (fooAmount == null) {
// error...not a valid currency amount
return;
}
// Check the amount is a minimum of $1,000
if (validator.minValue(fooAmount, 1000) {
// valid...in the specified range
return;
}
If, for example, you want to use the
Integer
Validator to validate a currency, then you can simply create a
new instance with the appropriate
format style. Note that
the other validators do not support the
lenient currency symbol
validation.
IntegerValidator validator =
new IntegerValidator(true, IntegerValidator.CURRENCY_FORMAT);
String pattern = "#,###" + '\u00A4' + '\u00A4'; // Use international symbol
Integer fooAmount = validator.validate("10.100EUR", pattern, Locale.GERMAN);
if (fooAmount == null) {
// error...not a valid currency amount
return;
}
3.6 Percent Validation
A default
Percent Validator
implementation is provided, although the
Float,
Double and
BigDecimal validators also support
percent validation. The default implementation converts
percent amounts to a
java.math.BigDecimal
and additionally
it provides
lenient percent symbol validation. That is, percent
amounts are valid with
or without the percent symbol.
BigDecimalValidator validator = PercentValidator.getInstance();
BigDecimal fooPercent = validator.validate("20%", Locale.US);
if (fooPercent == null) {
// error...not a valid percent
return;
}
// Check the percent is between 10% and 90%
if (validator.isInRange(fooPercent, 0.1, 0.9) {
// valid...in the specified range
return;
}
If, for example, you want to use the
Float
Validator to validate a percent, then you can simply create a
new instance with the appropriate
format style. Note that
the other validators do not support the
lenient percent symbol
validation.
FloatValidator validator =
new FloatValidator(true, FloatValidator.PERCENT_FORMAT);
Float fooPercent = validator.validate("20%", "###%");
if (fooPercent == null) {
// error...not a valid percent
return;
}
Note: in theory the other numeric validators besides
Float,
Double and
BigDecimal (i.e.
Byte,
Short,
Integer,
Long and
BigInteger)
also support percent validation. However, since they don't allow fractions
they will only work with percentages greater than 100%.