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