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

Last change on this file was 14273, checked in by stoecker, 13 months ago

fix typos - patch by naoliv - fix #16781 - Thanks a lot

File size: 10.1 KB
Line 
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>independent</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></li>
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, 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 id="other"></a>
59<h1>2. Validators</h1>
60
61<a id="other.overview"></a>
62<h2>2.1 Overview</h2>
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<h2>2.2 Regular Expression Validation</h2>
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:
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>
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
160<a id="other.inet"></a>
161<h2>2.3 IP Address Validation</h2>
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
182<a id="other.email"></a>
183<h2>2.4 Email Address Validation</h2>
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
206<a id="other.url"></a>
207<h2>2.5 URL Validation</h2>
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
247<a id="other.domain"></a>
248<h2>2.6 Domain Name Validation</h2>
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>
294</html>
Note: See TracBrowser for help on using the repository browser.