KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > validation > SchemaFactory


1
2 // $Id: SchemaFactory.java,v 1.20.10.1.2.3 2004/09/16 09:24:47 nb131165 Exp $
3
/*
4  * @(#)SchemaFactory.java 1.13 05/01/04
5  *
6  * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
7  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
8  */

9
10 package javax.xml.validation;
11
12 import java.io.File JavaDoc;
13 import java.net.URL JavaDoc;
14
15 import javax.xml.transform.Source JavaDoc;
16 import javax.xml.transform.stream.StreamSource JavaDoc;
17
18 import org.w3c.dom.ls.LSResourceResolver JavaDoc;
19 import org.xml.sax.ErrorHandler JavaDoc;
20 import org.xml.sax.SAXException JavaDoc;
21 import org.xml.sax.SAXNotRecognizedException JavaDoc;
22 import org.xml.sax.SAXNotSupportedException JavaDoc;
23
24 /**
25  * Factory that creates {@link Schema} objects. Entry-point to
26  * the validation API.
27  *
28  * <p>
29  * {@link SchemaFactory} is a schema compiler. It reads external
30  * representations of schemas and prepares them for validation.
31  *
32  * <p>
33  * The {@link SchemaFactory} class is not thread-safe. In other words,
34  * it is the application's responsibility to ensure that at most
35  * one thread is using a {@link SchemaFactory} object at any
36  * given moment. Implementations are encouraged to mark methods
37  * as <tt>synchronized</tt> to protect themselves from broken clients.
38  *
39  * <p>
40  * {@link SchemaFactory} is not re-entrant. While one of the
41  * <code>newSchema</code> methods is being invoked, applications
42  * may not attempt to recursively invoke the <code>newSchema</code> method,
43  * even from the same thread.
44  *
45  * <h2><a name="schemaLanguage"></a>Schema Language</h2>
46  * <p>
47  * This spec uses a namespace URI to designate a schema language.
48  * The following table shows the values defined by this specification.
49  * <p>
50  * To be compliant with the spec, the implementation
51  * is only required to support W3C XML Schema 1.0. However,
52  * if it chooses to support other schema languages listed here,
53  * it must conform to the relevant behaviors described in this spec.
54  *
55  * <p>
56  * Schema languages not listed here are expected to
57  * introduce their own URIs to represent themselves.
58  * The {@link SchemaFactory} class is capable of locating other
59  * implementations for other schema languages at run-time.
60  *
61  * <p>
62  * Note that because the XML DTD is strongly tied to the parsing process
63  * and has a significant effect on the parsing process, it is impossible
64  * to define the DTD validation as a process independent from parsing.
65  * For this reason, this specification does not define the semantics for
66  * the XML DTD. This doesn't prohibit implentors from implementing it
67  * in a way they see fit, but <em>users are warned that any DTD
68  * validation implemented on this interface necessarily deviate from
69  * the XML DTD semantics as defined in the XML 1.0</em>.
70  *
71  * <table border="1" cellpadding="2">
72  * <thead>
73  * <tr>
74  * <th>value</th>
75  * <th>language</th>
76  * </tr>
77  * </thead>
78  * <tbody>
79  * <tr>
80  * <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("<code>http://www.w3.org/2001/XMLSchema</code>")</td>
81  * <td><a HREF="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td>
82  * </tr>
83  * <tr>
84  * <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("<code>http://relaxng.org/ns/structure/1.0</code>")</td>
85  * <td><a HREF="http://www.relaxng.org/">RELAX NG 1.0</a></td>
86  * </tr>
87  * </tbody>
88  * </table>
89  *
90  * @author <a HREF="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
91  * @version $Revision: 1.20.10.1.2.3 $, $Date: 2004/09/16 09:24:47 $
92  * @since 1.5
93  */

94 public abstract class SchemaFactory {
95
96      private static SecuritySupport JavaDoc ss = new SecuritySupport JavaDoc();
97      
98     /**
99      * <p>Constructor for derived classes.</p>
100      *
101      * <p>The constructor does nothing.</p>
102      *
103      * <p>Derived classes must create {@link SchemaFactory} objects that have
104      * <code>null</code> {@link ErrorHandler} and
105      * <code>null</code> {@link LSResourceResolver}.</p>
106      */

107     protected SchemaFactory() {
108     }
109  
110     /**
111      * <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified
112      * schema language and return it.</p>
113      *
114      * <p>To find a <code>SchemaFactory</code> object for a given schema language,
115      * this method looks the following places in the following order
116      * where "the class loader" refers to the context class loader:</p>
117      * <ol>
118      * <li>
119      * If the system property
120      * <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code>
121      * is present (where <i>schemaLanguage</i> is the parameter
122      * to this method), then its value is read
123      * as a class name. The method will try to
124      * create a new instance of this class by using the class loader,
125      * and returns it if it is successfully created.
126      * </li>
127      * <li>
128      * <code>$java.home/lib/jaxp.properties</code> is read and
129      * the value associated with the key being the system property above
130      * is looked for. If present, the value is processed just like above.
131      * </li>
132      * <li>
133      * <p>The class loader is asked for service provider provider-configuration files matching
134      * <code>javax.xml.validation.SchemaFactory</code> in the resource directory META-INF/services.
135      * See the JAR File Specification for file format and parsing rules.
136      * Each potential service provider is required to implement the method:</p>
137      * <pre>
138      * {@link #isSchemaLanguageSupported(String schemaLanguage)}
139      * </pre>
140      * The first service provider found in class loader order that supports the specified schema language is returned.
141      * </li>
142      * <li>
143      * Platform default <code>SchemaFactory</code> is located
144      * in a implementation specific way. There must be a platform default
145      * <code>SchemaFactory</code> for W3C XML Schema.
146      * </li>
147      * </ol>
148      *
149      * <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p>
150      *
151      * <p><strong>Tip for Trouble-shooting:</strong></p>
152      * <p>See {@link java.util.Properties#load(java.io.InputStream)} for
153      * exactly how a property file is parsed. In particular, colons ':'
154      * need to be escaped in a property file, so make sure schema language
155      * URIs are properly escaped in it. For example:</p>
156      * <pre>
157      * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
158      * </pre>
159      *
160      * @param schemaLanguage
161      * Specifies the schema language which the returned
162      * SchemaFactory will understand. See
163      * <a HREF="#schemaLanguage">the list of available
164      * schema languages</a> for the possible values.
165      *
166      * @return New instance of a <code>SchemaFactory</code>
167      *
168      * @throws IllegalArgumentException
169      * If no implementation of the schema language is available.
170      *
171      * @throws NullPointerException
172      * If the <tt>schemLanguage</tt> parameter is null.
173      */

174     public static final SchemaFactory JavaDoc newInstance(String JavaDoc schemaLanguage) {
175         ClassLoader JavaDoc cl;
176         cl = ss.getContextClassLoader();
177         
178         if (cl == null) {
179             //cl = ClassLoader.getSystemClassLoader();
180
//use the current class loader
181
cl = SchemaFactory JavaDoc.class.getClassLoader();
182         }
183
184         SchemaFactory JavaDoc f = new SchemaFactoryFinder JavaDoc(cl).newFactory(schemaLanguage);
185         if (f == null) {
186             throw new IllegalArgumentException JavaDoc(schemaLanguage);
187         }
188         return f;
189     }
190     
191     /**
192      * <p>Is specified schema supported by this <code>SchemaFactory</code>?</p>
193      *
194      * @param schemaLanguage Specifies the schema language which the returned <code>SchemaFactory</code> will understand.
195      * <code>schemaLanguage</code> must specify a <a HREF="#schemaLanguage">valid</a> schema language.
196      *
197      * @return <code>true</code> if <code>SchemaFactory</code> supports <code>schemaLanguage</code>, else <code>false</code>.
198      *
199      * @throws NullPointerException If <code>schemaLanguage</code> is <code>null</code>.
200      * @throws IllegalArgumentException If <code>schemaLanguage.length() == 0</code>
201      * or <code>schemaLanguage</code> does not specify a <a HREF="#schemaLanguage">valid</a> schema language.
202      */

203     public abstract boolean isSchemaLanguageSupported(String JavaDoc schemaLanguage);
204
205     /**
206      * Look up the value of a feature flag.
207      *
208      * <p>The feature name is any fully-qualified URI. It is
209      * possible for a {@link SchemaFactory} to recognize a feature name but
210      * temporarily be unable to return its value.
211      *
212      * <p>Implementors are free (and encouraged) to invent their own features,
213      * using names built on their own URIs.</p>
214      *
215      * @param name The feature name, which is a non-null fully-qualified URI.
216      * @return The current value of the feature (true or false).
217      * @exception org.xml.sax.SAXNotRecognizedException If the feature
218      * value can't be assigned or retrieved.
219      * @exception org.xml.sax.SAXNotSupportedException When the
220      * {@link SchemaFactory} recognizes the feature name but
221      * cannot determine its value at this time.
222      * @exception NullPointerException
223      * if the name parameter is null.
224      * @see #setFeature(String, boolean)
225      */

226     public boolean getFeature(String JavaDoc name) throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc {
227         
228         if (name == null) {
229             throw new NullPointerException JavaDoc("the name parameter is null");
230         }
231         throw new SAXNotRecognizedException JavaDoc(name);
232     }
233     
234     /**
235      * Set the value of a feature flag.
236      *
237      * <p>
238      * Feature can be used to control the way a {@link SchemaFactory}
239      * parses schemas, although {@link SchemaFactory}s are not required
240      * to recognize any specific feature names.</p>
241      *
242      * <p>The feature name is any fully-qualified URI. It is
243      * possible for a {@link SchemaFactory} to expose a feature value but
244      * to be unable to change the current value.</p>
245      *
246      * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
247      * When the feature is:</p>
248      * <ul>
249      * <li>
250      * <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
251      * Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources.
252      * If XML processing is limited for security reasons, it will be reported via a call to the registered
253      * {@link ErrorHandler#fatalError(SAXParseException exception)}.
254      * See {@link #setErrorHandler(ErrorHandler errorHandler)}.
255      * </li>
256      * <li>
257      * <code>false</code>: the implementation will processing XML according to the XML specifications without
258      * regard to possible implementation limits.
259      * </li>
260      * </ul>
261      *
262      * @param name The feature name, which is a non-null fully-qualified URI.
263      * @param value The requested value of the feature (true or false).
264      *
265      * @exception org.xml.sax.SAXNotRecognizedException If the feature
266      * value can't be assigned or retrieved.
267      * @exception org.xml.sax.SAXNotSupportedException When the
268      * {@link SchemaFactory} recognizes the feature name but
269      * cannot set the requested value.
270      * @exception NullPointerException
271      * if the name parameter is null.
272      *
273      * @see #getFeature(String)
274      */

275     public void setFeature(String JavaDoc name, boolean value) throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc {
276         
277         if (name == null) {
278             throw new NullPointerException JavaDoc("the name parameter is null");
279         }
280         throw new SAXNotRecognizedException JavaDoc(name);
281     }
282     
283     /**
284      * Set the value of a property.
285      *
286      * <p>The property name is any fully-qualified URI. It is
287      * possible for a {@link SchemaFactory} to recognize a property name but
288      * to be unable to change the current value.</p>
289      *
290      * <p>{@link SchemaFactory}s are not required to recognize setting
291      * any specific property names.</p>
292      *
293      * @param name The property name, which is a non-null fully-qualified URI.
294      * @param object The requested value for the property.
295      * @exception org.xml.sax.SAXNotRecognizedException If the property
296      * value can't be assigned or retrieved.
297      * @exception org.xml.sax.SAXNotSupportedException When the
298      * {@link SchemaFactory} recognizes the property name but
299      * cannot set the requested value.
300      * @exception NullPointerException
301      * if the name parameter is null.
302      */

303     public void setProperty(String JavaDoc name, Object JavaDoc object) throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc {
304         
305         if (name == null) {
306             throw new NullPointerException JavaDoc("the name parameter is null");
307         }
308         throw new SAXNotRecognizedException JavaDoc(name);
309     }
310     
311     /**
312      * Look up the value of a property.
313      *
314      * <p>The property name is any fully-qualified URI. It is
315      * possible for a {@link SchemaFactory} to recognize a property name but
316      * temporarily be unable to return its value.</p>
317      *
318      * <p>{@link SchemaFactory}s are not required to recognize any specific
319      * property names.</p>
320      *
321      * <p>Implementors are free (and encouraged) to invent their own properties,
322      * using names built on their own URIs.</p>
323      *
324      * @param name The property name, which is a non-null fully-qualified URI.
325      * @return The current value of the property.
326      * @exception org.xml.sax.SAXNotRecognizedException If the property
327      * value can't be assigned or retrieved.
328      * @exception org.xml.sax.SAXNotSupportedException When the
329      * XMLReader recognizes the property name but
330      * cannot determine its value at this time.
331      * @exception NullPointerException
332      * if the name parameter is null.
333      * @see #setProperty(String, Object)
334      */

335     public Object JavaDoc getProperty(String JavaDoc name) throws SAXNotRecognizedException JavaDoc, SAXNotSupportedException JavaDoc {
336         
337         if (name == null) {
338             throw new NullPointerException JavaDoc("the name parameter is null");
339         }
340         throw new SAXNotRecognizedException JavaDoc(name);
341     }
342     
343     /**
344      * Sets the {@link ErrorHandler} to receive errors encountered
345      * during the <code>newSchema</code> method invocation.
346      *
347      * <p>
348      * Error handler can be used to customize the error handling process
349      * during schema parsing. When an {@link ErrorHandler} is set,
350      * errors found during the parsing of schemas will be first sent
351      * to the {@link ErrorHandler}.
352      *
353      * <p>
354      * The error handler can abort the parsing of a schema immediately
355      * by throwing {@link SAXException} from the handler. Or for example
356      * it can print an error to the screen and try to continue the
357      * processing by returning normally from the {@link ErrorHandler}
358      *
359      * <p>
360      * If any {@link Throwable} (or instances of its derived classes)
361      * is thrown from an {@link ErrorHandler},
362      * the caller of the <code>newSchema</code> method will be thrown
363      * the same {@link Throwable} object.
364      *
365      * <p>
366      * {@link SchemaFactory} is not allowed to
367      * throw {@link SAXException} without first reporting it to
368      * {@link ErrorHandler}.
369      *
370      * <p>
371      * Applications can call this method even during a {@link Schema}
372      * is being parsed.
373      *
374      * <p>
375      * When the {@link ErrorHandler} is null, the implementation will
376      * behave as if the following {@link ErrorHandler} is set:
377      * <pre>
378      * class DraconianErrorHandler implements {@link ErrorHandler} {
379      * public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
380      * throw e;
381      * }
382      * public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
383      * throw e;
384      * }
385      * public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
386      * // noop
387      * }
388      * }
389      * </pre>
390      *
391      * <p>
392      * When a new {@link SchemaFactory} object is created, initially
393      * this field is set to null. This field will <em>NOT</em> be
394      * inherited to {@link Schema}s, {@link Validator}s, or
395      * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
396      *
397      *
398      * @param errorHandler
399      * A new error handler to be set. This parameter can be null.
400      */

401     public abstract void setErrorHandler(ErrorHandler JavaDoc errorHandler);
402     
403     /**
404      * Gets the current {@link ErrorHandler} set to this {@link SchemaFactory}.
405      *
406      * @return
407      * This method returns the object that was last set through
408      * the {@link #setErrorHandler(ErrorHandler)} method, or null
409      * if that method has never been called since this {@link SchemaFactory}
410      * has created.
411      *
412      * @see #setErrorHandler(ErrorHandler)
413      */

414     public abstract ErrorHandler JavaDoc getErrorHandler();
415     
416     /**
417      * Sets the {@link LSResourceResolver} to customize
418      * resource resolution when parsing schemas.
419      *
420      * <p>
421      * {@link SchemaFactory} uses a {@link LSResourceResolver}
422      * when it needs to locate external resources while parsing schemas,
423      * although exactly what constitutes "locating external resources" is
424      * up to each schema language. For example, for W3C XML Schema,
425      * this includes files <tt>&lt;include></tt>d or <tt>&lt;import></tt>ed,
426      * and DTD referenced from schema files, etc.
427      *
428      * <p>
429      * Applications can call this method even during a {@link Schema}
430      * is being parsed.
431      *
432      * <p>
433      * When the {@link LSResourceResolver} is null, the implementation will
434      * behave as if the following {@link LSResourceResolver} is set:
435      * <pre>
436      * class DumbDOMResourceResolver implements {@link LSResourceResolver} {
437      * public {@link org.w3c.dom.ls.LSInput} resolveResource(
438      * String publicId, String systemId, String baseURI) {
439      *
440      * return null; // always return null
441      * }
442      * }
443      * </pre>
444      *
445      * <p>
446      * If a {@link LSResourceResolver} throws a {@link RuntimeException}
447      * (or instances of its derived classes),
448      * then the {@link SchemaFactory} will abort the parsing and
449      * the caller of the <code>newSchema</code> method will receive
450      * the same {@link RuntimeException}.
451      *
452      * <p>
453      * When a new {@link SchemaFactory} object is created, initially
454      * this field is set to null. This field will <em>NOT</em> be
455      * inherited to {@link Schema}s, {@link Validator}s, or
456      * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
457      *
458      * @param resourceResolver
459      * A new resource resolver to be set. This parameter can be null.
460      */

461     public abstract void setResourceResolver(LSResourceResolver JavaDoc resourceResolver);
462     
463     /**
464      * Gets the current {@link LSResourceResolver} set to this {@link SchemaFactory}.
465      *
466      * @return
467      * This method returns the object that was last set through
468      * the {@link #setResourceResolver(LSResourceResolver)} method, or null
469      * if that method has never been called since this {@link SchemaFactory}
470      * has created.
471      *
472      * @see #setErrorHandler(ErrorHandler)
473      */

474     public abstract LSResourceResolver JavaDoc getResourceResolver();
475     
476     /**
477      * <p>Parses the specified source as a schema and returns it as a schema.</p>
478      *
479      * <p>This is a convenience method for {@link #newSchema(Source[] schemas)}.</p>
480      *
481      * @param schema Source that represents a schema.
482      *
483      * @return New <code>Schema</code> from parsing <code>schema</code>.
484      *
485      * @throws SAXException If a SAX error occurs during parsing.
486      * @throws NullPointerException if <tt>schema</tt> is null.
487      */

488     public Schema JavaDoc newSchema(Source JavaDoc schema) throws SAXException JavaDoc {
489         return newSchema(new Source JavaDoc[]{schema});
490     }
491     
492     /**
493      * <p>Parses the specified <code>File</code> as a schema and returns it as a <code>Schema</code>.</p>
494      *
495      * <p>This is a convenience method for {@link #newSchema(Source schema)}.</p>
496      *
497      * @param schema File that represents a schema.
498      *
499      * @return New <code>Schema</code> from parsing <code>schema</code>.
500      *
501      * @throws SAXException If a SAX error occurs during parsing.
502      * @throws NullPointerException if <tt>schema</tt> is null.
503      */

504     public Schema JavaDoc newSchema(File JavaDoc schema) throws SAXException JavaDoc {
505         return newSchema(new StreamSource JavaDoc(schema));
506     }
507     
508     /**
509      * <p>Parses the specified <code>URL</code> as a schema and returns it as a <code>Schema</code>.</p>
510      *
511      * <p>This is a convenience method for {@link #newSchema(Source schema)}.</p>
512      *
513      * @param schema <code>URL</code> that represents a schema.
514      *
515      * @return New <code>Schema</code> from parsing <code>schema</code>.
516      *
517      * @throws SAXException If a SAX error occurs during parsing.
518      * @throws NullPointerException if <tt>schema</tt> is null.
519      */

520     public Schema JavaDoc newSchema(URL JavaDoc schema) throws SAXException JavaDoc {
521         return newSchema(new StreamSource JavaDoc(schema.toExternalForm()));
522     }
523     
524     /**
525      * Parses the specified source(s) as a schema and returns it as a schema.
526      *
527      * <p>
528      * The callee will read all the {@link Source}s and combine them into a
529      * single schema. The exact semantics of the combination depends on the schema
530      * language that this {@link SchemaFactory} object is created for.
531      *
532      * <p>
533      * When an {@link ErrorHandler} is set, the callee will report all the errors
534      * found in sources to the handler. If the handler throws an exception, it will
535      * abort the schema compilation and the same exception will be thrown from
536      * this method. Also, after an error is reported to a handler, the callee is allowed
537      * to abort the further processing by throwing it. If an error handler is not set,
538      * the callee will throw the first error it finds in the sources.
539      *
540      * <h2>W3C XML Schema 1.0</h2>
541      * <p>
542      * The resulting schema contains components from the specified sources.
543      * The same result would be achieved if all these sources were
544      * imported, using appropriate values for schemaLocation and namespace,
545      * into a single schema document with a different targetNamespace
546      * and no components of its own, if the import elements were given
547      * in the same order as the sources. Section 4.2.3 of the XML Schema
548      * recommendation describes the options processors have in this
549      * regard. While a processor should be consistent in its treatment of
550      * JAXP schema sources and XML Schema imports, the behaviour between
551      * JAXP-compliant parsers may vary; in particular, parsers may choose
552      * to ignore all but the first &lt;import> for a given namespace,
553      * regardless of information provided in schemaLocation.
554      *
555      * <p>
556      * If the parsed set of schemas includes error(s) as
557      * specified in the section 5.1 of the XML Schema spec, then
558      * the error must be reported to the {@link ErrorHandler}.
559      *
560      * <h2>RELAX NG</h2>
561      *
562      * <p>For RELAX NG, this method must throw {@link UnsupportedOperationException}
563      * if <tt>schemas.length!=1</tt>.
564      *
565      *
566      * @param schemas
567      * inputs to be parsed. {@link SchemaFactory} is required
568      * to recognize {@link javax.xml.transform.sax.SAXSource},
569      * {@link StreamSource}, and {@link javax.xml.transform.dom.DOMSource}.
570      *
571      * @return
572      * Always return a non-null valid {@link Schema} object.
573      * Note that when an error has been reported, there is no
574      * guarantee that the returned {@link Schema} object is
575      * meaningful.
576      *
577      * @throws SAXException
578      * If an error is found during processing the specified inputs.
579      * When an {@link ErrorHandler} is set, errors are reported to
580      * there first. See {@link #setErrorHandler(ErrorHandler)}.
581      * @throws NullPointerException
582      * If the <code>schemas</code> parameter itself is null or
583      * any item in the array is null.
584      * @throws IllegalArgumentException
585      * If any item in the array is not recognized by this method.
586      * @throws UnsupportedOperationException
587      * If the schema language doesn't support this operation.
588      */

589     public abstract Schema JavaDoc newSchema(Source JavaDoc[] schemas) throws SAXException JavaDoc;
590     
591     /**
592      * Creates a special {@link Schema} object.
593      *
594      * <p>
595      * The exact semantics of the returned {@link Schema} object depends
596      * on the schema language that this {@link SchemaFactory} is created
597      * for.
598      *
599      * <p>
600      * Also, implementations are allowed to use implementation-specific
601      * property/feature to alter the semantics of this method.
602      *
603      *
604      * <h2>W3C XML Schema 1.0</h2>
605      * <p>
606      * For XML Schema, this method creates a {@link Schema} object that
607      * performs validation by using location hints specified in documents.
608      *
609      * <p>
610      * The returned {@link Schema} object assumes that if documents
611      * refer to the same URL in the schema location hints,
612      * they will always resolve to the same schema document. This
613      * asusmption allows implementations to reuse parsed results of
614      * schema documents so that multiple validations against the same
615      * schema will run faster.
616      *
617      * <p>
618      * Note that the use of schema location hints introduces a
619      * vulnerability to denial-of-service attacks.
620      *
621      *
622      * <h2>RELAX NG</h2>
623      * <p>
624      * RELAX NG does not support this operation.
625      *
626      * @return
627      * Always return non-null valid {@link Schema} object.
628      *
629      * @throws UnsupportedOperationException
630      * If this operation is not supported by the callee.
631      * @throws SAXException
632      * If this operation is supported but failed for some reason.
633      */

634     public abstract Schema JavaDoc newSchema() throws SAXException JavaDoc;
635 }
636
Popular Tags