1 /*
2 * Copyright (c) 2003, 2005, 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 org.w3c.dom.ls.LSResourceResolver;
29 import org.xml.sax.ContentHandler;
30 import org.xml.sax.ErrorHandler;
31 import org.xml.sax.SAXNotRecognizedException;
32 import org.xml.sax.SAXNotSupportedException;
33
34 /**
35 * Streaming validator that works on SAX stream.
36 *
37 * <p>
38 * A {@link ValidatorHandler} object is not thread-safe and not reentrant.
39 * In other words, it is the application's responsibility to make
40 * sure that one {@link ValidatorHandler} object is not used from
41 * more than one thread at any given time.
42 *
43 * <p>
44 * {@link ValidatorHandler} checks if the SAX events follow
45 * the set of constraints described in the associated {@link Schema},
46 * and additionally it may modify the SAX events (for example
47 * by adding default values, etc.)
48 *
49 * <p>
50 * {@link ValidatorHandler} extends from {@link ContentHandler},
51 * but it refines the underlying {@link ContentHandler} in
52 * the following way:
53 * <ol>
54 * <li>startElement/endElement events must receive non-null String
55 * for <code>uri</code>, <code>localName</code>, and <code>qname</code>,
56 * even though SAX allows some of them to be null.
57 * Similarly, the user-specified {@link ContentHandler} will receive non-null
58 * Strings for all three parameters.
59 *
60 * <li>Applications must ensure that {@link ValidatorHandler}'s
61 * {@link ContentHandler#startPrefixMapping(String,String)} and
62 * {@link ContentHandler#endPrefixMapping(String)} are invoked
63 * properly. Similarly, the user-specified {@link ContentHandler}
64 * will receive startPrefixMapping/endPrefixMapping events.
65 * If the {@link ValidatorHandler} introduces additional namespace
66 * bindings, the user-specified {@link ContentHandler} will receive
67 * additional startPrefixMapping/endPrefixMapping events.
68 *
69 * <li>{@link org.xml.sax.Attributes} for the
70 * {@link ContentHandler#startElement(String,String,String,Attributes)} method
71 * may or may not include xmlns* attributes.
72 * </ol>
73 *
74 * <p>
75 * A {@link ValidatorHandler} is automatically reset every time
76 * the startDocument method is invoked.
77 *
78 * <h2>Recognized Properties and Features</h2>
79 * <p>
80 * This spec defines the following feature that must be recognized
81 * by all {@link ValidatorHandler} implementations.
82 *
83 * <h3><code>http://xml.org/sax/features/namespace-prefixes</code></h3>
84 * <p>
85 * This feature controls how a {@link ValidatorHandler} introduces
86 * namespace bindings that were not present in the original SAX event
87 * stream.
88 * When this feature is set to true, it must make
89 * sure that the user's {@link ContentHandler} will see
90 * the corresponding <code>xmlns*</code> attribute in
91 * the {@link org.xml.sax.Attributes} object of the
92 * {@link ContentHandler#startElement(String,String,String,Attributes)}
93 * callback. Otherwise, <code>xmlns*</code> attributes must not be
94 * added to {@link org.xml.sax.Attributes} that's passed to the
95 * user-specified {@link ContentHandler}.
96 * <p>
97 * (Note that regardless of this switch, namespace bindings are
98 * always notified to applications through
99 * {@link ContentHandler#startPrefixMapping(String,String)} and
100 * {@link ContentHandler#endPrefixMapping(String)} methods of the
101 * {@link ContentHandler} specified by the user.)
102 *
103 * <p>
104 * Note that this feature does <em>NOT</em> affect the way
105 * a {@link ValidatorHandler} receives SAX events. It merely
106 * changes the way it augments SAX events.
107 *
108 * <p>This feature is set to <code>false</code> by default.</p>
109 *
110 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
111 * @since 1.5
112 */
113 public abstract class ValidatorHandler implements ContentHandler {
114
115 /**
116 * <p>Constructor for derived classes.</p>
117 *
118 * <p>The constructor does nothing.</p>
119 *
120 * <p>Derived classes must create {@link ValidatorHandler} objects that have
121 * <code>null</code> {@link ErrorHandler} and
122 * <code>null</code> {@link LSResourceResolver}.</p>
123 */
124 protected ValidatorHandler() {
125 }
126
127 /**
128 * Sets the {@link ContentHandler} which receives
129 * the augmented validation result.
130 *
131 * <p>
132 * When a {@link ContentHandler} is specified, a
133 * {@link ValidatorHandler} will work as a filter
134 * and basically copy the incoming events to the
135 * specified {@link ContentHandler}.
136 *
137 * <p>
138 * In doing so, a {@link ValidatorHandler} may modify
139 * the events, for example by adding defaulted attributes.
140 *
141 * <p>
142 * A {@link ValidatorHandler} may buffer events to certain
143 * extent, but to allow {@link ValidatorHandler} to be used
144 * by a parser, the following requirement has to be met.
145 *
146 * <ol>
147 * <li>When
148 * {@link ContentHandler#startElement(String, String, String, Attributes)},
149 * {@link ContentHandler#endElement(String, String, String)},
150 * {@link ContentHandler#startDocument()}, or
151 * {@link ContentHandler#endDocument()}
152 * are invoked on a {@link ValidatorHandler},
153 * the same method on the user-specified {@link ContentHandler}
154 * must be invoked for the same event before the callback
155 * returns.
156 * <li>{@link ValidatorHandler} may not introduce new elements that
157 * were not present in the input.
158 *
159 * <li>{@link ValidatorHandler} may not remove attributes that were
160 * present in the input.
161 * </ol>
162 *
163 * <p>
164 * When a callback method on the specified {@link ContentHandler}
165 * throws an exception, the same exception object must be thrown
166 * from the {@link ValidatorHandler}. The {@link ErrorHandler}
167 * should not be notified of such an exception.
168 *
169 * <p>
170 * This method can be called even during a middle of a validation.
171 *
172 * @param receiver
173 * A {@link ContentHandler} or a null value.
174 */
175 public abstract void setContentHandler(ContentHandler receiver);
176
177 /**
178 * Gets the {@link ContentHandler} which receives the
179 * augmented validation result.
180 *
181 * @return
182 * This method returns the object that was last set through
183 * the {@link #getContentHandler()} method, or null
184 * if that method has never been called since this {@link ValidatorHandler}
185 * has created.
186 *
187 * @see #setContentHandler(ContentHandler)
188 */
189 public abstract ContentHandler getContentHandler();
190
191 /**
192 * Sets the {@link ErrorHandler} to receive errors encountered
193 * during the validation.
194 *
195 * <p>
196 * Error handler can be used to customize the error handling process
197 * during a validation. When an {@link ErrorHandler} is set,
198 * errors found during the validation will be first sent
199 * to the {@link ErrorHandler}.
200 *
201 * <p>
202 * The error handler can abort further validation immediately
203 * by throwing {@link org.xml.sax.SAXException} from the handler. Or for example
204 * it can print an error to the screen and try to continue the
205 * validation by returning normally from the {@link ErrorHandler}
206 *
207 * <p>
208 * If any {@link Throwable} is thrown from an {@link ErrorHandler},
209 * the same {@link Throwable} object will be thrown toward the
210 * root of the call stack.
211 *
212 * <p>
213 * {@link ValidatorHandler} is not allowed to
214 * throw {@link org.xml.sax.SAXException} without first reporting it to
215 * {@link ErrorHandler}.
216 *
217 * <p>
218 * When the {@link ErrorHandler} is null, the implementation will
219 * behave as if the following {@link ErrorHandler} is set:
220 * <pre>
221 * class DraconianErrorHandler implements {@link ErrorHandler} {
222 * public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
223 * throw e;
224 * }
225 * public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
226 * throw e;
227 * }
228 * public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
229 * // noop
230 * }
231 * }
232 * </pre>
233 *
234 * <p>
235 * When a new {@link ValidatorHandler} object is created, initially
236 * this field is set to null.
237 *
238 * @param errorHandler
239 * A new error handler to be set. This parameter can be null.
240 */
241 public abstract void setErrorHandler(ErrorHandler errorHandler);
242
243 /**
244 * Gets the current {@link ErrorHandler} set to this {@link ValidatorHandler}.
245 *
246 * @return
247 * This method returns the object that was last set through
248 * the {@link #setErrorHandler(ErrorHandler)} method, or null
249 * if that method has never been called since this {@link ValidatorHandler}
250 * has created.
251 *
252 * @see #setErrorHandler(ErrorHandler)
253 */
254 public abstract ErrorHandler getErrorHandler();
255
256 /**
257 * Sets the {@link LSResourceResolver} to customize
258 * resource resolution while in a validation episode.
259 *
260 * <p>
261 * {@link ValidatorHandler} uses a {@link LSResourceResolver}
262 * when it needs to locate external resources while a validation,
263 * although exactly what constitutes "locating external resources" is
264 * up to each schema language.
265 *
266 * <p>
267 * When the {@link LSResourceResolver} is null, the implementation will
268 * behave as if the following {@link LSResourceResolver} is set:
269 * <pre>
270 * class DumbLSResourceResolver implements {@link LSResourceResolver} {
271 * public {@link org.w3c.dom.ls.LSInput} resolveResource(
272 * String publicId, String systemId, String baseURI) {
273 *
274 * return null; // always return null
275 * }
276 * }
277 * </pre>
278 *
279 * <p>
280 * If a {@link LSResourceResolver} throws a {@link RuntimeException}
281 * (or instances of its derived classes),
282 * then the {@link ValidatorHandler} will abort the parsing and
283 * the caller of the <code>validate</code> method will receive
284 * the same {@link RuntimeException}.
285 *
286 * <p>
287 * When a new {@link ValidatorHandler} object is created, initially
288 * this field is set to null.
289 *
290 * @param resourceResolver
291 * A new resource resolver to be set. This parameter can be null.
292 */
293 public abstract void setResourceResolver(LSResourceResolver resourceResolver);
294
295 /**
296 * Gets the current {@link LSResourceResolver} set to this {@link ValidatorHandler}.
297 *
298 * @return
299 * This method returns the object that was last set through
300 * the {@link #setResourceResolver(LSResourceResolver)} method, or null
301 * if that method has never been called since this {@link ValidatorHandler}
302 * has created.
303 *
304 * @see #setErrorHandler(ErrorHandler)
305 */
306 public abstract LSResourceResolver getResourceResolver();
307
308 /**
309 * Obtains the {@link TypeInfoProvider} implementation of this
310 * {@link ValidatorHandler}.
311 *
312 * <p>
313 * The obtained {@link TypeInfoProvider} can be queried during a parse
314 * to access the type information determined by the validator.
315 *
316 * <p>
317 * Some schema languages do not define the notion of type,
318 * for those languages, this method may not be supported.
319 * However, to be compliant with this specification, implementations
320 * for W3C XML Schema 1.0 must support this operation.
321 *
322 * @return
323 * null if the validator / schema language does not support
324 * the notion of {@link org.w3c.dom.TypeInfo}.
325 * Otherwise a non-null valid {@link TypeInfoProvider}.
326 */
327 public abstract TypeInfoProvider getTypeInfoProvider();
328
329
330 /**
331 * Look up the value of a feature flag.
332 *
333 * <p>The feature name is any fully-qualified URI. It is
334 * possible for a {@link ValidatorHandler} to recognize a feature name but
335 * temporarily be unable to return its value.
336 * Some feature values may be available only in specific
337 * contexts, such as before, during, or after a validation.
338 *
339 * <p>Implementors are free (and encouraged) to invent their own features,
340 * using names built on their own URIs.</p>
341 *
342 * @param name The feature name, which is a non-null fully-qualified URI.
343 *
344 * @return The current value of the feature (true or false).
345 *
346 * @throws SAXNotRecognizedException If the feature
347 * value can't be assigned or retrieved.
348 * @throws SAXNotSupportedException When the
349 * {@link ValidatorHandler} recognizes the feature name but
350 * cannot determine its value at this time.
351 * @throws NullPointerException When <code>name</code> is <code>null</code>.
352 *
353 * @see #setFeature(String, boolean)
354 */
355 public boolean getFeature(String name)
356 throws SAXNotRecognizedException, SAXNotSupportedException {
357
358 if (name == null) {
359 throw new NullPointerException();
360 }
361
362 throw new SAXNotRecognizedException(name);
363 }
364
365 /**
366 * <p>Set a feature for this <code>ValidatorHandler</code>.</p>
367 *
368 * <p>Feature can be used to control the way a
369 * {@link ValidatorHandler} parses schemas. The feature name is
370 * any fully-qualified URI. It is possible for a
371 * {@link SchemaFactory} to
372 * expose a feature value but to be unable to change the current
373 * value. Some feature values may be immutable or mutable only in
374 * specific contexts, such as before, during, or after a
375 * validation.</p>
376 *
377 * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
378 * When the feature is:</p>
379 * <ul>
380 * <li>
381 * <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
382 * Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
383 * If XML processing is limited for security reasons, it will be reported via a call to the registered
384 * {@link ErrorHandler#fatalError(SAXParseException exception)}.
385 * See {@link #setErrorHandler(ErrorHandler errorHandler)}.
386 * </li>
387 * <li>
388 * <code>false</code>: the implementation will processing XML according to the XML specifications without
389 * regard to possible implementation limits.
390 * </li>
391 * </ul>
392 *
393 * @param name The feature name, which is a non-null fully-qualified URI.
394 * @param value The requested value of the feature (true or false).
395 *
396 * @throws SAXNotRecognizedException If the feature
397 * value can't be assigned or retrieved.
398 * @throws SAXNotSupportedException When the
399 * {@link ValidatorHandler} recognizes the feature name but
400 * cannot set the requested value.
401 * @throws NullPointerException When <code>name</code> is <code>null</code>.
402 *
403 * @see #getFeature(String)
404 */
405 public void setFeature(String name, boolean value)
406 throws SAXNotRecognizedException, SAXNotSupportedException {
407
408 if (name == null) {
409 throw new NullPointerException();
410 }
411
412 throw new SAXNotRecognizedException(name);
413 }
414
415 /**
416 * Set the value of a property.
417 *
418 * <p>The property name is any fully-qualified URI. It is
419 * possible for a {@link ValidatorHandler} to recognize a property name but
420 * to be unable to change the current value.
421 * Some property values may be immutable or mutable only
422 * in specific contexts, such as before, during, or after
423 * a validation.</p>
424 *
425 * <p>{@link ValidatorHandler}s are not required to recognize setting
426 * any specific property names.</p>
427 *
428 * @param name The property name, which is a non-null fully-qualified URI.
429 * @param object The requested value for the property.
430 *
431 * @throws SAXNotRecognizedException If the property
432 * value can't be assigned or retrieved.
433 * @throws SAXNotSupportedException When the
434 * {@link ValidatorHandler} recognizes the property name but
435 * cannot set the requested value.
436 * @throws NullPointerException When <code>name</code> is <code>null</code>.
437 */
438 public void setProperty(String name, Object object)
439 throws SAXNotRecognizedException, SAXNotSupportedException {
440
441 if (name == null) {
442 throw new NullPointerException();
443 }
444
445 throw new SAXNotRecognizedException(name);
446 }
447
448 /**
449 * Look up the value of a property.
450 *
451 * <p>The property name is any fully-qualified URI. It is
452 * possible for a {@link ValidatorHandler} to recognize a property name but
453 * temporarily be unable to return its value.
454 * Some property values may be available only in specific
455 * contexts, such as before, during, or after a validation.</p>
456 *
457 * <p>{@link ValidatorHandler}s are not required to recognize any specific
458 * property names.</p>
459 *
460 * <p>Implementors are free (and encouraged) to invent their own properties,
461 * using names built on their own URIs.</p>
462 *
463 * @param name The property name, which is a non-null fully-qualified URI.
464 *
465 * @return The current value of the property.
466 *
467 * @throws SAXNotRecognizedException If the property
468 * value can't be assigned or retrieved.
469 * @throws SAXNotSupportedException When the
470 * XMLReader recognizes the property name but
471 * cannot determine its value at this time.
472 * @throws NullPointerException When <code>name</code> is <code>null</code>.
473 *
474 * @see #setProperty(String, Object)
475 */
476 public Object getProperty(String name)
477 throws SAXNotRecognizedException, SAXNotSupportedException {
478
479 if (name == null) {
480 throw new NullPointerException();
481 }
482
483 throw new SAXNotRecognizedException(name);
484 }
485 }