1 /*
   2  * Copyright (c) 2003, 2017, 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 com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchemaFactory;
  29 import java.io.File;
  30 import java.net.URL;
  31 import javax.xml.transform.Source;
  32 import javax.xml.transform.stream.StreamSource;
  33 import jdk.xml.internal.SecuritySupport;
  34 import org.w3c.dom.ls.LSResourceResolver;
  35 import org.xml.sax.ErrorHandler;
  36 import org.xml.sax.SAXException;
  37 import org.xml.sax.SAXNotRecognizedException;
  38 import org.xml.sax.SAXNotSupportedException;
  39 import org.xml.sax.SAXParseException;
  40 
  41 /**
  42  * Factory that creates {@link Schema} objects. Entry-point to
  43  * the validation API.
  44  *
  45  * <p>
  46  * {@link SchemaFactory} is a schema compiler. It reads external
  47  * representations of schemas and prepares them for validation.
  48  *
  49  * <p>
  50  * The {@link SchemaFactory} class is not thread-safe. In other words,
  51  * it is the application's responsibility to ensure that at most
  52  * one thread is using a {@link SchemaFactory} object at any
  53  * given moment. Implementations are encouraged to mark methods
  54  * as {@code synchronized} to protect themselves from broken clients.
  55  *
  56  * <p>
  57  * {@link SchemaFactory} is not re-entrant. While one of the
  58  * {@code newSchema} methods is being invoked, applications
  59  * may not attempt to recursively invoke the {@code newSchema} method,
  60  * even from the same thread.
  61  *
  62  * <h2><a id="schemaLanguage"></a>Schema Language</h2>
  63  * <p>
  64  * This spec uses a namespace URI to designate a schema language.
  65  * The following table shows the values defined by this specification.
  66  * <p>
  67  * To be compliant with the spec, the implementation
  68  * is only required to support W3C XML Schema 1.0. However,
  69  * if it chooses to support other schema languages listed here,
  70  * it must conform to the relevant behaviors described in this spec.
  71  *
  72  * <p>
  73  * Schema languages not listed here are expected to
  74  * introduce their own URIs to represent themselves.
  75  * The {@link SchemaFactory} class is capable of locating other
  76  * implementations for other schema languages at run-time.
  77  *
  78  * <p>
  79  * Note that because the XML DTD is strongly tied to the parsing process
  80  * and has a significant effect on the parsing process, it is impossible
  81  * to define the DTD validation as a process independent from parsing.
  82  * For this reason, this specification does not define the semantics for
  83  * the XML DTD. This doesn't prohibit implementors from implementing it
  84  * in a way they see fit, but <em>users are warned that any DTD
  85  * validation implemented on this interface necessarily deviate from
  86  * the XML DTD semantics as defined in the XML 1.0</em>.
  87  *
  88  * <table class="striped">
  89  *   <caption>URIs for Supported Schema languages</caption>
  90  *   <thead>
  91  *     <tr>
  92  *       <th scope="col">value</th>
  93  *       <th scope="col">language</th>
  94  *     </tr>
  95  *   </thead>
  96  *   <tbody>
  97  *     <tr>
  98  *       <th scope="row">{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("{@code http://www.w3.org/2001/XMLSchema}")</th>
  99  *       <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td>
 100  *     </tr>
 101  *     <tr>
 102  *       <th scope="row">{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("{@code http://relaxng.org/ns/structure/1.0}")</th>
 103  *       <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td>
 104  *     </tr>
 105  *   </tbody>
 106  * </table>
 107  *
 108  * @author  Kohsuke Kawaguchi
 109  * @author  Neeraj Bajaj
 110  *
 111  * @since 1.5
 112  */
 113 public abstract class SchemaFactory {
 114 
 115     /**
 116      * Constructor for derived classes.
 117      *
 118      * <p>The constructor does nothing.
 119      *
 120      * <p>Derived classes must create {@link SchemaFactory} objects that have
 121      * {@code null} {@link ErrorHandler} and
 122      * {@code null} {@link LSResourceResolver}.
 123      */
 124     protected SchemaFactory() {
 125     }
 126 
 127     /**
 128      * Creates a new instance of the {@code SchemaFactory} builtin
 129      * system-default implementation.
 130      *
 131      * @implSpec The {@code SchemaFactory} builtin
 132      * system-default implementation is only required to support the
 133      * <a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a>,
 134      * but may support additional <a href="#schemaLanguage">schema languages</a>.
 135      *
 136      * @return A new instance of the {@code SchemaFactory} builtin
 137      *         system-default implementation.
 138      *
 139      * @since 9
 140      */
 141     public static SchemaFactory newDefaultInstance() {
 142         return new XMLSchemaFactory();
 143     }
 144 
 145     /**
 146      * Lookup an implementation of the {@code SchemaFactory} that supports the specified
 147      * schema language and return it.
 148      *
 149      * <p>To find a {@code SchemaFactory} object for a given schema language,
 150      * this method looks the following places in the following order
 151      * where "the class loader" refers to the context class loader:
 152      * <ol>
 153      *  <li>
 154      *     <p>
 155      *     If the system property
 156      *     {@code "javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"}
 157      *     is present (where <i>schemaLanguage</i> is the parameter
 158      *     to this method), then its value is read
 159      *     as a class name. The method will try to
 160      *     create a new instance of this class by using the class loader,
 161      *     and returns it if it is successfully created.
 162      *   </li>
 163      *   <li>
 164      *     <p>
 165      *     Use the configuration file "jaxp.properties". The file is in standard
 166      *     {@link java.util.Properties} format and typically located in the
 167      *     conf directory of the Java installation. It contains the fully qualified
 168      *     name of the implementation class with the key being the system property
 169      *     defined above.
 170      *     <p>
 171      *     The jaxp.properties file is read only once by the JAXP implementation
 172      *     and its values are then cached for future use.  If the file does not exist
 173      *     when the first attempt is made to read from it, no further attempts are
 174      *     made to check for its existence.  It is not possible to change the value
 175      *     of any property in jaxp.properties after it has been read for the first time.
 176      *   </li>
 177      *   <li>
 178      *   <p>
 179      *   Use the service-provider loading facility, defined by the
 180      *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
 181      *   implementation of the service using the {@linkplain
 182      *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
 183      *   the service-provider loading facility will use the {@linkplain
 184      *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
 185      *   to attempt to load the service. If the context class
 186      *   loader is null, the {@linkplain
 187      *   ClassLoader#getSystemClassLoader() system class loader} will be used.
 188      *   <br>
 189      *   Each potential service provider is required to implement the method
 190      *        {@link #isSchemaLanguageSupported(String schemaLanguage)}.
 191      *   <br>
 192      *   The first service provider found that supports the specified schema
 193      *   language is returned.
 194      *   <br>
 195      *   In case of {@link java.util.ServiceConfigurationError} a
 196      *   {@link SchemaFactoryConfigurationError} will be thrown.
 197      *   </li>
 198      *   <li>
 199      *     <p>
 200      *     Platform default {@code SchemaFactory} is located
 201      *     in an implementation specific way. There must be a
 202      *     {@linkplain #newDefaultInstance() platform default}
 203      *     {@code SchemaFactory} for W3C XML Schema.
 204      *   </li>
 205      * </ol>
 206      *
 207      * <p>If everything fails, {@link IllegalArgumentException} will be thrown.
 208      *
 209      * <p><strong>Tip for Trouble-shooting:</strong>
 210      * <p>See {@link java.util.Properties#load(java.io.InputStream)} for
 211      * exactly how a property file is parsed. In particular, colons ':'
 212      * need to be escaped in a property file, so make sure schema language
 213      * URIs are properly escaped in it. For example:
 214      * <pre>
 215      * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
 216      * </pre>
 217      *
 218      * @param schemaLanguage
 219      *      Specifies the schema language which the returned
 220      *      SchemaFactory will understand. See
 221      *      <a href="#schemaLanguage">the list of available
 222      *      schema languages</a> for the possible values.
 223      *
 224      * @return New instance of a {@code SchemaFactory}
 225      *
 226      * @throws IllegalArgumentException
 227      *      If no implementation of the schema language is available.
 228      * @throws NullPointerException
 229      *      If the {@code schemaLanguage} parameter is null.
 230      * @throws SchemaFactoryConfigurationError
 231      *      If a configuration error is encountered.
 232      *
 233      * @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
 234      */
 235     public static SchemaFactory newInstance(String schemaLanguage) {
 236         ClassLoader cl;
 237         cl = SecuritySupport.getContextClassLoader();
 238 
 239         if (cl == null) {
 240             //cl = ClassLoader.getSystemClassLoader();
 241             //use the current class loader
 242             cl = SchemaFactory.class.getClassLoader();
 243         }
 244 
 245         SchemaFactory f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage);
 246         if (f == null) {
 247             throw new IllegalArgumentException(
 248                     "No SchemaFactory"
 249                     + " that implements the schema language specified by: " + schemaLanguage
 250                     + " could be loaded");
 251         }
 252         return f;
 253     }
 254 
 255     /**
 256      * Obtain a new instance of a {@code SchemaFactory} from class name. {@code SchemaFactory}
 257      * is returned if specified factory class name supports the specified schema language.
 258      * This function is useful when there are multiple providers in the classpath.
 259      * It gives more control to the application as it can specify which provider
 260      * should be loaded.
 261      *
 262      * <h2>Tip for Trouble-shooting</h2>
 263      * <p>Setting the {@code jaxp.debug} system property will cause
 264      * this method to print a lot of debug messages
 265      * to {@code System.err} about what it is doing and where it is looking at.
 266      *
 267      * <p> If you have problems try:
 268      * <pre>
 269      * java -Djaxp.debug=1 YourProgram ....
 270      * </pre>
 271      *
 272      * @param schemaLanguage Specifies the schema language which the returned
 273      *                          {@code SchemaFactory} will understand. See
 274      *                          <a href="#schemaLanguage">the list of available
 275      *                          schema languages</a> for the possible values.
 276      *
 277      * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.validation.SchemaFactory}.
 278      *
 279      * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null}
 280      *                     current {@code Thread}'s context classLoader is used to load the factory class.
 281      *
 282      * @return New instance of a {@code SchemaFactory}
 283      *
 284      * @throws IllegalArgumentException
 285      *                   if {@code factoryClassName} is {@code null}, or
 286      *                   the factory class cannot be loaded, instantiated or doesn't
 287      *                   support the schema language specified in {@code schemLanguage}
 288      *                   parameter.
 289      *
 290      * @throws NullPointerException
 291      *      If the {@code schemaLanguage} parameter is null.
 292      *
 293      * @see #newInstance(String schemaLanguage)
 294      *
 295      * @since 1.6
 296      */
 297     public static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader){
 298         ClassLoader cl = classLoader;
 299 
 300         if (cl == null) {
 301             cl = SecuritySupport.getContextClassLoader();
 302         }
 303 
 304         SchemaFactory f = new SchemaFactoryFinder(cl).createInstance(factoryClassName);
 305         if (f == null) {
 306             throw new IllegalArgumentException(
 307                     "Factory " + factoryClassName
 308                     + " could not be loaded to implement the schema language specified by: " + schemaLanguage);
 309         }
 310         //if this factory supports the given schemalanguage return this factory else thrown exception
 311         if(f.isSchemaLanguageSupported(schemaLanguage)){
 312             return f;
 313         }else{
 314             throw new IllegalArgumentException(
 315                     "Factory " + f.getClass().getName()
 316                     + " does not implement the schema language specified by: " + schemaLanguage);
 317         }
 318 
 319     }
 320 
 321     /**
 322      * Is specified schema supported by this {@code SchemaFactory}?
 323      *
 324      * @param schemaLanguage Specifies the schema language which the returned {@code SchemaFactory} will understand.
 325      *    {@code schemaLanguage} must specify a <a href="#schemaLanguage">valid</a> schema language.
 326      *
 327      * @return {@code true} if {@code SchemaFactory} supports {@code schemaLanguage}, else {@code false}.
 328      *
 329      * @throws NullPointerException If {@code schemaLanguage} is {@code null}.
 330      * @throws IllegalArgumentException If {@code schemaLanguage.length() == 0}
 331      *   or {@code schemaLanguage} does not specify a <a href="#schemaLanguage">valid</a> schema language.
 332      */
 333     public abstract boolean isSchemaLanguageSupported(String schemaLanguage);
 334 
 335     /**
 336      * Look up the value of a feature flag.
 337      *
 338      * <p>The feature name is any fully-qualified URI.  It is
 339      * possible for a {@link SchemaFactory} to recognize a feature name but
 340      * temporarily be unable to return its value.
 341      *
 342      * <p>Implementors are free (and encouraged) to invent their own features,
 343      * using names built on their own URIs.
 344      *
 345      * @param name The feature name, which is a non-null fully-qualified URI.
 346      *
 347      * @return The current value of the feature (true or false).
 348      *
 349      * @throws SAXNotRecognizedException If the feature
 350      *   value can't be assigned or retrieved.
 351      * @throws SAXNotSupportedException When the
 352      *   {@link SchemaFactory} recognizes the feature name but
 353      *   cannot determine its value at this time.
 354      * @throws NullPointerException If {@code name} is {@code null}.
 355      *
 356      * @see #setFeature(String, boolean)
 357      */
 358     public boolean getFeature(String name)
 359         throws SAXNotRecognizedException, SAXNotSupportedException {
 360 
 361         if (name == null) {
 362                 throw new NullPointerException("the name parameter is null");
 363         }
 364         throw new SAXNotRecognizedException(name);
 365     }
 366 
 367     /**
 368      * Set a feature for this {@code SchemaFactory},
 369      * {@link Schema}s created by this factory, and by extension,
 370      * {@link Validator}s and {@link ValidatorHandler}s created by
 371      * those {@link Schema}s.
 372      *
 373      * <p>Implementors and developers should pay particular attention
 374      * to how the special {@link Schema} object returned by {@link
 375      * #newSchema()} is processed. In some cases, for example, when the
 376      * {@code SchemaFactory} and the class actually loading the
 377      * schema come from different implementations, it may not be possible
 378      * for {@code SchemaFactory} features to be inherited automatically.
 379      * Developers should
 380      * make sure that features, such as secure processing, are explicitly
 381      * set in both places.
 382      *
 383      * <p>The feature name is any fully-qualified URI. It is
 384      * possible for a {@link SchemaFactory} to expose a feature value but
 385      * to be unable to change the current value.
 386      *
 387      * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
 388      * When the feature is:
 389      * <ul>
 390      *   <li>
 391      *     {@code true}: the implementation will limit XML processing to conform to implementation limits.
 392      *     Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
 393      *     If XML processing is limited for security reasons, it will be reported via a call to the registered
 394      *    {@link ErrorHandler#fatalError(SAXParseException exception)}.
 395      *     See {@link #setErrorHandler(ErrorHandler errorHandler)}.
 396      *   </li>
 397      *   <li>
 398      *     {@code false}: the implementation will processing XML according to the XML specifications without
 399      *     regard to possible implementation limits.
 400      *   </li>
 401      * </ul>
 402      *
 403      * @param name The feature name, which is a non-null fully-qualified URI.
 404      * @param value The requested value of the feature (true or false).
 405      *
 406      * @throws SAXNotRecognizedException If the feature
 407      *   value can't be assigned or retrieved.
 408      * @throws SAXNotSupportedException When the
 409      *   {@link SchemaFactory} recognizes the feature name but
 410      *   cannot set the requested value.
 411      * @throws NullPointerException If {@code name} is {@code null}.
 412      *
 413      * @see #getFeature(String)
 414      */
 415     public void setFeature(String name, boolean value)
 416         throws SAXNotRecognizedException, SAXNotSupportedException {
 417 
 418         if (name == null) {
 419                 throw new NullPointerException("the name parameter is null");
 420         }
 421         throw new SAXNotRecognizedException(name);
 422     }
 423 
 424     /**
 425      * Set the value of a property.
 426      *
 427      * <p>The property name is any fully-qualified URI. It is
 428      * possible for a {@link SchemaFactory} to recognize a property name but
 429      * to be unable to change the current value.
 430      *
 431      * <p>
 432      * All implementations that implement JAXP 1.5 or newer are required to
 433      * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and
 434      * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties.
 435      *
 436      * <ul>
 437      *   <li>
 438      *      <p>Access to external DTDs in Schema files is restricted to the protocols
 439      *      specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
 440      *      If access is denied during the creation of new Schema due to the restriction
 441      *      of this property, {@link org.xml.sax.SAXException} will be thrown by the
 442      *      {@link #newSchema(Source)} or {@link #newSchema(File)}
 443      *      or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.
 444      *
 445      *      <p>Access to external DTDs in xml source files is restricted to the protocols
 446      *      specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property.
 447      *      If access is denied during validation due to the restriction
 448      *      of this property, {@link org.xml.sax.SAXException} will be thrown by the
 449      *      {@link javax.xml.validation.Validator#validate(Source)} or
 450      *      {@link javax.xml.validation.Validator#validate(Source, Result)} method.
 451      *
 452      *      <p>Access to external reference set by the schemaLocation attribute is
 453      *      restricted to the protocols specified by the
 454      *      {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
 455      *      If access is denied during validation due to the restriction of this property,
 456      *      {@link org.xml.sax.SAXException} will be thrown by the
 457      *      {@link javax.xml.validation.Validator#validate(Source)} or
 458      *      {@link javax.xml.validation.Validator#validate(Source, Result)} method.
 459      *
 460      *      <p>Access to external reference set by the Import
 461      *      and Include element is restricted to the protocols specified by the
 462      *      {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property.
 463      *      If access is denied during the creation of new Schema due to the restriction
 464      *      of this property, {@link org.xml.sax.SAXException} will be thrown by the
 465      *      {@link #newSchema(Source)} or {@link #newSchema(File)}
 466      *      or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method.
 467      *   </li>
 468      * </ul>
 469      *
 470      * @param name The property name, which is a non-null fully-qualified URI.
 471      * @param object The requested value for the property.
 472      *
 473      * @throws SAXNotRecognizedException If the property
 474      *   value can't be assigned or retrieved.
 475      * @throws SAXNotSupportedException When the
 476      *   {@link SchemaFactory} recognizes the property name but
 477      *   cannot set the requested value.
 478      * @throws NullPointerException If {@code name} is {@code null}.
 479      */
 480     public void setProperty(String name, Object object)
 481         throws SAXNotRecognizedException, SAXNotSupportedException {
 482 
 483         if (name == null) {
 484                 throw new NullPointerException("the name parameter is null");
 485         }
 486         throw new SAXNotRecognizedException(name);
 487     }
 488 
 489     /**
 490      * Look up the value of a property.
 491      *
 492      * <p>The property name is any fully-qualified URI.  It is
 493      * possible for a {@link SchemaFactory} to recognize a property name but
 494      * temporarily be unable to return its value.
 495      *
 496      * <p>{@link SchemaFactory}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 If {@code name} is {@code 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");
 520         }
 521         throw new SAXNotRecognizedException(name);
 522     }
 523 
 524     /**
 525      * Sets the {@link ErrorHandler} to receive errors encountered
 526      * during the {@code newSchema} method invocation.
 527      *
 528      * <p>
 529      * Error handler can be used to customize the error handling process
 530      * during schema parsing. When an {@link ErrorHandler} is set,
 531      * errors found during the parsing of schemas will be first sent
 532      * to the {@link ErrorHandler}.
 533      *
 534      * <p>
 535      * The error handler can abort the parsing of a schema immediately
 536      * by throwing {@link SAXException} from the handler. Or for example
 537      * it can print an error to the screen and try to continue the
 538      * processing by returning normally from the {@link ErrorHandler}
 539      *
 540      * <p>
 541      * If any {@link Throwable} (or instances of its derived classes)
 542      * is thrown from an {@link ErrorHandler},
 543      * the caller of the {@code newSchema} method will be thrown
 544      * the same {@link Throwable} object.
 545      *
 546      * <p>
 547      * {@link SchemaFactory} is not allowed to
 548      * throw {@link SAXException} without first reporting it to
 549      * {@link ErrorHandler}.
 550      *
 551      * <p>
 552      * Applications can call this method even during a {@link Schema}
 553      * is being parsed.
 554      *
 555      * <p>
 556      * When the {@link ErrorHandler} is null, the implementation will
 557      * behave as if the following {@link ErrorHandler} is set:
 558      * <pre>
 559      * class DraconianErrorHandler implements {@link ErrorHandler} {
 560      *     public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 561      *         throw e;
 562      *     }
 563      *     public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 564      *         throw e;
 565      *     }
 566      *     public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
 567      *         // noop
 568      *     }
 569      * }
 570      * </pre>
 571      *
 572      * <p>
 573      * When a new {@link SchemaFactory} object is created, initially
 574      * this field is set to null. This field will <em>NOT</em> be
 575      * inherited to {@link Schema}s, {@link Validator}s, or
 576      * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
 577      *
 578      * @param errorHandler A new error handler to be set.
 579      *   This parameter can be {@code null}.
 580      */
 581     public abstract void setErrorHandler(ErrorHandler errorHandler);
 582 
 583     /**
 584      * Gets the current {@link ErrorHandler} set to this {@link SchemaFactory}.
 585      *
 586      * @return
 587      *      This method returns the object that was last set through
 588      *      the {@link #setErrorHandler(ErrorHandler)} method, or null
 589      *      if that method has never been called since this {@link SchemaFactory}
 590      *      has created.
 591      *
 592      * @see #setErrorHandler(ErrorHandler)
 593      */
 594     public abstract ErrorHandler getErrorHandler();
 595 
 596     /**
 597      * Sets the {@link LSResourceResolver} to customize
 598      * resource resolution when parsing schemas.
 599      *
 600      * <p>
 601      * {@link SchemaFactory} uses a {@link LSResourceResolver}
 602      * when it needs to locate external resources while parsing schemas,
 603      * although exactly what constitutes "locating external resources" is
 604      * up to each schema language. For example, for W3C XML Schema,
 605      * this includes files {@code <include>}d or {@code <import>}ed,
 606      * and DTD referenced from schema files, etc.
 607      *
 608      * <p>
 609      * Applications can call this method even during a {@link Schema}
 610      * is being parsed.
 611      *
 612      * <p>
 613      * When the {@link LSResourceResolver} is null, the implementation will
 614      * behave as if the following {@link LSResourceResolver} is set:
 615      * <pre>
 616      * class DumbDOMResourceResolver implements {@link LSResourceResolver} {
 617      *     public {@link org.w3c.dom.ls.LSInput} resolveResource(
 618      *         String publicId, String systemId, String baseURI) {
 619      *
 620      *         return null; // always return null
 621      *     }
 622      * }
 623      * </pre>
 624      *
 625      * <p>
 626      * If a {@link LSResourceResolver} throws a {@link RuntimeException}
 627      *  (or instances of its derived classes),
 628      * then the {@link SchemaFactory} will abort the parsing and
 629      * the caller of the {@code newSchema} method will receive
 630      * the same {@link RuntimeException}.
 631      *
 632      * <p>
 633      * When a new {@link SchemaFactory} object is created, initially
 634      * this field is set to null.  This field will <em>NOT</em> be
 635      * inherited to {@link Schema}s, {@link Validator}s, or
 636      * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
 637      *
 638      * @param   resourceResolver
 639      *      A new resource resolver to be set. This parameter can be null.
 640      */
 641     public abstract void setResourceResolver(LSResourceResolver resourceResolver);
 642 
 643     /**
 644      * Gets the current {@link LSResourceResolver} set to this {@link SchemaFactory}.
 645      *
 646      * @return
 647      *      This method returns the object that was last set through
 648      *      the {@link #setResourceResolver(LSResourceResolver)} method, or null
 649      *      if that method has never been called since this {@link SchemaFactory}
 650      *      has created.
 651      *
 652      * @see #setErrorHandler(ErrorHandler)
 653      */
 654     public abstract LSResourceResolver getResourceResolver();
 655 
 656     /**
 657      * Parses the specified source as a schema and returns it as a schema.
 658      *
 659      * <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.
 660      *
 661      * @param schema Source that represents a schema.
 662      *
 663      * @return New {@code Schema} from parsing {@code schema}.
 664      *
 665      * @throws SAXException If a SAX error occurs during parsing.
 666      * @throws NullPointerException if {@code schema} is null.
 667      */
 668     public Schema newSchema(Source schema) throws SAXException {
 669         return newSchema(new Source[]{schema});
 670     }
 671 
 672     /**
 673      * Parses the specified {@code File} as a schema and returns it as a {@code Schema}.
 674      *
 675      * <p>This is a convenience method for {@link #newSchema(Source schema)}.
 676      *
 677      * @param schema File that represents a schema.
 678      *
 679      * @return New {@code Schema} from parsing {@code schema}.
 680      *
 681      * @throws SAXException If a SAX error occurs during parsing.
 682      * @throws NullPointerException if {@code schema} is null.
 683      */
 684     public Schema newSchema(File schema) throws SAXException {
 685         return newSchema(new StreamSource(schema));
 686     }
 687 
 688     /**
 689      * Parses the specified {@code URL} as a schema and returns it as a {@code Schema}.
 690      *
 691      * <p>This is a convenience method for {@link #newSchema(Source schema)}.
 692      *
 693      * @param schema {@code URL} that represents a schema.
 694      *
 695      * @return New {@code Schema} from parsing {@code schema}.
 696      *
 697      * @throws SAXException If a SAX error occurs during parsing.
 698      * @throws NullPointerException if {@code schema} is null.
 699      */
 700     public Schema newSchema(URL schema) throws SAXException {
 701         return newSchema(new StreamSource(schema.toExternalForm()));
 702     }
 703 
 704     /**
 705      * Parses the specified source(s) as a schema and returns it as a schema.
 706      *
 707      * <p>
 708      * The callee will read all the {@link Source}s and combine them into a
 709      * single schema. The exact semantics of the combination depends on the schema
 710      * language that this {@link SchemaFactory} object is created for.
 711      *
 712      * <p>
 713      * When an {@link ErrorHandler} is set, the callee will report all the errors
 714      * found in sources to the handler. If the handler throws an exception, it will
 715      * abort the schema compilation and the same exception will be thrown from
 716      * this method. Also, after an error is reported to a handler, the callee is allowed
 717      * to abort the further processing by throwing it. If an error handler is not set,
 718      * the callee will throw the first error it finds in the sources.
 719      *
 720      * <h2>W3C XML Schema 1.0</h2>
 721      * <p>
 722      * The resulting schema contains components from the specified sources.
 723      * The same result would be achieved if all these sources were
 724      * imported, using appropriate values for schemaLocation and namespace,
 725      * into a single schema document with a different targetNamespace
 726      * and no components of its own, if the import elements were given
 727      * in the same order as the sources.  Section 4.2.3 of the XML Schema
 728      * recommendation describes the options processors have in this
 729      * regard.  While a processor should be consistent in its treatment of
 730      * JAXP schema sources and XML Schema imports, the behaviour between
 731      * JAXP-compliant parsers may vary; in particular, parsers may choose
 732      * to ignore all but the first {@code <import>} for a given namespace,
 733      * regardless of information provided in schemaLocation.
 734      *
 735      * <p>
 736      * If the parsed set of schemas includes error(s) as
 737      * specified in the section 5.1 of the XML Schema spec, then
 738      * the error must be reported to the {@link ErrorHandler}.
 739      *
 740      * <h2>RELAX NG</h2>
 741      *
 742      * <p>For RELAX NG, this method must throw {@link UnsupportedOperationException}
 743      * if {@code schemas.length!=1}.
 744      *
 745      *
 746      * @param schemas
 747      *      inputs to be parsed. {@link SchemaFactory} is required
 748      *      to recognize {@link javax.xml.transform.sax.SAXSource},
 749      *      {@link StreamSource},
 750      *      {@link javax.xml.transform.stax.StAXSource},
 751      *      and {@link javax.xml.transform.dom.DOMSource}.
 752      *      Input schemas must be XML documents or
 753      *      XML elements and must not be null. For backwards compatibility,
 754      *      the results of passing anything other than
 755      *      a document or element are implementation-dependent.
 756      *      Implementations must either recognize and process the input
 757      *      or thrown an IllegalArgumentException.
 758      *
 759      * @return
 760      *      Always return a non-null valid {@link Schema} object.
 761      *      Note that when an error has been reported, there is no
 762      *      guarantee that the returned {@link Schema} object is
 763      *      meaningful.
 764      *
 765      * @throws SAXException
 766      *      If an error is found during processing the specified inputs.
 767      *      When an {@link ErrorHandler} is set, errors are reported to
 768      *      there first. See {@link #setErrorHandler(ErrorHandler)}.
 769      * @throws NullPointerException
 770      *      If the {@code schemas} parameter itself is null or
 771      *      any item in the array is null.
 772      * @throws IllegalArgumentException
 773      *      If any item in the array is not recognized by this method.
 774      * @throws UnsupportedOperationException
 775      *      If the schema language doesn't support this operation.
 776      */
 777     public abstract Schema newSchema(Source[] schemas) throws SAXException;
 778 
 779     /**
 780      * Creates a special {@link Schema} object.
 781      *
 782      * <p>The exact semantics of the returned {@link Schema} object
 783      * depend on the schema language for which this {@link SchemaFactory}
 784      * is created.
 785      *
 786      * <p>Also, implementations are allowed to use implementation-specific
 787      * property/feature to alter the semantics of this method.
 788      *
 789      * <p>Implementors and developers should pay particular attention
 790      * to how the features set on this {@link SchemaFactory} are
 791      * processed by this special {@link Schema}.
 792      * In some cases, for example, when the
 793      * {@link SchemaFactory} and the class actually loading the
 794      * schema come from different implementations, it may not be possible
 795      * for {@link SchemaFactory} features to be inherited automatically.
 796      * Developers should
 797      * make sure that features, such as secure processing, are explicitly
 798      * set in both places.
 799      *
 800      * <h2>W3C XML Schema 1.0</h2>
 801      * <p>
 802      * For XML Schema, this method creates a {@link Schema} object that
 803      * performs validation by using location hints specified in documents.
 804      *
 805      * <p>
 806      * The returned {@link Schema} object assumes that if documents
 807      * refer to the same URL in the schema location hints,
 808      * they will always resolve to the same schema document. This
 809      * asusmption allows implementations to reuse parsed results of
 810      * schema documents so that multiple validations against the same
 811      * schema will run faster.
 812      *
 813      * <p>
 814      * Note that the use of schema location hints introduces a
 815      * vulnerability to denial-of-service attacks.
 816      *
 817      *
 818      * <h2>RELAX NG</h2>
 819      * <p>
 820      * RELAX NG does not support this operation.
 821      *
 822      * @return
 823      *      Always return non-null valid {@link Schema} object.
 824      *
 825      * @throws UnsupportedOperationException
 826      *      If this operation is not supported by the callee.
 827      * @throws SAXException
 828      *      If this operation is supported but failed for some reason.
 829      */
 830     public abstract Schema newSchema() throws SAXException;
 831 }