source: josm/trunk/src/org/openstreetmap/josm/data/validation/routines/package.html @ 9853

Last change on this file since 9853 was 9853, checked in by Don-vip, 4 years ago

fix #12557 : update to Apache Commons Validator 1.5.0 + updates from trunk + unit/integration tests + anticipated patches to add missing TLDs and Country Codes from IANA

File size: 10.1 KB
RevLine 
[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">
[9853]22    <p>This package contains <i>independant</i> validation routines adapted from Apache Commons Validator 1.5.0.</p>
[7489]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
[9853]38<a name="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
[9853]58<a name="other"></a>
[7489]59<h1>2. Validators</h1>
60
[9853]61<a name="other.overview"></a>
[7489]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
[9853]79<a name="other.regex"></a>
[7489]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
[9853]159<a name="other.inet"></a>
[7489]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
[9853]181<a name="other.email"></a>
[7489]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
[9853]205<a name="other.url"></a>
[7489]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
[9853]246<a name="other.domain"></a>
[7489]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>
Note: See TracBrowser for help on using the repository browser.