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