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 enity 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 }