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 }