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.4.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 id="overview"></a>
|
---|
39 | <h1>1. Overview</h1>
|
---|
40 | <p>
|
---|
41 | Commons Validator serves two purposes:
|
---|
42 | </p>
|
---|
43 | <ul>
|
---|
44 | <li>To provide standard, independant 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, independant
|
---|
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 id="other"></a>
|
---|
59 | <h1>2. Validators</h1>
|
---|
60 |
|
---|
61 | <a id="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 id="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 id="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 id="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 id="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 id="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>
|
---|