Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package org.apache.commons.validator.routines

This package contains independant validation routines.

See:
Description

Class Summary
AbstractCalendarValidator | Abstract class for Date/Time/Calendar validation.
AbstractFormatValidator | Abstract class for Format based Validation.
AbstractNumberValidator | Abstract class for Number Validation.
BigDecimalValidator | BigDecimal Validation and Conversion routines (`java.math.BigDecimal`).
BigIntegerValidator | BigInteger Validation and Conversion routines (`java.math.BigInteger`).
ByteValidator | Byte Validation and Conversion routines (`java.lang.Byte`).
CalendarValidator | Calendar Validation and Conversion routines (`java.util.Calendar`).
CurrencyValidator | Currency Validation and Conversion routines (`java.math.BigDecimal`).
DateValidator | Date Validation and Conversion routines (`java.util.Date`).
DoubleValidator | Double Validation and Conversion routines (`java.lang.Double`).
FloatValidator | Float Validation and Conversion routines (`java.lang.Float`).
IntegerValidator | Integer Validation and Conversion routines (`java.lang.Integer`).
LongValidator | Long Validation and Conversion routines (`java.lang.Long`).
PercentValidator | Percentage Validation and Conversion routines (`java.math.BigDecimal`).
ShortValidator | Short Validation and Conversion routines (`java.lang.Short`).
TimeValidator | Time Validation and Conversion routines (`java.util.Calendar`).

## Package org.apache.commons.validator.routines Description

This package contains independant validation routines.

# Table of Contents

- 1. Overview
- 2. Date and Time Validators
  - 2.1 Overview
  - 2.2 Validating a Date Value
  - 2.3 Formatting
  - 2.4 Time Zones
  - 2.5 Comparing Dates and Times
- 2. Numeric Validators
  - 3.1 Overview
  - 3.2 Validating a Numeric Value
  - 3.3 Formatting
  - 3.4 Comparing Numbers
  - 3.5 Currency Validation
  - 3.6 Percent Validation

# 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`.

- Date Validator - validates dates converting to a `java.util.Date` type.
- Calendar Validator - validates dates converting to a `java.util.Calendar` type.
- Time Validator - validates times converting to a `java.util.Calendar` type.

### 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 < 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;
          }

# 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`.

- Byte Validator - validates numbers converting to a `java.lang.Byte` type.
- Short Validator - validates numbers converting to a `java.lang.Short` type.
- Integer Validator - validates numbers converting to a `java.lang.Integer` type.
- Long Validator - validates numbers converting to a `java.lang.Long` type.
- Float Validator - validates numbers converting to a `java.lang.Float` type.
- Double Validator - validates numbers converting to a `java.lang.Double` type.
- BigInteger Validator - validates numbers converting to a `java.math.BigInteger` type.
- BigDecimal Validator - validates numbers converting to a `java.math.BigDecimal` type.

### 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%.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Copyright © 2002-2006 The Apache Software Foundation. All Rights Reserved.