< prev index next >

src/java.xml/share/classes/javax/xml/validation/Validator.java

Print this page




  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 java.io.IOException;
  29 
  30 import javax.xml.transform.Result;
  31 import javax.xml.transform.Source;
  32 
  33 import org.w3c.dom.ls.LSResourceResolver;
  34 import org.xml.sax.ErrorHandler;
  35 import org.xml.sax.SAXException;
  36 import org.xml.sax.SAXNotRecognizedException;
  37 import org.xml.sax.SAXNotSupportedException;
  38 
  39 /**
  40  * <p>A processor that checks an XML document against {@link Schema}.</p>
  41  *
  42  * <p>
  43  * A validator object is not thread-safe and not reentrant.
  44  * In other words, it is the application's responsibility to make
  45  * sure that one {@link Validator} object is not used from
  46  * more than one thread at any given time, and while the <code>validate</code>
  47  * method is invoked, applications may not recursively call
  48  * the <code>validate</code> method.
  49  * <p>
  50  *
  51  *
  52  * @author  <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
  53  * @since 1.5
  54  */
  55 public abstract class Validator {
  56 
  57     /**
  58      * Constructor for derived classes.
  59      *
  60      * <p>The constructor does nothing.</p>
  61      *
  62      * <p>Derived classes must create {@link Validator} objects that have
  63      * <code>null</code> {@link ErrorHandler} and
  64      * <code>null</code> {@link LSResourceResolver}.
  65      * </p>
  66      */
  67     protected Validator() {
  68     }
  69 
  70         /**
  71          * <p>Reset this <code>Validator</code> to its original configuration.</p>
  72          *
  73          * <p><code>Validator</code> is reset to the same state as when it was created with
  74          * {@link Schema#newValidator()}.
  75          * <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s
  76          * thus saving resources associated with the creation of new <code>Validator</code>s.</p>
  77          *
  78          * <p>The reset <code>Validator</code> is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler}
  79          * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.  It is guaranteed to have a functionally equal
  80          * <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p>


  81          */
  82         public abstract void reset();
  83 
  84     /**
  85      * Validates the specified input.
  86      *
  87      * <p>This is just a convenience method for
  88      * {@link #validate(Source source, Result result)}
  89      * with <code>result</code> of <code>null</code>.</p>
  90      *
  91      * @param source
  92      *      XML to be validated. Must be an XML document or
  93      *      XML element and must not be null. For backwards compatibility,
  94      *      the results of attempting to validate anything other than
  95      *      a document or element are implementation-dependent.
  96      *      Implementations must either recognize and process the input
  97      *      or throw an IllegalArgumentException.
  98      *
  99      * @throws IllegalArgumentException
 100      *      If the <code>Source</code>
 101      *      is an XML artifact that the implementation cannot
 102      *      validate (for example, a processing instruction).
 103      *
 104      * @throws SAXException
 105      *      If the {@link ErrorHandler} throws a {@link SAXException} or
 106      *      if a fatal error is found and the {@link ErrorHandler} returns
 107      *      normally.
 108      *
 109      * @throws IOException
 110      *      If the validator is processing a
 111      *      {@link javax.xml.transform.sax.SAXSource} and the
 112      *      underlying {@link org.xml.sax.XMLReader} throws an
 113      *      {@link IOException}.
 114      *
 115      *
 116      * @throws NullPointerException If <code>source</code> is
 117      *   <code>null</code>.
 118      *
 119      * @see #validate(Source source, Result result)
 120      */
 121     public void validate(Source source)
 122         throws SAXException, IOException {
 123 
 124         validate(source, null);
 125     }
 126 
 127     /**
 128      * <p>Validates the specified input and send the augmented validation
 129      * result to the specified output.</p>
 130      *
 131      * <p>This method places the following restrictions on the types of
 132      * the {@link Source}/{@link Result} accepted.</p>
 133      *
 134      * <table border=1>
 135      * <thead>
 136      *  <tr>
 137      *   <th colspan="5"><code>Source</code> / <code>Result</code> Accepted</th>
 138      *  </tr>
 139      *  <tr>
 140      *   <th></th>
 141      *   <th>{@link javax.xml.transform.stream.StreamSource}</th>
 142      *   <th>{@link javax.xml.transform.sax.SAXSource}</th>
 143      *   <th>{@link javax.xml.transform.dom.DOMSource}</th>
 144      *   <th>{@link javax.xml.transform.stax.StAXSource}</th>
 145      *  </tr>
 146      * </thead>
 147      * <tbody align="center">
 148      *  <tr>
 149      *   <td><code>null</code></td>
 150      *   <td>OK</td>
 151      *   <td>OK</td>
 152      *   <td>OK</td>
 153      *   <td>OK</td>
 154      *  </tr>
 155      *  <tr>
 156      *   <th>{@link javax.xml.transform.stream.StreamResult}</th>
 157      *   <td>OK</td>
 158      *   <td><code>IllegalArgumentException</code></td>
 159      *   <td><code>IllegalArgumentException</code></td>
 160      *   <td><code>IllegalArgumentException</code></td>
 161      *  </tr>
 162      *  <tr>
 163      *   <th>{@link javax.xml.transform.sax.SAXResult}</th>
 164      *   <td><code>IllegalArgumentException</code></td>
 165      *   <td>OK</td>
 166      *   <td><code>IllegalArgumentException</code></td>
 167      *   <td><code>IllegalArgumentException</code></td>
 168      *  </tr>
 169      *  <tr>
 170      *   <th>{@link javax.xml.transform.dom.DOMResult}</th>
 171      *   <td><code>IllegalArgumentException</code></td>
 172      *   <td><code>IllegalArgumentException</code></td>
 173      *   <td>OK</td>
 174      *   <td><code>IllegalArgumentException</code></td>
 175      *  </tr>
 176      *  <tr>
 177      *   <th>{@link javax.xml.transform.stax.StAXResult}</th>
 178      *   <td><code>IllegalArgumentException</code></td>
 179      *   <td><code>IllegalArgumentException</code></td>
 180      *   <td><code>IllegalArgumentException</code></td>
 181      *   <td>OK</td>
 182      *  </tr>
 183      * </tbody>
 184      * </table>
 185      *
 186      * <p>To validate one <code>Source</code> into another kind of
 187      * <code>Result</code>, use the identity transformer (see
 188      * {@link javax.xml.transform.TransformerFactory#newTransformer()}).</p>
 189      *
 190      * <p>Errors found during the validation is sent to the specified
 191      * {@link ErrorHandler}.</p>
 192      *
 193      * <p>If a document is valid, or if a document contains some errors
 194      * but none of them were fatal and the <code>ErrorHandler</code> didn't
 195      * throw any exception, then the method returns normally.</p>
 196      *
 197      * @param source
 198      *      XML to be validated. Must be an XML document or
 199      *      XML element and must not be null. For backwards compatibility,
 200      *      the results of attempting to validate anything other than
 201      *      a document or element are implementation-dependent.
 202      *      Implementations must either recognize and process the input
 203      *      or throw an IllegalArgumentException.
 204      *
 205      * @param result
 206      *      The <code>Result</code> object that receives (possibly augmented)
 207      *      XML. This parameter can be null if the caller is not interested
 208      *      in it.
 209      *
 210      *      Note that when a <code>DOMResult</code> is used,
 211      *      a validator might just pass the same DOM node from
 212      *      <code>DOMSource</code> to <code>DOMResult</code>
 213      *      (in which case <code>source.getNode()==result.getNode()</code>),
 214      *      it might copy the entire DOM tree, or it might alter the
 215      *      node given by the source.
 216      *
 217      * @throws IllegalArgumentException
 218      *      If the <code>Result</code> type doesn't match the
 219      *      <code>Source</code> type of if the <code>Source</code>
 220      *      is an XML artifact that the implementation cannot
 221      *      validate (for example, a processing instruction).
 222      * @throws SAXException
 223      *      If the <code>ErrorHandler</code> throws a
 224      *      <code>SAXException</code> or
 225      *      if a fatal error is found and the <code>ErrorHandler</code> returns
 226      *      normally.
 227      * @throws IOException
 228      *      If the validator is processing a
 229      *      <code>SAXSource</code> and the
 230      *      underlying {@link org.xml.sax.XMLReader} throws an
 231      *      <code>IOException</code>.
 232      * @throws NullPointerException
 233      *      If the <code>source</code> parameter is <code>null</code>.
 234      *
 235      * @see #validate(Source source)
 236      */
 237     public abstract void validate(Source source, Result result)
 238         throws SAXException, IOException;
 239 
 240     /**
 241      * Sets the {@link ErrorHandler} to receive errors encountered
 242      * during the <code>validate</code> method invocation.
 243      *
 244      * <p>
 245      * Error handler can be used to customize the error handling process
 246      * during a validation. When an {@link ErrorHandler} is set,
 247      * errors found during the validation will be first sent
 248      * to the {@link ErrorHandler}.
 249      *
 250      * <p>
 251      * The error handler can abort further validation immediately
 252      * by throwing {@link SAXException} from the handler. Or for example
 253      * it can print an error to the screen and try to continue the
 254      * validation by returning normally from the {@link ErrorHandler}
 255      *
 256      * <p>
 257      * If any {@link Throwable} is thrown from an {@link ErrorHandler},
 258      * the caller of the <code>validate</code> method will be thrown
 259      * the same {@link Throwable} object.
 260      *
 261      * <p>
 262      * {@link Validator} is not allowed to
 263      * throw {@link SAXException} without first reporting it to
 264      * {@link ErrorHandler}.
 265      *
 266      * <p>
 267      * When the {@link ErrorHandler} is null, the implementation will
 268      * behave as if the following {@link ErrorHandler} is set:
 269      * <pre>
 270      * class DraconianErrorHandler implements {@link ErrorHandler} {
 271      *     public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 272      *         throw e;
 273      *     }
 274      *     public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 275      *         throw e;
 276      *     }
 277      *     public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 278      *         // noop


 312      * although exactly what constitutes "locating external resources" is
 313      * up to each schema language.
 314      *
 315      * <p>
 316      * When the {@link LSResourceResolver} is null, the implementation will
 317      * behave as if the following {@link LSResourceResolver} is set:
 318      * <pre>
 319      * class DumbLSResourceResolver implements {@link LSResourceResolver} {
 320      *     public {@link org.w3c.dom.ls.LSInput} resolveResource(
 321      *         String publicId, String systemId, String baseURI) {
 322      *
 323      *         return null; // always return null
 324      *     }
 325      * }
 326      * </pre>
 327      *
 328      * <p>
 329      * If a {@link LSResourceResolver} throws a {@link RuntimeException}
 330      *  (or instances of its derived classes),
 331      * then the {@link Validator} will abort the parsing and
 332      * the caller of the <code>validate</code> method will receive
 333      * the same {@link RuntimeException}.
 334      *
 335      * <p>
 336      * When a new {@link Validator} object is created, initially
 337      * this field is set to null.
 338      *
 339      * @param   resourceResolver
 340      *      A new resource resolver to be set. This parameter can be null.
 341      */
 342     public abstract void setResourceResolver(LSResourceResolver resourceResolver);
 343 
 344     /**
 345      * Gets the current {@link LSResourceResolver} set to this {@link Validator}.
 346      *
 347      * @return
 348      *      This method returns the object that was last set through
 349      *      the {@link #setResourceResolver(LSResourceResolver)} method, or null
 350      *      if that method has never been called since this {@link Validator}
 351      *      has created.
 352      *
 353      * @see #setErrorHandler(ErrorHandler)
 354      */
 355     public abstract LSResourceResolver getResourceResolver();
 356 
 357 
 358 
 359     /**
 360      * Look up the value of a feature flag.
 361      *
 362      * <p>The feature name is any fully-qualified URI.  It is
 363      * possible for a {@link Validator} to recognize a feature name but
 364      * temporarily be unable to return its value.
 365      * Some feature values may be available only in specific
 366      * contexts, such as before, during, or after a validation.
 367      *
 368      * <p>Implementors are free (and encouraged) to invent their own features,
 369      * using names built on their own URIs.</p>
 370      *
 371      * @param name The feature name, which is a non-null fully-qualified URI.
 372      *
 373      * @return The current value of the feature (true or false).
 374      *
 375      * @throws SAXNotRecognizedException If the feature
 376      *   value can't be assigned or retrieved.
 377      * @throws SAXNotSupportedException When the
 378      *   {@link Validator} recognizes the feature name but
 379      *   cannot determine its value at this time.
 380      * @throws NullPointerException
 381      *   When the name parameter is null.
 382      *
 383      * @see #setFeature(String, boolean)
 384      */
 385     public boolean getFeature(String name)
 386         throws SAXNotRecognizedException, SAXNotSupportedException {
 387 
 388         if (name == null) {
 389             throw new NullPointerException("the name parameter is null");
 390         }
 391 
 392         throw new SAXNotRecognizedException(name);
 393     }
 394 
 395     /**
 396      * Set the value of a feature flag.
 397      *
 398      * <p>
 399      * Feature can be used to control the way a {@link Validator}
 400      * parses schemas, although {@link Validator}s are not required
 401      * to recognize any specific feature names.</p>
 402      *
 403      * <p>The feature name is any fully-qualified URI.  It is
 404      * possible for a {@link Validator} to expose a feature value but
 405      * to be unable to change the current value.
 406      * Some feature values may be immutable or mutable only
 407      * in specific contexts, such as before, during, or after
 408      * a validation.</p>
 409      *
 410      * @param name The feature name, which is a non-null fully-qualified URI.
 411      * @param value The requested value of the feature (true or false).
 412      *
 413      * @throws SAXNotRecognizedException If the feature
 414      *   value can't be assigned or retrieved.
 415      * @throws SAXNotSupportedException When the
 416      *   {@link Validator} recognizes the feature name but
 417      *   cannot set the requested value.
 418      * @throws NullPointerException
 419      *   When the name parameter is null.
 420      *
 421      * @see #getFeature(String)
 422      */
 423     public void setFeature(String name, boolean value)
 424         throws SAXNotRecognizedException, SAXNotSupportedException {
 425 
 426         if (name == null) {
 427             throw new NullPointerException("the name parameter is null");
 428         }
 429 
 430         throw new SAXNotRecognizedException(name);
 431     }
 432 
 433     /**
 434      * Set the value of a property.
 435      *
 436      * <p>The property name is any fully-qualified URI.  It is
 437      * possible for a {@link Validator} to recognize a property name but
 438      * to be unable to change the current value.
 439      * Some property values may be immutable or mutable only
 440      * in specific contexts, such as before, during, or after
 441      * a validation.</p>
 442      *
 443      * <p>
 444      * All implementations that implement JAXP 1.5 or newer are required to
 445      * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
 446      * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
 447      * </p>
 448      * <ul>
 449      *   <li>
 450      *      <p>Access to external DTDs in source or Schema file is restricted to
 451      *      the protocols specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD}
 452      *      property.  If access is denied during validation due to the restriction
 453      *      of this property, {@link org.xml.sax.SAXException} will be thrown by the
 454      *      {@link #validate(Source)} method.</p>
 455      *
 456      *      <p>Access to external reference set by the schemaLocation attribute is
 457      *      restricted to the protocols specified by the
 458      *      {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
 459      *      If access is denied during validation due to the restriction of this property,
 460      *      {@link org.xml.sax.SAXException} will be thrown by the
 461      *      {@link #validate(Source)} method.</p>
 462      *   </li>
 463      * </ul>
 464      *
 465      * @param name The property name, which is a non-null fully-qualified URI.
 466      * @param object The requested value for the property.
 467      *
 468      * @throws SAXNotRecognizedException If the property
 469      *   value can't be assigned or retrieved.
 470      * @throws SAXNotSupportedException When the
 471      *   {@link Validator} recognizes the property name but
 472      *   cannot set the requested value.
 473      * @throws NullPointerException
 474      *   When the name parameter is null.
 475      */
 476     public void setProperty(String name, Object object)
 477         throws SAXNotRecognizedException, SAXNotSupportedException {
 478 
 479         if (name == null) {
 480             throw new NullPointerException("the name parameter is null");
 481         }
 482 
 483         throw new SAXNotRecognizedException(name);
 484     }
 485 
 486     /**
 487      * Look up the value of a property.
 488      *
 489      * <p>The property name is any fully-qualified URI.  It is
 490      * possible for a {@link Validator} to recognize a property name but
 491      * temporarily be unable to return its value.
 492      * Some property values may be available only in specific
 493      * contexts, such as before, during, or after a validation.</p>
 494      *
 495      * <p>{@link Validator}s are not required to recognize any specific
 496      * property names.</p>
 497      *
 498      * <p>Implementors are free (and encouraged) to invent their own properties,
 499      * using names built on their own URIs.</p>
 500      *
 501      * @param name The property name, which is a non-null fully-qualified URI.
 502      *
 503      * @return The current value of the property.
 504      *
 505      * @throws SAXNotRecognizedException If the property
 506      *   value can't be assigned or retrieved.
 507      * @throws SAXNotSupportedException When the
 508      *   XMLReader recognizes the property name but
 509      *   cannot determine its value at this time.
 510      * @throws NullPointerException
 511      *   When the name parameter is null.
 512      *
 513      * @see #setProperty(String, Object)
 514      */
 515     public Object getProperty(String name)
 516         throws SAXNotRecognizedException, SAXNotSupportedException {
 517 
 518         if (name == null) {
 519             throw new NullPointerException("the name parameter is null");


  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 java.io.IOException;
  29 
  30 import javax.xml.transform.Result;
  31 import javax.xml.transform.Source;
  32 
  33 import org.w3c.dom.ls.LSResourceResolver;
  34 import org.xml.sax.ErrorHandler;
  35 import org.xml.sax.SAXException;
  36 import org.xml.sax.SAXNotRecognizedException;
  37 import org.xml.sax.SAXNotSupportedException;
  38 
  39 /**
  40  * A processor that checks an XML document against {@link Schema}.
  41  *
  42  * <p>
  43  * A validator object is not thread-safe and not reentrant.
  44  * In other words, it is the application's responsibility to make
  45  * sure that one {@link Validator} object is not used from
  46  * more than one thread at any given time, and while the {@code validate}
  47  * method is invoked, applications may not recursively call
  48  * the {@code validate} method.

  49  *
  50  *
  51  * @author  <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
  52  * @since 1.5
  53  */
  54 public abstract class Validator {
  55 
  56     /**
  57      * Constructor for derived classes.
  58      *
  59      * <p>The constructor does nothing.
  60      *
  61      * <p>Derived classes must create {@link Validator} objects that have
  62      * {@code null} {@link ErrorHandler} and
  63      * {@code null} {@link LSResourceResolver}.
  64      * 
  65      */
  66     protected Validator() {
  67     }
  68 
  69         /**
  70          * Reset this {@code Validator} to its original configuration.
  71          *
  72          * <p>{@code Validator} is reset to the same state as when it was created with
  73          * {@link Schema#newValidator()}.
  74          * {@code reset()} is designed to allow the reuse of existing {@code Validator}s
  75          * thus saving resources associated with the creation of new {@code Validator}s.
  76          *
  77          * <p>The reset {@code Validator} is not guaranteed to have
  78          * the same {@link LSResourceResolver} or {@link ErrorHandler}
  79          * {@code Object}s, e.g. {@link Object#equals(Object obj)}.
  80          * It is guaranteed to have a functionally equal
  81          * {@code LSResourceResolver} and {@code ErrorHandler}.
  82          */
  83         public abstract void reset();
  84 
  85     /**
  86      * Validates the specified input.
  87      *
  88      * <p>This is just a convenience method for
  89      * {@link #validate(Source source, Result result)}
  90      * with {@code result} of {@code null}.
  91      *
  92      * @param source
  93      *      XML to be validated. Must be an XML document or
  94      *      XML element and must not be null. For backwards compatibility,
  95      *      the results of attempting to validate anything other than
  96      *      a document or element are implementation-dependent.
  97      *      Implementations must either recognize and process the input
  98      *      or throw an IllegalArgumentException.
  99      *
 100      * @throws IllegalArgumentException
 101      *      If the {@code Source}
 102      *      is an XML artifact that the implementation cannot
 103      *      validate (for example, a processing instruction).
 104      *
 105      * @throws SAXException
 106      *      If the {@link ErrorHandler} throws a {@link SAXException} or
 107      *      if a fatal error is found and the {@link ErrorHandler} returns
 108      *      normally.
 109      *
 110      * @throws IOException
 111      *      If the validator is processing a
 112      *      {@link javax.xml.transform.sax.SAXSource} and the
 113      *      underlying {@link org.xml.sax.XMLReader} throws an
 114      *      {@link IOException}.
 115      *
 116      *
 117      * @throws NullPointerException If {@code source} is
 118      *   {@code null}.
 119      *
 120      * @see #validate(Source source, Result result)
 121      */
 122     public void validate(Source source)
 123         throws SAXException, IOException {
 124 
 125         validate(source, null);
 126     }
 127 
 128     /**
 129      * Validates the specified input and send the augmented validation
 130      * result to the specified output.
 131      *
 132      * <p>This method places the following restrictions on the types of
 133      * the {@link Source}/{@link Result} accepted.
 134      *
 135      * <table border=1>
 136      * <thead>
 137      *  <tr>
 138      *   <th colspan="5">{@code Source} / {@code Result} Accepted</th>
 139      *  </tr>
 140      *  <tr>
 141      *   <th></th>
 142      *   <th>{@link javax.xml.transform.stream.StreamSource}</th>
 143      *   <th>{@link javax.xml.transform.sax.SAXSource}</th>
 144      *   <th>{@link javax.xml.transform.dom.DOMSource}</th>
 145      *   <th>{@link javax.xml.transform.stax.StAXSource}</th>
 146      *  </tr>
 147      * </thead>
 148      * <tbody align="center">
 149      *  <tr>
 150      *   <td>{@code null}</td>
 151      *   <td>OK</td>
 152      *   <td>OK</td>
 153      *   <td>OK</td>
 154      *   <td>OK</td>
 155      *  </tr>
 156      *  <tr>
 157      *   <th>{@link javax.xml.transform.stream.StreamResult}</th>
 158      *   <td>OK</td>
 159      *   <td>{@code IllegalArgumentException}</td>
 160      *   <td>{@code IllegalArgumentException}</td>
 161      *   <td>{@code IllegalArgumentException}</td>
 162      *  </tr>
 163      *  <tr>
 164      *   <th>{@link javax.xml.transform.sax.SAXResult}</th>
 165      *   <td>{@code IllegalArgumentException}</td>
 166      *   <td>OK</td>
 167      *   <td>{@code IllegalArgumentException}</td>
 168      *   <td>{@code IllegalArgumentException}</td>
 169      *  </tr>
 170      *  <tr>
 171      *   <th>{@link javax.xml.transform.dom.DOMResult}</th>
 172      *   <td>{@code IllegalArgumentException}</td>
 173      *   <td>{@code IllegalArgumentException}</td>
 174      *   <td>OK</td>
 175      *   <td>{@code IllegalArgumentException}</td>
 176      *  </tr>
 177      *  <tr>
 178      *   <th>{@link javax.xml.transform.stax.StAXResult}</th>
 179      *   <td>{@code IllegalArgumentException}</td>
 180      *   <td>{@code IllegalArgumentException}</td>
 181      *   <td>{@code IllegalArgumentException}</td>
 182      *   <td>OK</td>
 183      *  </tr>
 184      * </tbody>
 185      * </table>
 186      *
 187      * <p>To validate one {@code Source} into another kind of
 188      * {@code Result}, use the identity transformer (see
 189      * {@link javax.xml.transform.TransformerFactory#newTransformer()}).
 190      *
 191      * <p>Errors found during the validation is sent to the specified
 192      * {@link ErrorHandler}.
 193      *
 194      * <p>If a document is valid, or if a document contains some errors
 195      * but none of them were fatal and the {@code ErrorHandler} didn't
 196      * throw any exception, then the method returns normally.
 197      *
 198      * @param source
 199      *      XML to be validated. Must be an XML document or
 200      *      XML element and must not be null. For backwards compatibility,
 201      *      the results of attempting to validate anything other than
 202      *      a document or element are implementation-dependent.
 203      *      Implementations must either recognize and process the input
 204      *      or throw an IllegalArgumentException.
 205      *
 206      * @param result
 207      *      The {@code Result} object that receives (possibly augmented)
 208      *      XML. This parameter can be null if the caller is not interested
 209      *      in it.
 210      *
 211      *      Note that when a {@code DOMResult} is used,
 212      *      a validator might just pass the same DOM node from
 213      *      {@code DOMSource} to {@code DOMResult}
 214      *      (in which case {@code source.getNode()==result.getNode()}),
 215      *      it might copy the entire DOM tree, or it might alter the
 216      *      node given by the source.
 217      *
 218      * @throws IllegalArgumentException
 219      *      If the {@code Result} type doesn't match the
 220      *      {@code Source} type of if the {@code Source}
 221      *      is an XML artifact that the implementation cannot
 222      *      validate (for example, a processing instruction).
 223      * @throws SAXException
 224      *      If the {@code ErrorHandler} throws a
 225      *      {@code SAXException} or
 226      *      if a fatal error is found and the {@code ErrorHandler} returns
 227      *      normally.
 228      * @throws IOException
 229      *      If the validator is processing a
 230      *      {@code SAXSource} and the
 231      *      underlying {@link org.xml.sax.XMLReader} throws an
 232      *      {@code IOException}.
 233      * @throws NullPointerException
 234      *      If the {@code source} parameter is {@code null}.
 235      *
 236      * @see #validate(Source source)
 237      */
 238     public abstract void validate(Source source, Result result)
 239         throws SAXException, IOException;
 240 
 241     /**
 242      * Sets the {@link ErrorHandler} to receive errors encountered
 243      * during the {@code validate} method invocation.
 244      *
 245      * <p>
 246      * Error handler can be used to customize the error handling process
 247      * during a validation. When an {@link ErrorHandler} is set,
 248      * errors found during the validation will be first sent
 249      * to the {@link ErrorHandler}.
 250      *
 251      * <p>
 252      * The error handler can abort further validation immediately
 253      * by throwing {@link SAXException} from the handler. Or for example
 254      * it can print an error to the screen and try to continue the
 255      * validation by returning normally from the {@link ErrorHandler}
 256      *
 257      * <p>
 258      * If any {@link Throwable} is thrown from an {@link ErrorHandler},
 259      * the caller of the {@code validate} method will be thrown
 260      * the same {@link Throwable} object.
 261      *
 262      * <p>
 263      * {@link Validator} is not allowed to
 264      * throw {@link SAXException} without first reporting it to
 265      * {@link ErrorHandler}.
 266      *
 267      * <p>
 268      * When the {@link ErrorHandler} is null, the implementation will
 269      * behave as if the following {@link ErrorHandler} is set:
 270      * <pre>
 271      * class DraconianErrorHandler implements {@link ErrorHandler} {
 272      *     public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 273      *         throw e;
 274      *     }
 275      *     public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 276      *         throw e;
 277      *     }
 278      *     public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 279      *         // noop


 313      * although exactly what constitutes "locating external resources" is
 314      * up to each schema language.
 315      *
 316      * <p>
 317      * When the {@link LSResourceResolver} is null, the implementation will
 318      * behave as if the following {@link LSResourceResolver} is set:
 319      * <pre>
 320      * class DumbLSResourceResolver implements {@link LSResourceResolver} {
 321      *     public {@link org.w3c.dom.ls.LSInput} resolveResource(
 322      *         String publicId, String systemId, String baseURI) {
 323      *
 324      *         return null; // always return null
 325      *     }
 326      * }
 327      * </pre>
 328      *
 329      * <p>
 330      * If a {@link LSResourceResolver} throws a {@link RuntimeException}
 331      *  (or instances of its derived classes),
 332      * then the {@link Validator} will abort the parsing and
 333      * the caller of the {@code validate} method will receive
 334      * the same {@link RuntimeException}.
 335      *
 336      * <p>
 337      * When a new {@link Validator} object is created, initially
 338      * this field is set to null.
 339      *
 340      * @param   resourceResolver
 341      *      A new resource resolver to be set. This parameter can be null.
 342      */
 343     public abstract void setResourceResolver(LSResourceResolver resourceResolver);
 344 
 345     /**
 346      * Gets the current {@link LSResourceResolver} set to this {@link Validator}.
 347      *
 348      * @return
 349      *      This method returns the object that was last set through
 350      *      the {@link #setResourceResolver(LSResourceResolver)} method, or null
 351      *      if that method has never been called since this {@link Validator}
 352      *      has created.
 353      *
 354      * @see #setErrorHandler(ErrorHandler)
 355      */
 356     public abstract LSResourceResolver getResourceResolver();
 357 
 358 
 359 
 360     /**
 361      * Look up the value of a feature flag.
 362      *
 363      * <p>The feature name is any fully-qualified URI.  It is
 364      * possible for a {@link Validator} to recognize a feature name but
 365      * temporarily be unable to return its value.
 366      * Some feature values may be available only in specific
 367      * contexts, such as before, during, or after a validation.
 368      *
 369      * <p>Implementors are free (and encouraged) to invent their own features,
 370      * using names built on their own URIs.
 371      *
 372      * @param name The feature name, which is a non-null fully-qualified URI.
 373      *
 374      * @return The current value of the feature (true or false).
 375      *
 376      * @throws SAXNotRecognizedException If the feature
 377      *   value can't be assigned or retrieved.
 378      * @throws SAXNotSupportedException When the
 379      *   {@link Validator} recognizes the feature name but
 380      *   cannot determine its value at this time.
 381      * @throws NullPointerException
 382      *   When the name parameter is null.
 383      *
 384      * @see #setFeature(String, boolean)
 385      */
 386     public boolean getFeature(String name)
 387         throws SAXNotRecognizedException, SAXNotSupportedException {
 388 
 389         if (name == null) {
 390             throw new NullPointerException("the name parameter is null");
 391         }
 392 
 393         throw new SAXNotRecognizedException(name);
 394     }
 395 
 396     /**
 397      * Set the value of a feature flag.
 398      *
 399      * <p>
 400      * Feature can be used to control the way a {@link Validator}
 401      * parses schemas, although {@link Validator}s are not required
 402      * to recognize any specific feature names.
 403      *
 404      * <p>The feature name is any fully-qualified URI.  It is
 405      * possible for a {@link Validator} to expose a feature value but
 406      * to be unable to change the current value.
 407      * Some feature values may be immutable or mutable only
 408      * in specific contexts, such as before, during, or after
 409      * a validation.
 410      *
 411      * @param name The feature name, which is a non-null fully-qualified URI.
 412      * @param value The requested value of the feature (true or false).
 413      *
 414      * @throws SAXNotRecognizedException If the feature
 415      *   value can't be assigned or retrieved.
 416      * @throws SAXNotSupportedException When the
 417      *   {@link Validator} recognizes the feature name but
 418      *   cannot set the requested value.
 419      * @throws NullPointerException
 420      *   When the name parameter is null.
 421      *
 422      * @see #getFeature(String)
 423      */
 424     public void setFeature(String name, boolean value)
 425         throws SAXNotRecognizedException, SAXNotSupportedException {
 426 
 427         if (name == null) {
 428             throw new NullPointerException("the name parameter is null");
 429         }
 430 
 431         throw new SAXNotRecognizedException(name);
 432     }
 433 
 434     /**
 435      * Set the value of a property.
 436      *
 437      * <p>The property name is any fully-qualified URI.  It is
 438      * possible for a {@link Validator} to recognize a property name but
 439      * to be unable to change the current value.
 440      * Some property values may be immutable or mutable only
 441      * in specific contexts, such as before, during, or after
 442      * a validation.
 443      *
 444      * <p>
 445      * All implementations that implement JAXP 1.5 or newer are required to
 446      * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
 447      * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
 448      * 
 449      * <ul>
 450      *   <li>
 451      *      <p>Access to external DTDs in source or Schema file is restricted to
 452      *      the protocols specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD}
 453      *      property.  If access is denied during validation due to the restriction
 454      *      of this property, {@link org.xml.sax.SAXException} will be thrown by the
 455      *      {@link #validate(Source)} method.
 456      *
 457      *      <p>Access to external reference set by the schemaLocation attribute is
 458      *      restricted to the protocols specified by the
 459      *      {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
 460      *      If access is denied during validation due to the restriction of this property,
 461      *      {@link org.xml.sax.SAXException} will be thrown by the
 462      *      {@link #validate(Source)} method.
 463      *   </li>
 464      * </ul>
 465      *
 466      * @param name The property name, which is a non-null fully-qualified URI.
 467      * @param object The requested value for the property.
 468      *
 469      * @throws SAXNotRecognizedException If the property
 470      *   value can't be assigned or retrieved.
 471      * @throws SAXNotSupportedException When the
 472      *   {@link Validator} recognizes the property name but
 473      *   cannot set the requested value.
 474      * @throws NullPointerException
 475      *   When the name parameter is null.
 476      */
 477     public void setProperty(String name, Object object)
 478         throws SAXNotRecognizedException, SAXNotSupportedException {
 479 
 480         if (name == null) {
 481             throw new NullPointerException("the name parameter is null");
 482         }
 483 
 484         throw new SAXNotRecognizedException(name);
 485     }
 486 
 487     /**
 488      * Look up the value of a property.
 489      *
 490      * <p>The property name is any fully-qualified URI.  It is
 491      * possible for a {@link Validator} to recognize a property name but
 492      * temporarily be unable to return its value.
 493      * Some property values may be available only in specific
 494      * contexts, such as before, during, or after a validation.
 495      *
 496      * <p>{@link Validator}s are not required to recognize any specific
 497      * property names.
 498      *
 499      * <p>Implementors are free (and encouraged) to invent their own properties,
 500      * using names built on their own URIs.
 501      *
 502      * @param name The property name, which is a non-null fully-qualified URI.
 503      *
 504      * @return The current value of the property.
 505      *
 506      * @throws SAXNotRecognizedException If the property
 507      *   value can't be assigned or retrieved.
 508      * @throws SAXNotSupportedException When the
 509      *   XMLReader recognizes the property name but
 510      *   cannot determine its value at this time.
 511      * @throws NullPointerException
 512      *   When the name parameter is null.
 513      *
 514      * @see #setProperty(String, Object)
 515      */
 516     public Object getProperty(String name)
 517         throws SAXNotRecognizedException, SAXNotSupportedException {
 518 
 519         if (name == null) {
 520             throw new NullPointerException("the name parameter is null");
< prev index next >