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 26package javax.xml.validation; 27 28import org.w3c.dom.ls.LSResourceResolver; 29import org.xml.sax.ContentHandler; 30import org.xml.sax.ErrorHandler; 31import org.xml.sax.SAXNotRecognizedException; 32import 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 */ 113public 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} 486