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