| 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">
|
|---|
| 22 | <p>This package contains <i>independant</i> validation routines adapted from Apache Commons Validator 1.5.0.</p>
|
|---|
| 23 | <h1>Table of Contents</h1>
|
|---|
| 24 |
|
|---|
| 25 | <ul>
|
|---|
| 26 | <li>1. <a href="#overview">Overview</a>
|
|---|
| 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 |
|
|---|
| 38 | <a name="overview"></a>
|
|---|
| 39 | <h1>1. Overview</h1>
|
|---|
| 40 | <p>
|
|---|
| 41 | Commons Validator serves two purposes:
|
|---|
| 42 | </p>
|
|---|
| 43 | <ul>
|
|---|
| 44 | <li>To provide standard, independent validation routines/functions.</li>
|
|---|
| 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
|
|---|
| 49 | separate these two concerns and is the location for the standard, independent
|
|---|
| 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 |
|
|---|
| 58 | <a name="other"></a>
|
|---|
| 59 | <h1>2. Validators</h1>
|
|---|
| 60 |
|
|---|
| 61 | <a name="other.overview"></a>
|
|---|
| 62 | <h3>2.1 Overview</h3>
|
|---|
| 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 |
|
|---|
| 79 | <a name="other.regex"></a>
|
|---|
| 80 | <h3>2.2 Regular Expression Validation</h3>
|
|---|
| 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>
|
|---|
| 87 | <li><b>Method Flavours</b> - three <i>flavours</i> of validation metods are provided:</li>
|
|---|
| 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>
|
|---|
| 97 | <li><b>Case Sensitivity</b> - matching can be done in either a <i>case
|
|---|
| 98 | sensitive</i> or <i>case in-sensitive</i> way.</li>
|
|---|
| 99 | <li><b>Multiple Expressions</b> - instances of the
|
|---|
| 100 | <a href="RegexValidator.html">RegexValidator</a>
|
|---|
| 101 | can be created to either match against a single regular expression
|
|---|
| 102 | or set (String array) of regular expressions.</li>
|
|---|
| 103 | </ul>
|
|---|
| 104 | <p>
|
|---|
| 105 | Below is an example of using one of the static methods to validate,
|
|---|
| 106 | matching in a <i>case insensitive</i> manner and returning a String
|
|---|
| 107 | of the matched groups (which doesn't include the hyphen).
|
|---|
| 108 | </p>
|
|---|
| 109 | <pre>
|
|---|
| 110 | // set up the parameters
|
|---|
| 111 | boolean caseSensitive = false;
|
|---|
| 112 | String regex = "^([A-Z]*)(?:\\-)([A-Z]*)$";
|
|---|
| 113 |
|
|---|
| 114 | // validate - result should be a String of value "abcdef"
|
|---|
| 115 | String result = RegexValidator.validate("abc-def", regex, caseSensitive);
|
|---|
| 116 |
|
|---|
| 117 | </pre>
|
|---|
| 118 |
|
|---|
| 119 | <p>The following static methods are provided for regular expression validation:
|
|---|
| 120 | </p>
|
|---|
| 121 | <ul>
|
|---|
| 122 | <li><code>isValid(<i>value</i>, <i>regex</i>)</code></li>
|
|---|
| 123 | <li><code>isValid(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
|
|---|
| 124 | <li><code>validate(<i>value</i>, <i>regex</i>)</code></li>
|
|---|
| 125 | <li><code>validate(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
|
|---|
| 126 | <li><code>match(<i>value</i>, <i>regex</i>)</code></li>
|
|---|
| 127 | <li><code>match(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
|
|---|
| 128 | </ul>
|
|---|
| 129 | <p>
|
|---|
| 130 | Below is an example of creating an instance of
|
|---|
| 131 | <a href="RegexValidator.html">RegexValidator</a> matching in a <i>case insensitive</i>
|
|---|
| 132 | manner against a set of regular expressions:
|
|---|
| 133 | </p>
|
|---|
| 134 | <pre>
|
|---|
| 135 | // set up the parameters
|
|---|
| 136 | boolean caseSensitive = false;
|
|---|
| 137 | String regex1 = "^([A-Z]*)(?:\\-)([A-Z]*)*$"
|
|---|
| 138 | String regex2 = "^([A-Z]*)$";
|
|---|
| 139 | String[] regexs = new String[] {regex1, regex1};
|
|---|
| 140 |
|
|---|
| 141 | // Create the validator
|
|---|
| 142 | RegexValidator validator = new RegexValidator(regexs, caseSensitive);
|
|---|
| 143 |
|
|---|
| 144 | // Validate true/false
|
|---|
| 145 | boolean valid = validator.isValid("abc-def");
|
|---|
| 146 |
|
|---|
| 147 | // Validate and return a String
|
|---|
| 148 | String result = validator.validate("abc-def");
|
|---|
| 149 |
|
|---|
| 150 | // Validate and return a String[]
|
|---|
| 151 | String[] groups = validator.match("abc-def");
|
|---|
| 152 |
|
|---|
| 153 | </pre>
|
|---|
| 154 | <p>See the
|
|---|
| 155 | <a href="RegexValidator.html">RegexValidator</a> javadoc for a full list
|
|---|
| 156 | of the available constructors.
|
|---|
| 157 | </p>
|
|---|
| 158 |
|
|---|
| 159 | <a name="other.inet"></a>
|
|---|
| 160 | <h3>2.3 IP Address Validation</h3>
|
|---|
| 161 |
|
|---|
| 162 | <p>
|
|---|
| 163 | <a href="InetAddressValidator.html">InetAddressValidator</a> provides
|
|---|
| 164 | IPv4 address validation.
|
|---|
| 165 | </p>
|
|---|
| 166 | <p>
|
|---|
| 167 | For example:
|
|---|
| 168 | </p>
|
|---|
| 169 | <pre>
|
|---|
| 170 |
|
|---|
| 171 | // Get an InetAddressValidator
|
|---|
| 172 | InetAddressValidator validator = InetAddressValidator.getInstance();
|
|---|
| 173 |
|
|---|
| 174 | // Validate an IPv4 address
|
|---|
| 175 | if (!validator.isValid(candidateInetAddress)) {
|
|---|
| 176 | ... // invalid
|
|---|
| 177 | }
|
|---|
| 178 |
|
|---|
| 179 | </pre>
|
|---|
| 180 |
|
|---|
| 181 | <a name="other.email"></a>
|
|---|
| 182 | <h3>2.4 Email Address Validation</h3>
|
|---|
| 183 |
|
|---|
| 184 | <p>
|
|---|
| 185 | <a href="EmailValidator.html">EmailValidator</a> provides email address
|
|---|
| 186 | validation according to RFC 822 standards.
|
|---|
| 187 | </p>
|
|---|
| 188 | <p>
|
|---|
| 189 | For example:
|
|---|
| 190 | </p>
|
|---|
| 191 | <pre>
|
|---|
| 192 | // Get an EmailValidator
|
|---|
| 193 | EmailValidator validator = EmailValidator.getInstance();
|
|---|
| 194 |
|
|---|
| 195 | // Validate an email address
|
|---|
| 196 | boolean isAddressValid = validator.isValid("user@apache.org");
|
|---|
| 197 |
|
|---|
| 198 | // Validate a variable containing an email address
|
|---|
| 199 | if (!validator.isValid(addressFromUserForm)) {
|
|---|
| 200 | webController.sendRedirect(ERROR_REDIRECT, "Email address isn't valid");
|
|---|
| 201 | // etc.
|
|---|
| 202 | }
|
|---|
| 203 | </pre>
|
|---|
| 204 |
|
|---|
| 205 | <a name="other.url"></a>
|
|---|
| 206 | <h3>2.5 URL Validation</h3>
|
|---|
| 207 |
|
|---|
| 208 | <p>
|
|---|
| 209 | <a href="UrlValidator.html">UrlValidator</a> provides URL validation by
|
|---|
| 210 | checking the scheme, authority, path, query, and fragment in turn. Clients
|
|---|
| 211 | may specify valid schemes to be used in validating in addition to or instead of
|
|---|
| 212 | the default values (HTTP, HTTPS, FTP). The UrlValidator also supports options
|
|---|
| 213 | that change the parsing rules; for example, the ALLOW_2_SLASHES option instructs
|
|---|
| 214 | the Validator to allow consecutive slash characters in the path component, which
|
|---|
| 215 | is considered an error by default.
|
|---|
| 216 |
|
|---|
| 217 | For more information on the available options, see the UrlValidator documentation.
|
|---|
| 218 | </p>
|
|---|
| 219 | <p>
|
|---|
| 220 | For example:
|
|---|
| 221 | </p>
|
|---|
| 222 | <pre>
|
|---|
| 223 | // Get an UrlValidator
|
|---|
| 224 | UrlValidator defaultValidator = new UrlValidator(); // default schemes
|
|---|
| 225 | if (defaultValidator.isValid("http://www.apache.org")) {
|
|---|
| 226 | ... // valid
|
|---|
| 227 | }
|
|---|
| 228 | if (!defaultValidator.isValid("http//www.oops.com")) {
|
|---|
| 229 | ... // invalid
|
|---|
| 230 | }
|
|---|
| 231 |
|
|---|
| 232 | // Get an UrlValidator with custom schemes
|
|---|
| 233 | String[] customSchemes = { "sftp", "scp", "https" };
|
|---|
| 234 | UrlValidator customValidator = new UrlValidator(customSchemes);
|
|---|
| 235 | if (!customValidator.isValid("http://www.apache.org")) {
|
|---|
| 236 | ... // invalid due to insecure protocol
|
|---|
| 237 | }
|
|---|
| 238 |
|
|---|
| 239 | // Get an UrlValidator that allows double slashes in the path
|
|---|
| 240 | UrlValidator doubleSlashValidator = new UrlValidator(UrlValidator.ALLOW_2_SLASHES);
|
|---|
| 241 | if (doubleSlashValidator.isValid("http://www.apache.org//projects")) {
|
|---|
| 242 | ... // valid only in this Validator instance
|
|---|
| 243 | }
|
|---|
| 244 | </pre>
|
|---|
| 245 |
|
|---|
| 246 | <a name="other.domain"></a>
|
|---|
| 247 | <h3>2.6 Domain Name Validation</h3>
|
|---|
| 248 |
|
|---|
| 249 | <p>
|
|---|
| 250 | <a href="DomainValidator.html">DomainValidator</a> provides validation of Internet
|
|---|
| 251 | domain names as specified by RFC1034/RFC1123 and according to the IANA-recognized
|
|---|
| 252 | list of top-level domains (TLDs). Clients may validate an entire domain name, a
|
|---|
| 253 | TLD of any category, or a TLD within a specific category.
|
|---|
| 254 | </p>
|
|---|
| 255 | <p>
|
|---|
| 256 | For example:
|
|---|
| 257 | </p>
|
|---|
| 258 | <pre>
|
|---|
| 259 | // Get a DomainValidator
|
|---|
| 260 | DomainValidator validator = DomainValidator.getInstance();
|
|---|
| 261 |
|
|---|
| 262 | // Validate a domain name
|
|---|
| 263 | if (validator.isValid("www.apache.org")) {
|
|---|
| 264 | ... // valid
|
|---|
| 265 | }
|
|---|
| 266 | if (!validator.isValid("www.apache.wrong")) {
|
|---|
| 267 | ... // invalid
|
|---|
| 268 | }
|
|---|
| 269 |
|
|---|
| 270 | // Validate a TLD
|
|---|
| 271 | if (validator.isValidTld(".com")) {
|
|---|
| 272 | ... // valid
|
|---|
| 273 | }
|
|---|
| 274 | if (validator.isValidTld("org")) {
|
|---|
| 275 | ... // valid, the leading dot is optional
|
|---|
| 276 | }
|
|---|
| 277 | if (validator.isValidTld(".us")) {
|
|---|
| 278 | ... // valid, country code TLDs are also accepted
|
|---|
| 279 | }
|
|---|
| 280 |
|
|---|
| 281 | // Validate TLDs in categories
|
|---|
| 282 | if (validator.isValidGenericTld(".name")) {
|
|---|
| 283 | ... // valid
|
|---|
| 284 | }
|
|---|
| 285 | if (!validator.isValidGenericTld(".uk")) {
|
|---|
| 286 | ... // invalid, .uk is a country code TLD
|
|---|
| 287 | }
|
|---|
| 288 | if (!validator.isValidCountryCodeTld(".info")) {
|
|---|
| 289 | ... // invalid, .info is a generic TLD
|
|---|
| 290 | }
|
|---|
| 291 | </pre>
|
|---|
| 292 | </body>
|
|---|
| 293 | </html>
|
|---|
