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