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