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 05:55:40 -0700 (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 */ ValidatorHandler()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 */ setContentHandler(ContentHandler receiver)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 */ getContentHandler()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 */ setErrorHandler(ErrorHandler errorHandler)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 */ getErrorHandler()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 */ setResourceResolver(LSResourceResolver resourceResolver)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 */ getResourceResolver()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 */ getTypeInfoProvider()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 */ getFeature(String name)349 public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException { 350 if (name == null) { 351 throw new NullPointerException("name == null"); 352 } 353 throw new SAXNotRecognizedException(name); 354 } 355 356 /** 357 * Set the value of a feature flag. 358 * 359 * <p> 360 * Feature can be used to control the way a {@link ValidatorHandler} 361 * parses schemas, although {@link ValidatorHandler}s are not required 362 * to recognize any specific property names.</p> 363 * 364 * <p>The feature name is any fully-qualified URI. It is 365 * possible for a {@link ValidatorHandler} to expose a feature value but 366 * to be unable to change the current value. 367 * Some feature values may be immutable or mutable only 368 * in specific contexts, such as before, during, or after 369 * a validation.</p> 370 * 371 * @param name The feature name, which is a non-null fully-qualified URI. 372 * @param value The requested value of the feature (true or false). 373 * 374 * @exception org.xml.sax.SAXNotRecognizedException If the feature 375 * value can't be assigned or retrieved. 376 * @exception org.xml.sax.SAXNotSupportedException When the 377 * {@link ValidatorHandler} recognizes the feature name but 378 * cannot set the requested value. 379 * @throws NullPointerException 380 * When the name parameter is null. 381 * 382 * @see #getFeature(String) 383 */ setFeature(String name, boolean value)384 public void setFeature(String name, boolean value) throws SAXNotRecognizedException, SAXNotSupportedException { 385 if (name == null) { 386 throw new NullPointerException("name == null"); 387 } 388 throw new SAXNotRecognizedException(name); 389 } 390 391 /** 392 * Set the value of a property. 393 * 394 * <p>The property name is any fully-qualified URI. It is 395 * possible for a {@link ValidatorHandler} to recognize a property name but 396 * to be unable to change the current value. 397 * Some property values may be immutable or mutable only 398 * in specific contexts, such as before, during, or after 399 * a validation.</p> 400 * 401 * <p>{@link ValidatorHandler}s are not required to recognize setting 402 * any specific property names.</p> 403 * 404 * @param name The property name, which is a non-null fully-qualified URI. 405 * @param object The requested value for the property. 406 * 407 * @exception org.xml.sax.SAXNotRecognizedException If the property 408 * value can't be assigned or retrieved. 409 * @exception org.xml.sax.SAXNotSupportedException When the 410 * {@link ValidatorHandler} recognizes the property name but 411 * cannot set the requested value. 412 * @throws NullPointerException 413 * When the name parameter is null. 414 */ setProperty(String name, Object object)415 public void setProperty(String name, Object object) throws SAXNotRecognizedException, SAXNotSupportedException { 416 if (name == null) { 417 throw new NullPointerException("name == null"); 418 } 419 throw new SAXNotRecognizedException(name); 420 } 421 422 /** 423 * Look up the value of a property. 424 * 425 * <p>The property name is any fully-qualified URI. It is 426 * possible for a {@link ValidatorHandler} to recognize a property name but 427 * temporarily be unable to return its value. 428 * Some property values may be available only in specific 429 * contexts, such as before, during, or after a validation.</p> 430 * 431 * <p>{@link ValidatorHandler}s are not required to recognize any specific 432 * property names.</p> 433 * 434 * <p>Implementors are free (and encouraged) to invent their own properties, 435 * using names built on their own URIs.</p> 436 * 437 * @param name The property name, which is a non-null fully-qualified URI. 438 * @return The current value of the property. 439 * @exception org.xml.sax.SAXNotRecognizedException If the property 440 * value can't be assigned or retrieved. 441 * @exception org.xml.sax.SAXNotSupportedException When the 442 * XMLReader recognizes the property name but 443 * cannot determine its value at this time. 444 * @throws NullPointerException 445 * When the name parameter is null. 446 * @see #setProperty(String, Object) 447 */ getProperty(String name)448 public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException { 449 if (name == null) { 450 throw new NullPointerException("name == null"); 451 } 452 throw new SAXNotRecognizedException(name); 453 } 454 } 455