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