Package Documentation for org.openstreetmap.josm.data.validation.routines Package

This package contains independent validation routines adapted from Apache Commons Validator 1.5.0.

# Table of Contents

- 1. Overview
- 2. Validators
  - 2.1 Overview
  - 2.2 Regular Expression validation
  - 2.3 IP Address Validation
  - 2.4 Email Address Validation
  - 2.5 URL Validation
  - 2.6 Domain Name Validation

# 1. Overview

Commons Validator serves two purposes:

- To provide standard, independent 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, independent 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. Validators

## 2.1 Overview

This section lists other available validators.

- Regular Expressions - validates using Java 1.4+ regular expression support
- IP Address Validation - provides IPv4 address validation.
- Email Address Validation - provides email address validation according to RFC 822 standards.
- URL Validation - provides URL validation on scheme, domain, and authority.
- Domain Name Validation - provides domain name and IANA TLD validation.

## 2.2 Regular Expression Validation

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.

- Method Flavours - three flavours of validation metods are provided:
  - `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.
- Case Sensitivity - matching can be done in either a case sensitive or case in-sensitive way.
- Multiple Expressions - instances of the RegexValidator can be created to either match against a single regular expression or set (String array) of regular expressions.

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.

## 2.3 IP Address Validation

InetAddressValidator provides IPv4 address validation.

For example:

          // Get an InetAddressValidator
          InetAddressValidator validator = InetAddressValidator.getInstance();

          // Validate an IPv4 address
          if (!validator.isValid(candidateInetAddress)) {
              ... // invalid
          }

## 2.4 Email Address Validation

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.
          }

## 2.5 URL Validation

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
          }

## 2.6 Domain Name Validation

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
          }