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

Last change on this file since 11742 was 11742, checked in by stoecker, 7 years ago

fix JavaDoc
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>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></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 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<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 name="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 name="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 name="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 name="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 name="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.