[7489] | 1 | <!--
|
---|
| 2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
---|
| 3 | contributor license agreements. See the NOTICE file distributed with
|
---|
| 4 | this work for additional information regarding copyright ownership.
|
---|
| 5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
---|
| 6 | (the "License"); you may not use this file except in compliance with
|
---|
| 7 | the License. You may obtain a copy of the License at
|
---|
| 8 |
|
---|
| 9 | http://www.apache.org/licenses/LICENSE-2.0
|
---|
| 10 |
|
---|
| 11 | Unless required by applicable law or agreed to in writing, software
|
---|
| 12 | distributed under the License is distributed on an "AS IS" BASIS,
|
---|
| 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
| 14 | See the License for the specific language governing permissions and
|
---|
| 15 | limitations under the License.
|
---|
| 16 | -->
|
---|
| 17 | <html>
|
---|
| 18 | <head>
|
---|
| 19 | <title>Package Documentation for org.openstreetmap.josm.data.validation.routines Package</title>
|
---|
| 20 | </head>
|
---|
| 21 | <body bgcolor="white">
|
---|
[14273] | 22 | <p>This package contains <i>independent</i> validation routines adapted from Apache Commons Validator 1.5.0.</p>
|
---|
[7489] | 23 | <h1>Table of Contents</h1>
|
---|
| 24 |
|
---|
| 25 | <ul>
|
---|
[11638] | 26 | <li>1. <a href="#overview">Overview</a></li>
|
---|
[7489] | 27 | <li>2. <a href="#other">Validators</a>
|
---|
| 28 | <ul>
|
---|
| 29 | <li>2.1 <a href="#other.overview">Overview</a></li>
|
---|
| 30 | <li>2.2 <a href="#other.regex">Regular Expression validation</a></li>
|
---|
| 31 | <li>2.3 <a href="#other.inet">IP Address Validation</a></li>
|
---|
| 32 | <li>2.4 <a href="#other.email">Email Address Validation</a></li>
|
---|
| 33 | <li>2.5 <a href="#other.url">URL Validation</a></li>
|
---|
| 34 | <li>2.6 <a href="#other.domain">Domain Name Validation</a></li>
|
---|
| 35 | </ul></li>
|
---|
| 36 | </ul>
|
---|
| 37 |
|
---|
[13494] | 38 | <a id="overview"></a>
|
---|
[7489] | 39 | <h1>1. Overview</h1>
|
---|
| 40 | <p>
|
---|
| 41 | Commons Validator serves two purposes:
|
---|
| 42 | </p>
|
---|
| 43 | <ul>
|
---|
[9853] | 44 | <li>To provide standard, independent validation routines/functions.</li>
|
---|
[7489] | 45 | <li>To provide a <i>mini</i> framework for Validation.</li>
|
---|
| 46 | </ul>
|
---|
| 47 | <p>
|
---|
| 48 | This package has been created, since version 1.3.0, in an attempt to clearly
|
---|
[9853] | 49 | separate these two concerns and is the location for the standard, independent
|
---|
[7489] | 50 | validation routines/functions in <em>Commons Validator</em>.
|
---|
| 51 | </p>
|
---|
| 52 |
|
---|
| 53 | <p>
|
---|
| 54 | The contents of this package have no dependencies on the framework aspect of
|
---|
| 55 | Commons Validator and can be used on their own.
|
---|
| 56 | </p>
|
---|
| 57 |
|
---|
[13494] | 58 | <a id="other"></a>
|
---|
[7489] | 59 | <h1>2. Validators</h1>
|
---|
| 60 |
|
---|
[13494] | 61 | <a id="other.overview"></a>
|
---|
[11742] | 62 | <h2>2.1 Overview</h2>
|
---|
[7489] | 63 | <p>
|
---|
| 64 | This section lists other available validators.
|
---|
| 65 | </p>
|
---|
| 66 | <ul>
|
---|
| 67 | <li><a href="#other.regex">Regular Expressions</a> - validates
|
---|
| 68 | using Java 1.4+ regular expression support</li>
|
---|
| 69 | <li><a href="#other.inet">IP Address Validation</a> - provides IPv4 address
|
---|
| 70 | validation.</li>
|
---|
| 71 | <li><a href="#other.email">Email Address Validation</a> - provides email
|
---|
| 72 | address validation according to RFC 822 standards.</li>
|
---|
| 73 | <li><a href="#other.url">URL Validation</a> - provides URL validation on
|
---|
| 74 | scheme, domain, and authority.</li>
|
---|
| 75 | <li><a href="#other.domain">Domain Name Validation</a> - provides domain
|
---|
| 76 | name and IANA TLD validation.</li>
|
---|
| 77 | </ul>
|
---|
| 78 |
|
---|
[13494] | 79 | <a id="other.regex"></a>
|
---|
[11742] | 80 | <h2>2.2 Regular Expression Validation</h2>
|
---|
[7489] | 81 | <p>
|
---|
| 82 | Regular expression validation can be done either by using the <i>static</i>
|
---|
| 83 | methods provied by <a href="RegexValidator.html">RegexValidator</a> or
|
---|
| 84 | by creating a new instance, which caches and re-uses compiled Patterns.
|
---|
| 85 | </p>
|
---|
| 86 | <ul>
|
---|
[10836] | 87 | <li><b>Method Flavours</b> - three <i>flavours</i> of validation metods are provided:
|
---|
[7489] | 88 | <ul>
|
---|
| 89 | <li><code>isValid()</code> methods return true/false to indicate
|
---|
| 90 | whether validation was successful.</li>
|
---|
| 91 | <li><code>validate()</code> methods return a <code>String</code>
|
---|
| 92 | value of the matched <i>groups</i> aggregated together or
|
---|
| 93 | <code>null</code> if invalid.</li>
|
---|
| 94 | <li><code>match()</code> methods return a <code>String</code> array
|
---|
| 95 | of the matched <i>groups</i> or <code>null</code> if invalid.</li>
|
---|
| 96 | </ul>
|
---|
[10836] | 97 | </li>
|
---|
[7489] | 98 | <li><b>Case Sensitivity</b> - matching can be done in either a <i>case
|
---|
| 99 | sensitive</i> or <i>case in-sensitive</i> way.</li>
|
---|
| 100 | <li><b>Multiple Expressions</b> - instances of the
|
---|
| 101 | <a href="RegexValidator.html">RegexValidator</a>
|
---|
| 102 | can be created to either match against a single regular expression
|
---|
| 103 | or set (String array) of regular expressions.</li>
|
---|
| 104 | </ul>
|
---|
| 105 | <p>
|
---|
| 106 | Below is an example of using one of the static methods to validate,
|
---|
| 107 | matching in a <i>case insensitive</i> manner and returning a String
|
---|
| 108 | of the matched groups (which doesn't include the hyphen).
|
---|
| 109 | </p>
|
---|
| 110 | <pre>
|
---|
| 111 | // set up the parameters
|
---|
| 112 | boolean caseSensitive = false;
|
---|
| 113 | String regex = "^([A-Z]*)(?:\\-)([A-Z]*)$";
|
---|
| 114 |
|
---|
| 115 | // validate - result should be a String of value "abcdef"
|
---|
| 116 | String result = RegexValidator.validate("abc-def", regex, caseSensitive);
|
---|
| 117 |
|
---|
| 118 | </pre>
|
---|
| 119 |
|
---|
| 120 | <p>The following static methods are provided for regular expression validation:
|
---|
| 121 | </p>
|
---|
| 122 | <ul>
|
---|
| 123 | <li><code>isValid(<i>value</i>, <i>regex</i>)</code></li>
|
---|
| 124 | <li><code>isValid(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
|
---|
| 125 | <li><code>validate(<i>value</i>, <i>regex</i>)</code></li>
|
---|
| 126 | <li><code>validate(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
|
---|
| 127 | <li><code>match(<i>value</i>, <i>regex</i>)</code></li>
|
---|
| 128 | <li><code>match(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
|
---|
| 129 | </ul>
|
---|
| 130 | <p>
|
---|
| 131 | Below is an example of creating an instance of
|
---|
| 132 | <a href="RegexValidator.html">RegexValidator</a> matching in a <i>case insensitive</i>
|
---|
| 133 | manner against a set of regular expressions:
|
---|
| 134 | </p>
|
---|
| 135 | <pre>
|
---|
| 136 | // set up the parameters
|
---|
| 137 | boolean caseSensitive = false;
|
---|
| 138 | String regex1 = "^([A-Z]*)(?:\\-)([A-Z]*)*$"
|
---|
| 139 | String regex2 = "^([A-Z]*)$";
|
---|
| 140 | String[] regexs = new String[] {regex1, regex1};
|
---|
| 141 |
|
---|
| 142 | // Create the validator
|
---|
| 143 | RegexValidator validator = new RegexValidator(regexs, caseSensitive);
|
---|
| 144 |
|
---|
| 145 | // Validate true/false
|
---|
| 146 | boolean valid = validator.isValid("abc-def");
|
---|
| 147 |
|
---|
| 148 | // Validate and return a String
|
---|
| 149 | String result = validator.validate("abc-def");
|
---|
| 150 |
|
---|
| 151 | // Validate and return a String[]
|
---|
| 152 | String[] groups = validator.match("abc-def");
|
---|
| 153 |
|
---|
| 154 | </pre>
|
---|
| 155 | <p>See the
|
---|
| 156 | <a href="RegexValidator.html">RegexValidator</a> javadoc for a full list
|
---|
| 157 | of the available constructors.
|
---|
| 158 | </p>
|
---|
| 159 |
|
---|
[13494] | 160 | <a id="other.inet"></a>
|
---|
[11742] | 161 | <h2>2.3 IP Address Validation</h2>
|
---|
[7489] | 162 |
|
---|
| 163 | <p>
|
---|
| 164 | <a href="InetAddressValidator.html">InetAddressValidator</a> provides
|
---|
| 165 | IPv4 address validation.
|
---|
| 166 | </p>
|
---|
| 167 | <p>
|
---|
| 168 | For example:
|
---|
| 169 | </p>
|
---|
| 170 | <pre>
|
---|
| 171 |
|
---|
| 172 | // Get an InetAddressValidator
|
---|
| 173 | InetAddressValidator validator = InetAddressValidator.getInstance();
|
---|
| 174 |
|
---|
| 175 | // Validate an IPv4 address
|
---|
| 176 | if (!validator.isValid(candidateInetAddress)) {
|
---|
| 177 | ... // invalid
|
---|
| 178 | }
|
---|
| 179 |
|
---|
| 180 | </pre>
|
---|
| 181 |
|
---|
[13494] | 182 | <a id="other.email"></a>
|
---|
[11742] | 183 | <h2>2.4 Email Address Validation</h2>
|
---|
[7489] | 184 |
|
---|
| 185 | <p>
|
---|
| 186 | <a href="EmailValidator.html">EmailValidator</a> provides email address
|
---|
| 187 | validation according to RFC 822 standards.
|
---|
| 188 | </p>
|
---|
| 189 | <p>
|
---|
| 190 | For example:
|
---|
| 191 | </p>
|
---|
| 192 | <pre>
|
---|
| 193 | // Get an EmailValidator
|
---|
| 194 | EmailValidator validator = EmailValidator.getInstance();
|
---|
| 195 |
|
---|
| 196 | // Validate an email address
|
---|
| 197 | boolean isAddressValid = validator.isValid("user@apache.org");
|
---|
| 198 |
|
---|
| 199 | // Validate a variable containing an email address
|
---|
| 200 | if (!validator.isValid(addressFromUserForm)) {
|
---|
| 201 | webController.sendRedirect(ERROR_REDIRECT, "Email address isn't valid");
|
---|
| 202 | // etc.
|
---|
| 203 | }
|
---|
| 204 | </pre>
|
---|
| 205 |
|
---|
[13494] | 206 | <a id="other.url"></a>
|
---|
[11742] | 207 | <h2>2.5 URL Validation</h2>
|
---|
[7489] | 208 |
|
---|
| 209 | <p>
|
---|
| 210 | <a href="UrlValidator.html">UrlValidator</a> provides URL validation by
|
---|
| 211 | checking the scheme, authority, path, query, and fragment in turn. Clients
|
---|
| 212 | may specify valid schemes to be used in validating in addition to or instead of
|
---|
| 213 | the default values (HTTP, HTTPS, FTP). The UrlValidator also supports options
|
---|
| 214 | that change the parsing rules; for example, the ALLOW_2_SLASHES option instructs
|
---|
| 215 | the Validator to allow consecutive slash characters in the path component, which
|
---|
| 216 | is considered an error by default.
|
---|
| 217 |
|
---|
| 218 | For more information on the available options, see the UrlValidator documentation.
|
---|
| 219 | </p>
|
---|
| 220 | <p>
|
---|
| 221 | For example:
|
---|
| 222 | </p>
|
---|
| 223 | <pre>
|
---|
| 224 | // Get an UrlValidator
|
---|
| 225 | UrlValidator defaultValidator = new UrlValidator(); // default schemes
|
---|
| 226 | if (defaultValidator.isValid("http://www.apache.org")) {
|
---|
| 227 | ... // valid
|
---|
| 228 | }
|
---|
| 229 | if (!defaultValidator.isValid("http//www.oops.com")) {
|
---|
| 230 | ... // invalid
|
---|
| 231 | }
|
---|
| 232 |
|
---|
| 233 | // Get an UrlValidator with custom schemes
|
---|
| 234 | String[] customSchemes = { "sftp", "scp", "https" };
|
---|
| 235 | UrlValidator customValidator = new UrlValidator(customSchemes);
|
---|
| 236 | if (!customValidator.isValid("http://www.apache.org")) {
|
---|
| 237 | ... // invalid due to insecure protocol
|
---|
| 238 | }
|
---|
| 239 |
|
---|
| 240 | // Get an UrlValidator that allows double slashes in the path
|
---|
| 241 | UrlValidator doubleSlashValidator = new UrlValidator(UrlValidator.ALLOW_2_SLASHES);
|
---|
| 242 | if (doubleSlashValidator.isValid("http://www.apache.org//projects")) {
|
---|
| 243 | ... // valid only in this Validator instance
|
---|
| 244 | }
|
---|
| 245 | </pre>
|
---|
| 246 |
|
---|
[13494] | 247 | <a id="other.domain"></a>
|
---|
[11742] | 248 | <h2>2.6 Domain Name Validation</h2>
|
---|
[7489] | 249 |
|
---|
| 250 | <p>
|
---|
| 251 | <a href="DomainValidator.html">DomainValidator</a> provides validation of Internet
|
---|
| 252 | domain names as specified by RFC1034/RFC1123 and according to the IANA-recognized
|
---|
| 253 | list of top-level domains (TLDs). Clients may validate an entire domain name, a
|
---|
| 254 | TLD of any category, or a TLD within a specific category.
|
---|
| 255 | </p>
|
---|
| 256 | <p>
|
---|
| 257 | For example:
|
---|
| 258 | </p>
|
---|
| 259 | <pre>
|
---|
| 260 | // Get a DomainValidator
|
---|
| 261 | DomainValidator validator = DomainValidator.getInstance();
|
---|
| 262 |
|
---|
| 263 | // Validate a domain name
|
---|
| 264 | if (validator.isValid("www.apache.org")) {
|
---|
| 265 | ... // valid
|
---|
| 266 | }
|
---|
| 267 | if (!validator.isValid("www.apache.wrong")) {
|
---|
| 268 | ... // invalid
|
---|
| 269 | }
|
---|
| 270 |
|
---|
| 271 | // Validate a TLD
|
---|
| 272 | if (validator.isValidTld(".com")) {
|
---|
| 273 | ... // valid
|
---|
| 274 | }
|
---|
| 275 | if (validator.isValidTld("org")) {
|
---|
| 276 | ... // valid, the leading dot is optional
|
---|
| 277 | }
|
---|
| 278 | if (validator.isValidTld(".us")) {
|
---|
| 279 | ... // valid, country code TLDs are also accepted
|
---|
| 280 | }
|
---|
| 281 |
|
---|
| 282 | // Validate TLDs in categories
|
---|
| 283 | if (validator.isValidGenericTld(".name")) {
|
---|
| 284 | ... // valid
|
---|
| 285 | }
|
---|
| 286 | if (!validator.isValidGenericTld(".uk")) {
|
---|
| 287 | ... // invalid, .uk is a country code TLD
|
---|
| 288 | }
|
---|
| 289 | if (!validator.isValidCountryCodeTld(".info")) {
|
---|
| 290 | ... // invalid, .info is a generic TLD
|
---|
| 291 | }
|
---|
| 292 | </pre>
|
---|
| 293 | </body>
|
---|
[11747] | 294 | </html>
|
---|