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