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