1 /*
2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.validation;
27
28 import java.io.IOException;
29
30 import javax.xml.transform.Result;
31 import javax.xml.transform.Source;
32
33 import org.w3c.dom.ls.LSResourceResolver;
34 import org.xml.sax.ErrorHandler;
35 import org.xml.sax.SAXException;
36 import org.xml.sax.SAXNotRecognizedException;
37 import org.xml.sax.SAXNotSupportedException;
38
39 /**
40 * <p>A processor that checks an XML document against {@link Schema}.</p>
41 *
42 * <p>
43 * A validator object is not thread-safe and not reentrant.
44 * In other words, it is the application's responsibility to make
45 * sure that one {@link Validator} object is not used from
46 * more than one thread at any given time, and while the <code>validate</code>
47 * method is invoked, applications may not recursively call
48 * the <code>validate</code> method.
49 * <p>
50 *
51 *
52 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
53 * @since 1.5
54 */
55 public abstract class Validator {
56
57 /**
58 * Constructor for derived classes.
59 *
60 * <p>The constructor does nothing.</p>
61 *
62 * <p>Derived classes must create {@link Validator} objects that have
63 * <code>null</code> {@link ErrorHandler} and
64 * <code>null</code> {@link LSResourceResolver}.
65 * </p>
66 */
67 protected Validator() {
68 }
69
70 /**
71 * <p>Reset this <code>Validator</code> to its original configuration.</p>
72 *
73 * <p><code>Validator</code> is reset to the same state as when it was created with
74 * {@link Schema#newValidator()}.
75 * <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s
76 * thus saving resources associated with the creation of new <code>Validator</code>s.</p>
77 *
78 * <p>The reset <code>Validator</code> is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler}
79 * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
80 * <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p>
81 */
82 public abstract void reset();
83
84 /**
85 * Validates the specified input.
86 *
87 * <p>This is just a convenience method for
88 * {@link #validate(Source source, Result result)}
89 * with <code>result</code> of <code>null</code>.</p>
90 *
91 * @param source
92 * XML to be validated. Must be an XML document or
93 * XML element and must not be null. For backwards compatibility,
94 * the results of attempting to validate anything other than
95 * a document or element are implementation-dependent.
96 * Implementations must either recognize and process the input
97 * or throw an IllegalArgumentException.
98 *
99 * @throws IllegalArgumentException
100 * If the <code>Source</code>
101 * is an XML artifact that the implementation cannot
102 * validate (for example, a processing instruction).
103 *
104 * @throws SAXException
105 * If the {@link ErrorHandler} throws a {@link SAXException} or
106 * if a fatal error is found and the {@link ErrorHandler} returns
107 * normally.
108 *
109 * @throws IOException
110 * If the validator is processing a
111 * {@link javax.xml.transform.sax.SAXSource} and the
112 * underlying {@link org.xml.sax.XMLReader} throws an
113 * {@link IOException}.
114 *
115 *
116 * @throws NullPointerException If <code>source</code> is
117 * <code>null</code>.
118 *
119 * @see #validate(Source source, Result result)
120 */
121 public void validate(Source source)
122 throws SAXException, IOException {
123
124 validate(source, null);
125 }
126
127 /**
128 * <p>Validates the specified input and send the augmented validation
129 * result to the specified output.</p>
130 *
131 * <p>This method places the following restrictions on the types of
132 * the {@link Source}/{@link Result} accepted.</p>
133 *
134 * <table border=1>
135 * <thead>
136 * <tr>
137 * <th colspan="5"><code>Source</code> / <code>Result</code> Accepted</th>
138 * </tr>
139 * <tr>
140 * <th></th>
141 * <th>{@link javax.xml.transform.stream.StreamSource}</th>
142 * <th>{@link javax.xml.transform.sax.SAXSource}</th>
143 * <th>{@link javax.xml.transform.dom.DOMSource}</th>
144 * <th>{@link javax.xml.transform.stax.StAXSource}</th>
145 * </tr>
146 * </thead>
147 * <tbody align="center">
148 * <tr>
149 * <td><code>null</code></td>
150 * <td>OK</td>
151 * <td>OK</td>
152 * <td>OK</td>
153 * <td>OK</td>
154 * </tr>
155 * <tr>
156 * <th>{@link javax.xml.transform.stream.StreamResult}</th>
157 * <td>OK</td>
158 * <td><code>IllegalArgumentException</code></td>
159 * <td><code>IllegalArgumentException</code></td>
160 * <td><code>IllegalArgumentException</code></td>
161 * </tr>
162 * <tr>
163 * <th>{@link javax.xml.transform.sax.SAXResult}</th>
164 * <td><code>IllegalArgumentException</code></td>
165 * <td>OK</td>
166 * <td><code>IllegalArgumentException</code></td>
167 * <td><code>IllegalArgumentException</code></td>
168 * </tr>
169 * <tr>
170 * <th>{@link javax.xml.transform.dom.DOMResult}</th>
171 * <td><code>IllegalArgumentException</code></td>
172 * <td><code>IllegalArgumentException</code></td>
173 * <td>OK</td>
174 * <td><code>IllegalArgumentException</code></td>
175 * </tr>
176 * <tr>
177 * <th>{@link javax.xml.transform.stax.StAXResult}</th>
178 * <td><code>IllegalArgumentException</code></td>
179 * <td><code>IllegalArgumentException</code></td>
180 * <td><code>IllegalArgumentException</code></td>
181 * <td>OK</td>
182 * </tr>
183 * </tbody>
184 * </table>
185 *
186 * <p>To validate one <code>Source</code> into another kind of
187 * <code>Result</code>, use the identity transformer (see
188 * {@link javax.xml.transform.TransformerFactory#newTransformer()}).</p>
189 *
190 * <p>Errors found during the validation is sent to the specified
191 * {@link ErrorHandler}.</p>
192 *
193 * <p>If a document is valid, or if a document contains some errors
194 * but none of them were fatal and the <code>ErrorHandler</code> didn't
195 * throw any exception, then the method returns normally.</p>
196 *
197 * @param source
198 * XML to be validated. Must be an XML document or
199 * XML element and must not be null. For backwards compatibility,
200 * the results of attempting to validate anything other than
201 * a document or element are implementation-dependent.
202 * Implementations must either recognize and process the input
203 * or throw an IllegalArgumentException.
204 *
205 * @param result
206 * The <code>Result</code> object that receives (possibly augmented)
207 * XML. This parameter can be null if the caller is not interested
208 * in it.
209 *
210 * Note that when a <code>DOMResult</code> is used,
211 * a validator might just pass the same DOM node from
212 * <code>DOMSource</code> to <code>DOMResult</code>
213 * (in which case <code>source.getNode()==result.getNode()</code>),
214 * it might copy the entire DOM tree, or it might alter the
215 * node given by the source.
216 *
217 * @throws IllegalArgumentException
218 * If the <code>Result</code> type doesn't match the
219 * <code>Source</code> type of if the <code>Source</code>
220 * is an XML artifact that the implementation cannot
221 * validate (for example, a processing instruction).
222 * @throws SAXException
223 * If the <code>ErrorHandler</code> throws a
224 * <code>SAXException</code> or
225 * if a fatal error is found and the <code>ErrorHandler</code> returns
226 * normally.
227 * @throws IOException
228 * If the validator is processing a
229 * <code>SAXSource</code> and the
230 * underlying {@link org.xml.sax.XMLReader} throws an
231 * <code>IOException</code>.
232 * @throws NullPointerException
233 * If the <code>source</code> parameter is <code>null</code>.
234 *
235 * @see #validate(Source source)
236 */
237 public abstract void validate(Source source, Result result)
238 throws SAXException, IOException;
239
240 /**
241 * Sets the {@link ErrorHandler} to receive errors encountered
242 * during the <code>validate</code> method invocation.
243 *
244 * <p>
245 * Error handler can be used to customize the error handling process
246 * during a validation. When an {@link ErrorHandler} is set,
247 * errors found during the validation will be first sent
248 * to the {@link ErrorHandler}.
249 *
250 * <p>
251 * The error handler can abort further validation immediately
252 * by throwing {@link SAXException} from the handler. Or for example
253 * it can print an error to the screen and try to continue the
254 * validation by returning normally from the {@link ErrorHandler}
255 *
256 * <p>
257 * If any {@link Throwable} is thrown from an {@link ErrorHandler},
258 * the caller of the <code>validate</code> method will be thrown
259 * the same {@link Throwable} object.
260 *
261 * <p>
262 * {@link Validator} is not allowed to
263 * throw {@link SAXException} without first reporting it to
264 * {@link ErrorHandler}.
265 *
266 * <p>
267 * When the {@link ErrorHandler} is null, the implementation will
268 * behave as if the following {@link ErrorHandler} is set:
269 * <pre>
270 * class DraconianErrorHandler implements {@link ErrorHandler} {
271 * public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
272 * throw e;
273 * }
274 * public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
275 * throw e;
276 * }
277 * public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
278 * // noop
279 * }
280 * }
281 * </pre>
282 *
283 * <p>
284 * When a new {@link Validator} object is created, initially
285 * this field is set to null.
286 *
287 * @param errorHandler
288 * A new error handler to be set. This parameter can be null.
289 */
290 public abstract void setErrorHandler(ErrorHandler errorHandler);
291
292 /**
293 * Gets the current {@link ErrorHandler} set to this {@link Validator}.
294 *
295 * @return
296 * This method returns the object that was last set through
297 * the {@link #setErrorHandler(ErrorHandler)} method, or null
298 * if that method has never been called since this {@link Validator}
299 * has created.
300 *
301 * @see #setErrorHandler(ErrorHandler)
302 */
303 public abstract ErrorHandler getErrorHandler();
304
305 /**
306 * Sets the {@link LSResourceResolver} to customize
307 * resource resolution while in a validation episode.
308 *
309 * <p>
310 * {@link Validator} uses a {@link LSResourceResolver}
311 * when it needs to locate external resources while a validation,
312 * although exactly what constitutes "locating external resources" is
313 * up to each schema language.
314 *
315 * <p>
316 * When the {@link LSResourceResolver} is null, the implementation will
317 * behave as if the following {@link LSResourceResolver} is set:
318 * <pre>
319 * class DumbLSResourceResolver implements {@link LSResourceResolver} {
320 * public {@link org.w3c.dom.ls.LSInput} resolveResource(
321 * String publicId, String systemId, String baseURI) {
322 *
323 * return null; // always return null
324 * }
325 * }
326 * </pre>
327 *
328 * <p>
329 * If a {@link LSResourceResolver} throws a {@link RuntimeException}
330 * (or instances of its derived classes),
331 * then the {@link Validator} will abort the parsing and
332 * the caller of the <code>validate</code> method will receive
333 * the same {@link RuntimeException}.
334 *
335 * <p>
336 * When a new {@link Validator} object is created, initially
337 * this field is set to null.
338 *
339 * @param resourceResolver
340 * A new resource resolver to be set. This parameter can be null.
341 */
342 public abstract void setResourceResolver(LSResourceResolver resourceResolver);
343
344 /**
345 * Gets the current {@link LSResourceResolver} set to this {@link Validator}.
346 *
347 * @return
348 * This method returns the object that was last set through
349 * the {@link #setResourceResolver(LSResourceResolver)} method, or null
350 * if that method has never been called since this {@link Validator}
351 * has created.
352 *
353 * @see #setErrorHandler(ErrorHandler)
354 */
355 public abstract LSResourceResolver getResourceResolver();
356
357
358
359 /**
360 * Look up the value of a feature flag.
361 *
362 * <p>The feature name is any fully-qualified URI. It is
363 * possible for a {@link Validator} to recognize a feature name but
364 * temporarily be unable to return its value.
365 * Some feature values may be available only in specific
366 * contexts, such as before, during, or after a validation.
367 *
368 * <p>Implementors are free (and encouraged) to invent their own features,
369 * using names built on their own URIs.</p>
370 *
371 * @param name The feature name, which is a non-null fully-qualified URI.
372 *
373 * @return The current value of the feature (true or false).
374 *
375 * @throws SAXNotRecognizedException If the feature
376 * value can't be assigned or retrieved.
377 * @throws SAXNotSupportedException When the
378 * {@link Validator} recognizes the feature name but
379 * cannot determine its value at this time.
380 * @throws NullPointerException
381 * When the name parameter is null.
382 *
383 * @see #setFeature(String, boolean)
384 */
385 public boolean getFeature(String name)
386 throws SAXNotRecognizedException, SAXNotSupportedException {
387
388 if (name == null) {
389 throw new NullPointerException("the name parameter is null");
390 }
391
392 throw new SAXNotRecognizedException(name);
393 }
394
395 /**
396 * Set the value of a feature flag.
397 *
398 * <p>
399 * Feature can be used to control the way a {@link Validator}
400 * parses schemas, although {@link Validator}s are not required
401 * to recognize any specific feature names.</p>
402 *
403 * <p>The feature name is any fully-qualified URI. It is
404 * possible for a {@link Validator} to expose a feature value but
405 * to be unable to change the current value.
406 * Some feature values may be immutable or mutable only
407 * in specific contexts, such as before, during, or after
408 * a validation.</p>
409 *
410 * @param name The feature name, which is a non-null fully-qualified URI.
411 * @param value The requested value of the feature (true or false).
412 *
413 * @throws SAXNotRecognizedException If the feature
414 * value can't be assigned or retrieved.
415 * @throws SAXNotSupportedException When the
416 * {@link Validator} recognizes the feature name but
417 * cannot set the requested value.
418 * @throws NullPointerException
419 * When the name parameter is null.
420 *
421 * @see #getFeature(String)
422 */
423 public void setFeature(String name, boolean value)
424 throws SAXNotRecognizedException, SAXNotSupportedException {
425
426 if (name == null) {
427 throw new NullPointerException("the name parameter is null");
428 }
429
430 throw new SAXNotRecognizedException(name);
431 }
432
433 /**
434 * Set the value of a property.
435 *
436 * <p>The property name is any fully-qualified URI. It is
437 * possible for a {@link Validator} to recognize a property name but
438 * to be unable to change the current value.
439 * Some property values may be immutable or mutable only
440 * in specific contexts, such as before, during, or after
441 * a validation.</p>
442 *
443 * <p>
444 * All implementations that implement JAXP 1.5 or newer are required to
445 * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
446 * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
447 * </p>
448 * <ul>
449 * <li>
450 * <p>Access to external DTDs in source or Schema file is restricted to
451 * the protocols specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD}
452 * property. If access is denied during validation due to the restriction
453 * of this property, {@link org.xml.sax.SAXException} will be thrown by the
454 * {@link #validate(Source)} method.</p>
455 *
456 * <p>Access to external reference set by the schemaLocation attribute is
457 * restricted to the protocols specified by the
458 * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
459 * If access is denied during validation due to the restriction of this property,
460 * {@link org.xml.sax.SAXException} will be thrown by the
461 * {@link #validate(Source)} method.</p>
462 * </li>
463 * </ul>
464 *
465 * @param name The property name, which is a non-null fully-qualified URI.
466 * @param object The requested value for the property.
467 *
468 * @throws SAXNotRecognizedException If the property
469 * value can't be assigned or retrieved.
470 * @throws SAXNotSupportedException When the
471 * {@link Validator} recognizes the property name but
472 * cannot set the requested value.
473 * @throws NullPointerException
474 * When the name parameter is null.
475 */
476 public void setProperty(String name, Object object)
477 throws SAXNotRecognizedException, SAXNotSupportedException {
478
479 if (name == null) {
480 throw new NullPointerException("the name parameter is null");
481 }
482
483 throw new SAXNotRecognizedException(name);
484 }
485
486 /**
487 * Look up the value of a property.
488 *
489 * <p>The property name is any fully-qualified URI. It is
490 * possible for a {@link Validator} to recognize a property name but
491 * temporarily be unable to return its value.
492 * Some property values may be available only in specific
493 * contexts, such as before, during, or after a validation.</p>
494 *
495 * <p>{@link Validator}s are not required to recognize any specific
496 * property names.</p>
497 *
498 * <p>Implementors are free (and encouraged) to invent their own properties,
499 * using names built on their own URIs.</p>
500 *
501 * @param name The property name, which is a non-null fully-qualified URI.
502 *
503 * @return The current value of the property.
504 *
505 * @throws SAXNotRecognizedException If the property
506 * value can't be assigned or retrieved.
507 * @throws SAXNotSupportedException When the
508 * XMLReader recognizes the property name but
509 * cannot determine its value at this time.
510 * @throws NullPointerException
511 * When the name parameter is null.
512 *
513 * @see #setProperty(String, Object)
514 */
515 public Object getProperty(String name)
516 throws SAXNotRecognizedException, SAXNotSupportedException {
517
518 if (name == null) {
519 throw new NullPointerException("the name parameter is null");
520 }
521
522 throw new SAXNotRecognizedException(name);
523 }
524 }