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