This package contains independant validation routines.
Commons Validator serves two purposes:
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.
The date and time validators either validate according to a specified format
or use a standard format for a specified Locale.
java.util.Date type.java.util.Calendar type.java.util.Calendar type.
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)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)
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)
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 < 0) {
// 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;
}
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.
java.lang.Byte type.java.lang.Short type.java.lang.Integer type.java.lang.Long type.java.lang.Float type.java.lang.Double type.java.math.BigInteger type.java.math.BigDecimal type.
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)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)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;
}
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;
}
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%.
This section lists other available validators.
Regular expression validation can be done either by using the static methods provied by RegexValidator or by creating a new instance, which caches and re-uses compiled Patterns.
isValid() methods return true/false to indicate
whether validation was successful.validate() methods return a String
value of the matched groups aggregated together or
null if invalid.match() methods return a String array
of the matched groups or null if invalid.Below is an example of using one of the static methods to validate, matching in a case insensitive manner and returning a String of the matched groups (which doesn't include the hyphen).
// set up the parameters
boolean caseSensitive = false;
String regex = "^([A-Z]*)(?:\\-)([A-Z]*)$";
// validate - result should be a String of value "abcdef"
String result = RegexValidator.validate("abc-def", regex, caseSensitive);
The following static methods are provided for regular expression validation:
isValid(value, regex)isValid(value, regex, caseSensitive)validate(value, regex)validate(value, regex, caseSensitive)match(value, regex)match(value, regex, caseSensitive)Below is an example of creating an instance of RegexValidator matching in a case insensitive manner against a set of regular expressions:
// set up the parameters
boolean caseSensitive = false;
String regex1 = "^([A-Z]*)(?:\\-)([A-Z]*)*$"
String regex2 = "^([A-Z]*)$";
String[] regexs = new String[] {regex1, regex1};
// Create the validator
RegexValidator validator = new RegexValidator(regexs, caseSensitive);
// Validate true/false
boolean valid = validator.isValid("abc-def");
// Validate and return a String
String result = validator.validate("abc-def");
// Validate and return a String[]
String[] groups = validator.match("abc-def");
See the RegexValidator javadoc for a full list of the available constructors.
CheckDigit defines a new type for the calculation and validation of check digits with the following methods:
isValid(code) - validates the check digit of a code,
returning true or false.calculate(code) - calulates the check digit for a code
returning the check digit character.The following implementations are provided:
The following examples show validating the check digit of a code:
// Luhn check digit validation
boolean valid = LuhnCheckDigit.INSTANCE.isValid(code);
// EAN / UPC / ISBN-13 check digit validation
boolean valid = EAN13CheckDigit.INSTANCE.isValid(code);
// ISBN-10 check digit validation
boolean valid = ISBNCheckDigit.ISBN10.isValid(code);
boolean valid = ISBN10CheckDigit.INSTANCE.isValid(code);
// ISBN-13 check digit validation
boolean valid = ISBNCheckDigit.ISBN13.isValid(code);
// ISBN-10 or ISBN-13 check digit validation
boolean valid = ISBNCheckDigit.ISBN.isValid(code);
The following examples show calulating the check digit of a code:
// Luhn check digit validation
char checkdigit = LuhnCheckDigit.INSTANCE.calculate(code);
// EAN / UPC / ISBN-13 check digit validation
char checkdigit = EAN13CheckDigit.INSTANCE.calculate(code);
// ISBN-10 check digit validation
char checkdigit = ISBNCheckDigit.ISBN10.isValid(code);
char checkdigit = ISBN10CheckDigit.INSTANCE.calculate(code);
// ISBN-13 check digit validation
char checkdigit = ISBNCheckDigit.ISBN13.calculate(code);
// ISBN-10 or ISBN-13 check digit validation
char checkdigit = ISBNCheckDigit.ISBN.calculate(code);
CodeValidator provides a generic implementation for validating codes. It performs the following validations on a code:
For example to create a validator to validate EAN-13 codes (numeric, with a length of 13):
// Create an EAN-13 code validator
CodeValidator validator = new CodeValidator("^[0-9]*$", 13, EAN13CheckDigit.INSTANCE);
// Validate an EAN-13 code
if (!validator.isValid(code)) {
... // invalid
}
ISBNValidator provides ISBN-10 and ISBN-13 validation and can optionally convert ISBN-10 codes to ISBN-13.
isValidISBN10(value) - returns a booleanvalidateISBN10(value) - returns a reformatted ISBN-10 codeisValidISBN13(value) - returns a booleanvalidateISBN13(value) - returns a reformatted ISBN-13 codeisValid(value) - returns a booleanvalidate(value) - returns a reformatted ISBN code
(converts ISBN-10 to ISBN-13 if the convert option is true).For example to validate
// Validate an ISBN-10 or ISBN-13 code
if (!ISBNValidator.getInstance().isValid(code)) {
... // invalid
}
// Validate an ISBN-10 or ISBN-13 code (converting to ISBN-13)
String code = ISBNValidator.getInstance().validate(code);
// Validate an ISBN-10 or ISBN-13 code (not converting)
String code = ISBNValidator.getInstance(false).validate(code);
InetAddressValidator provides IPv4 address validation.
For example:
// Get an InetAddressValidator
InetAddressValidator validator = InetAddressValidator.getInstance();
// Validate an IPv4 address
if (!validator.isValid(candidateInetAddress)) {
... // invalid
}
EmailValidator provides email address validation according to RFC 822 standards.
For example:
// Get an EmailValidator
EmailValidator validator = EmailValidator.getInstance();
// Validate an email address
boolean isAddressValid = validator.isValid("user@apache.org");
// Validate a variable containing an email address
if (!validator.isValid(addressFromUserForm)) {
webController.sendRedirect(ERROR_REDIRECT, "Email address isn't valid");
// etc.
}
UrlValidator provides URL validation by checking the scheme, authority, path, query, and fragment in turn. Clients may specify valid schemes to be used in validating in addition to or instead of the default values (HTTP, HTTPS, FTP). The UrlValidator also supports options that change the parsing rules; for example, the ALLOW_2_SLASHES option instructs the Validator to allow consecutive slash characters in the path component, which is considered an error by default. For more information on the available options, see the UrlValidator documentation.
For example:
// Get an UrlValidator
UrlValidator defaultValidator = new UrlValidator(); // default schemes
if (defaultValidator.isValid("http://www.apache.org")) {
... // valid
}
if (!defaultValidator.isValid("http//www.oops.com")) {
... // invalid
}
// Get an UrlValidator with custom schemes
String[] customSchemes = { "sftp", "scp", "https" };
UrlValidator customValidator = new UrlValidator(customSchemes);
if (!customValidator.isValid("http://www.apache.org")) {
... // invalid due to insecure protocol
}
// Get an UrlValidator that allows double slashes in the path
UrlValidator doubleSlashValidator = new UrlValidator(UrlValidator.ALLOW_2_SLASHES);
if (doubleSlashValidator.isValid("http://www.apache.org//projects")) {
... // valid only in this Validator instance
}
DomainValidator provides validation of Internet domain names as specified by RFC1034/RFC1123 and according to the IANA-recognized list of top-level domains (TLDs). Clients may validate an entire domain name, a TLD of any category, or a TLD within a specific category.
For example:
// Get a DomainValidator
DomainValidator validator = DomainValidator.getInstance();
// Validate a domain name
if (validator.isValid("www.apache.org")) {
... // valid
}
if (!validator.isValid("www.apache.wrong")) {
... // invalid
}
// Validate a TLD
if (validator.isValidTld(".com")) {
... // valid
}
if (validator.isValidTld("org")) {
... // valid, the leading dot is optional
}
if (validator.isValidTld(".us")) {
... // valid, country code TLDs are also accepted
}
// Validate TLDs in categories
if (validator.isValidGenericTld(".name")) {
... // valid
}
if (!validator.isValidGenericTld(".uk")) {
... // invalid, .uk is a country code TLD
}
if (!validator.isValidCountryCodeTld(".info")) {
... // invalid, .info is a generic TLD
}