+ * {@link SchemaFactory} is a schema compiler. It reads external + * representations of schemas and prepares them for validation. + * + *
+ * The {@link SchemaFactory} class is not thread-safe. In other words,
+ * it is the application's responsibility to ensure that at most
+ * one thread is using a {@link SchemaFactory} object at any
+ * given moment. Implementations are encouraged to mark methods
+ * as synchronized to protect themselves from broken clients.
+ *
+ *
+ * {@link SchemaFactory} is not re-entrant. While one of the
+ * newSchema methods is being invoked, applications
+ * may not attempt to recursively invoke the newSchema method,
+ * even from the same thread.
+ *
+ *
+ * This spec uses a namespace URI to designate a schema language. + * The following table shows the values defined by this specification. + *
+ * To be compliant with the spec, the implementation + * is only required to support W3C XML Schema 1.0. However, + * if it chooses to support other schema languages listed here, + * it must conform to the relevant behaviors described in this spec. + * + *
+ * Schema languages not listed here are expected to + * introduce their own URIs to represent themselves. + * The {@link SchemaFactory} class is capable of locating other + * implementations for other schema languages at run-time. + * + *
+ * Note that because the XML DTD is strongly tied to the parsing process + * and has a significant effect on the parsing process, it is impossible + * to define the DTD validation as a process independent from parsing. + * For this reason, this specification does not define the semantics for + * the XML DTD. This doesn't prohibit implentors from implementing it + * in a way they see fit, but users are warned that any DTD + * validation implemented on this interface necessarily deviate from + * the XML DTD semantics as defined in the XML 1.0. + * + *
| value | + *language | + *
|---|---|
{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("http://www.w3.org/2001/XMLSchema") |
+ * W3C XML Schema 1.0 | + *
{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("http://relaxng.org/ns/structure/1.0") |
+ * RELAX NG 1.0 | + *
Constructor for derived classes.
+ * + *The constructor does nothing.
+ * + *Derived classes must create {@link SchemaFactory} objects that have
+ * null {@link ErrorHandler} and
+ * null {@link LSResourceResolver}.
Lookup an implementation of the SchemaFactory that supports the specified
+ * schema language and return it.
To find a SchemaFactory object for a given schema language,
+ * this method looks the following places in the following order
+ * where "the class loader" refers to the context class loader:
"javax.xml.validation.SchemaFactory:schemaLanguage"
+ * is present (where schemaLanguage is the parameter
+ * to this method), then its value is read
+ * as a class name. The method will try to
+ * create a new instance of this class by using the class loader,
+ * and returns it if it is successfully created.
+ * $java.home/lib/jaxp.properties is read and
+ * the value associated with the key being the system property above
+ * is looked for. If present, the value is processed just like above.
+ * The class loader is asked for service provider provider-configuration files matching
+ * javax.xml.validation.SchemaFactory in the resource directory META-INF/services.
+ * See the JAR File Specification for file format and parsing rules.
+ * Each potential service provider is required to implement the method:
+ * {@link #isSchemaLanguageSupported(String schemaLanguage)}
+ *
+ * The first service provider found in class loader order that supports the specified schema language is returned.
+ * SchemaFactory is located
+ * in a implementation specific way. There must be a platform default
+ * SchemaFactory for W3C XML Schema.
+ * If everything fails, {@link IllegalArgumentException} will be thrown.
+ * + *Tip for Trouble-shooting:
+ *See {@link java.util.Properties#load(java.io.InputStream)} for + * exactly how a property file is parsed. In particular, colons ':' + * need to be escaped in a property file, so make sure schema language + * URIs are properly escaped in it. For example:
+ *+ * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory + *+ * + * @param schemaLanguage + * Specifies the schema language which the returned + * SchemaFactory will understand. See + * the list of available + * schema languages for the possible values. + * + * @return New instance of a
SchemaFactory
+ *
+ * @throws IllegalArgumentException
+ * If no implementation of the schema language is available.
+ * @throws NullPointerException
+ * If the schemaLanguage parameter is null.
+ *
+ * @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
+ */
+ public static final SchemaFactory newInstance(String schemaLanguage) {
+ ClassLoader cl;
+ cl = ss.getContextClassLoader();
+
+ if (cl == null) {
+ //cl = ClassLoader.getSystemClassLoader();
+ //use the current class loader
+ cl = SchemaFactory.class.getClassLoader();
+ }
+
+ SchemaFactory f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage);
+ if (f == null) {
+ throw new IllegalArgumentException(
+ "No SchemaFactory"
+ + " that implements the schema language specified by: " + schemaLanguage
+ + " could be loaded");
+ }
+ return f;
+ }
+
+ /**
+ * Obtain a new instance of a SchemaFactory from class name. SchemaFactory
+ * is returned if specified factory class name supports the specified schema language.
+ * This function is useful when there are multiple providers in the classpath.
+ * It gives more control to the application as it can specify which provider
+ * should be loaded.
Setting the jaxp.debug system property will cause
+ * this method to print a lot of debug messages
+ * to System.err about what it is doing and where it is looking at.
If you have problems try:
+ *+ * java -Djaxp.debug=1 YourProgram .... + *+ * + * @param schemaLanguage Specifies the schema language which the returned + *
SchemaFactory will understand. See
+ * the list of available
+ * schema languages for the possible values.
+ *
+ * @param factoryClassName fully qualified factory class name that provides implementation of javax.xml.validation.SchemaFactory.
+ *
+ * @param classLoader ClassLoader used to load the factory class. If null
+ * current Thread's context classLoader is used to load the factory class.
+ *
+ * @return New instance of a SchemaFactory
+ *
+ * @throws IllegalArgumentException
+ * if factoryClassName is null, or
+ * the factory class cannot be loaded, instantiated or doesn't
+ * support the schema language specified in schemLanguage
+ * parameter.
+ *
+ * @throws NullPointerException
+ * If the schemaLanguage parameter is null.
+ *
+ * @see #newInstance(String schemaLanguage)
+ *
+ * @since 1.6
+ */
+ public static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader){
+ ClassLoader cl = classLoader;
+
+ if (cl == null) {
+ cl = ss.getContextClassLoader();
+ }
+
+ SchemaFactory f = new SchemaFactoryFinder(cl).createInstance(factoryClassName);
+ if (f == null) {
+ throw new IllegalArgumentException(
+ "Factory " + factoryClassName
+ + " could not be loaded to implement the schema language specified by: " + schemaLanguage);
+ }
+ //if this factory supports the given schemalanguage return this factory else thrown exception
+ if(f.isSchemaLanguageSupported(schemaLanguage)){
+ return f;
+ }else{
+ throw new IllegalArgumentException(
+ "Factory " + f.getClass().getName()
+ + " does not implement the schema language specified by: " + schemaLanguage);
+ }
+
+ }
+
+ /**
+ * Is specified schema supported by this SchemaFactory?
SchemaFactory will understand.
+ * schemaLanguage must specify a valid schema language.
+ *
+ * @return true if SchemaFactory supports schemaLanguage, else false.
+ *
+ * @throws NullPointerException If schemaLanguage is null.
+ * @throws IllegalArgumentException If schemaLanguage.length() == 0
+ * or schemaLanguage does not specify a valid schema language.
+ */
+ public abstract boolean isSchemaLanguageSupported(String schemaLanguage);
+
+ /**
+ * Look up the value of a feature flag.
+ *
+ * The feature name is any fully-qualified URI. It is + * possible for a {@link SchemaFactory} to recognize a feature name but + * temporarily be unable to return its value. + * + *
Implementors are free (and encouraged) to invent their own features, + * using names built on their own URIs.
+ * + * @param name The feature name, which is a non-null fully-qualified URI. + * + * @return The current value of the feature (true or false). + * + * @throws SAXNotRecognizedException If the feature + * value can't be assigned or retrieved. + * @throws SAXNotSupportedException When the + * {@link SchemaFactory} recognizes the feature name but + * cannot determine its value at this time. + * @throws NullPointerException Ifname is null.
+ *
+ * @see #setFeature(String, boolean)
+ */
+ public boolean getFeature(String name)
+ throws SAXNotRecognizedException, SAXNotSupportedException {
+
+ if (name == null) {
+ throw new NullPointerException("the name parameter is null");
+ }
+ throw new SAXNotRecognizedException(name);
+ }
+
+ /**
+ * Set a feature for this SchemaFactory,
+ * {@link Schema}s created by this factory, and by extension,
+ * {@link Validator}s and {@link ValidatorHandler}s created by
+ * those {@link Schema}s.
+ *
Implementors and developers should pay particular attention
+ * to how the special {@link Schema} object returned by {@link
+ * #newSchema()} is processed. In some cases, for example, when the
+ * SchemaFactory and the class actually loading the
+ * schema come from different implementations, it may not be possible
+ * for SchemaFactory features to be inherited automatically.
+ * Developers should
+ * make sure that features, such as secure processing, are explicitly
+ * set in both places.
The feature name is any fully-qualified URI. It is + * possible for a {@link SchemaFactory} to expose a feature value but + * to be unable to change the current value.
+ * + *All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. + * When the feature is:
+ *true: the implementation will limit XML processing to conform to implementation limits.
+ * Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources.
+ * If XML processing is limited for security reasons, it will be reported via a call to the registered
+ * {@link ErrorHandler#fatalError(SAXParseException exception)}.
+ * See {@link #setErrorHandler(ErrorHandler errorHandler)}.
+ * false: the implementation will processing XML according to the XML specifications without
+ * regard to possible implementation limits.
+ * name is null.
+ *
+ * @see #getFeature(String)
+ */
+ public void setFeature(String name, boolean value)
+ throws SAXNotRecognizedException, SAXNotSupportedException {
+
+ if (name == null) {
+ throw new NullPointerException("the name parameter is null");
+ }
+ throw new SAXNotRecognizedException(name);
+ }
+
+ /**
+ * Set the value of a property.
+ *
+ * The property name is any fully-qualified URI. It is + * possible for a {@link SchemaFactory} to recognize a property name but + * to be unable to change the current value.
+ * + *{@link SchemaFactory}s are not required to recognize setting + * any specific property names.
+ * + * @param name The property name, which is a non-null fully-qualified URI. + * @param object The requested value for the property. + * + * @throws SAXNotRecognizedException If the property + * value can't be assigned or retrieved. + * @throws SAXNotSupportedException When the + * {@link SchemaFactory} recognizes the property name but + * cannot set the requested value. + * @throws NullPointerException Ifname is null.
+ */
+ public void setProperty(String name, Object object)
+ throws SAXNotRecognizedException, SAXNotSupportedException {
+
+ if (name == null) {
+ throw new NullPointerException("the name parameter is null");
+ }
+ throw new SAXNotRecognizedException(name);
+ }
+
+ /**
+ * Look up the value of a property.
+ *
+ * The property name is any fully-qualified URI. It is + * possible for a {@link SchemaFactory} to recognize a property name but + * temporarily be unable to return its value.
+ * + *{@link SchemaFactory}s are not required to recognize any specific + * property names.
+ * + *Implementors are free (and encouraged) to invent their own properties, + * using names built on their own URIs.
+ * + * @param name The property name, which is a non-null fully-qualified URI. + * + * @return The current value of the property. + * + * @throws SAXNotRecognizedException If the property + * value can't be assigned or retrieved. + * @throws SAXNotSupportedException When the + * XMLReader recognizes the property name but + * cannot determine its value at this time. + * @throws NullPointerException Ifname is null.
+ *
+ * @see #setProperty(String, Object)
+ */
+ public Object getProperty(String name)
+ throws SAXNotRecognizedException, SAXNotSupportedException {
+
+ if (name == null) {
+ throw new NullPointerException("the name parameter is null");
+ }
+ throw new SAXNotRecognizedException(name);
+ }
+
+ /**
+ * Sets the {@link ErrorHandler} to receive errors encountered
+ * during the newSchema method invocation.
+ *
+ * + * Error handler can be used to customize the error handling process + * during schema parsing. When an {@link ErrorHandler} is set, + * errors found during the parsing of schemas will be first sent + * to the {@link ErrorHandler}. + * + *
+ * The error handler can abort the parsing of a schema immediately + * by throwing {@link SAXException} from the handler. Or for example + * it can print an error to the screen and try to continue the + * processing by returning normally from the {@link ErrorHandler} + * + *
+ * If any {@link Throwable} (or instances of its derived classes)
+ * is thrown from an {@link ErrorHandler},
+ * the caller of the newSchema method will be thrown
+ * the same {@link Throwable} object.
+ *
+ *
+ * {@link SchemaFactory} is not allowed to + * throw {@link SAXException} without first reporting it to + * {@link ErrorHandler}. + * + *
+ * Applications can call this method even during a {@link Schema} + * is being parsed. + * + *
+ * When the {@link ErrorHandler} is null, the implementation will + * behave as if the following {@link ErrorHandler} is set: + *
+ * class DraconianErrorHandler implements {@link ErrorHandler} {
+ * public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
+ * throw e;
+ * }
+ * public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
+ * throw e;
+ * }
+ * public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
+ * // noop
+ * }
+ * }
+ *
+ *
+ *
+ * When a new {@link SchemaFactory} object is created, initially
+ * this field is set to null. This field will NOT be
+ * inherited to {@link Schema}s, {@link Validator}s, or
+ * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}.
+ *
+ * @param errorHandler A new error handler to be set.
+ * This parameter can be null.
+ */
+ public abstract void setErrorHandler(ErrorHandler errorHandler);
+
+ /**
+ * Gets the current {@link ErrorHandler} set to this {@link SchemaFactory}.
+ *
+ * @return
+ * This method returns the object that was last set through
+ * the {@link #setErrorHandler(ErrorHandler)} method, or null
+ * if that method has never been called since this {@link SchemaFactory}
+ * has created.
+ *
+ * @see #setErrorHandler(ErrorHandler)
+ */
+ public abstract ErrorHandler getErrorHandler();
+
+ /**
+ * Sets the {@link LSResourceResolver} to customize
+ * resource resolution when parsing schemas.
+ *
+ *
+ * {@link SchemaFactory} uses a {@link LSResourceResolver}
+ * when it needs to locate external resources while parsing schemas,
+ * although exactly what constitutes "locating external resources" is
+ * up to each schema language. For example, for W3C XML Schema,
+ * this includes files <include>d or <import>ed,
+ * and DTD referenced from schema files, etc.
+ *
+ *
+ * Applications can call this method even during a {@link Schema} + * is being parsed. + * + *
+ * When the {@link LSResourceResolver} is null, the implementation will + * behave as if the following {@link LSResourceResolver} is set: + *
+ * class DumbDOMResourceResolver implements {@link LSResourceResolver} {
+ * public {@link org.w3c.dom.ls.LSInput} resolveResource(
+ * String publicId, String systemId, String baseURI) {
+ *
+ * return null; // always return null
+ * }
+ * }
+ *
+ *
+ *
+ * If a {@link LSResourceResolver} throws a {@link RuntimeException}
+ * (or instances of its derived classes),
+ * then the {@link SchemaFactory} will abort the parsing and
+ * the caller of the newSchema method will receive
+ * the same {@link RuntimeException}.
+ *
+ *
+ * When a new {@link SchemaFactory} object is created, initially + * this field is set to null. This field will NOT be + * inherited to {@link Schema}s, {@link Validator}s, or + * {@link ValidatorHandler}s that are created from this {@link SchemaFactory}. + * + * @param resourceResolver + * A new resource resolver to be set. This parameter can be null. + */ + public abstract void setResourceResolver(LSResourceResolver resourceResolver); + + /** + * Gets the current {@link LSResourceResolver} set to this {@link SchemaFactory}. + * + * @return + * This method returns the object that was last set through + * the {@link #setResourceResolver(LSResourceResolver)} method, or null + * if that method has never been called since this {@link SchemaFactory} + * has created. + * + * @see #setErrorHandler(ErrorHandler) + */ + public abstract LSResourceResolver getResourceResolver(); + + /** + *
Parses the specified source as a schema and returns it as a schema.
+ * + *This is a convenience method for {@link #newSchema(Source[] schemas)}.
+ * + * @param schema Source that represents a schema. + * + * @return NewSchema from parsing schema.
+ *
+ * @throws SAXException If a SAX error occurs during parsing.
+ * @throws NullPointerException if schema is null.
+ */
+ public Schema newSchema(Source schema) throws SAXException {
+ return newSchema(new Source[]{schema});
+ }
+
+ /**
+ * Parses the specified File as a schema and returns it as a Schema.
This is a convenience method for {@link #newSchema(Source schema)}.
+ * + * @param schema File that represents a schema. + * + * @return NewSchema from parsing schema.
+ *
+ * @throws SAXException If a SAX error occurs during parsing.
+ * @throws NullPointerException if schema is null.
+ */
+ public Schema newSchema(File schema) throws SAXException {
+ return newSchema(new StreamSource(schema));
+ }
+
+ /**
+ * Parses the specified URL as a schema and returns it as a Schema.
This is a convenience method for {@link #newSchema(Source schema)}.
+ * + * @param schemaURL that represents a schema.
+ *
+ * @return New Schema from parsing schema.
+ *
+ * @throws SAXException If a SAX error occurs during parsing.
+ * @throws NullPointerException if schema is null.
+ */
+ public Schema newSchema(URL schema) throws SAXException {
+ return newSchema(new StreamSource(schema.toExternalForm()));
+ }
+
+ /**
+ * Parses the specified source(s) as a schema and returns it as a schema.
+ *
+ * + * The callee will read all the {@link Source}s and combine them into a + * single schema. The exact semantics of the combination depends on the schema + * language that this {@link SchemaFactory} object is created for. + * + *
+ * When an {@link ErrorHandler} is set, the callee will report all the errors + * found in sources to the handler. If the handler throws an exception, it will + * abort the schema compilation and the same exception will be thrown from + * this method. Also, after an error is reported to a handler, the callee is allowed + * to abort the further processing by throwing it. If an error handler is not set, + * the callee will throw the first error it finds in the sources. + * + *
+ * The resulting schema contains components from the specified sources. + * The same result would be achieved if all these sources were + * imported, using appropriate values for schemaLocation and namespace, + * into a single schema document with a different targetNamespace + * and no components of its own, if the import elements were given + * in the same order as the sources. Section 4.2.3 of the XML Schema + * recommendation describes the options processors have in this + * regard. While a processor should be consistent in its treatment of + * JAXP schema sources and XML Schema imports, the behaviour between + * JAXP-compliant parsers may vary; in particular, parsers may choose + * to ignore all but the first <import> for a given namespace, + * regardless of information provided in schemaLocation. + * + *
+ * If the parsed set of schemas includes error(s) as + * specified in the section 5.1 of the XML Schema spec, then + * the error must be reported to the {@link ErrorHandler}. + * + *
For RELAX NG, this method must throw {@link UnsupportedOperationException}
+ * if schemas.length!=1.
+ *
+ *
+ * @param schemas
+ * inputs to be parsed. {@link SchemaFactory} is required
+ * to recognize {@link javax.xml.transform.sax.SAXSource},
+ * {@link StreamSource},
+ * {@link javax.xml.transform.stax.StAXSource},
+ * and {@link javax.xml.transform.dom.DOMSource}.
+ * Input schemas must be XML documents or
+ * XML elements and must not be null. For backwards compatibility,
+ * the results of passing anything other than
+ * a document or element are implementation-dependent.
+ * Implementations must either recognize and process the input
+ * or thrown an IllegalArgumentException.
+ *
+ * @return
+ * Always return a non-null valid {@link Schema} object.
+ * Note that when an error has been reported, there is no
+ * guarantee that the returned {@link Schema} object is
+ * meaningful.
+ *
+ * @throws SAXException
+ * If an error is found during processing the specified inputs.
+ * When an {@link ErrorHandler} is set, errors are reported to
+ * there first. See {@link #setErrorHandler(ErrorHandler)}.
+ * @throws NullPointerException
+ * If the schemas parameter itself is null or
+ * any item in the array is null.
+ * @throws IllegalArgumentException
+ * If any item in the array is not recognized by this method.
+ * @throws UnsupportedOperationException
+ * If the schema language doesn't support this operation.
+ */
+ public abstract Schema newSchema(Source[] schemas) throws SAXException;
+
+ /**
+ * Creates a special {@link Schema} object.
+ *
+ *
The exact semantics of the returned {@link Schema} object + * depend on the schema language for which this {@link SchemaFactory} + * is created. + * + *
Also, implementations are allowed to use implementation-specific + * property/feature to alter the semantics of this method.
+ * + *Implementors and developers should pay particular attention + * to how the features set on this {@link SchemaFactory} are + * processed by this special {@link Schema}. + * In some cases, for example, when the + * {@link SchemaFactory} and the class actually loading the + * schema come from different implementations, it may not be possible + * for {@link SchemaFactory} features to be inherited automatically. + * Developers should + * make sure that features, such as secure processing, are explicitly + * set in both places.
+ * + *+ * For XML Schema, this method creates a {@link Schema} object that + * performs validation by using location hints specified in documents. + * + *
+ * The returned {@link Schema} object assumes that if documents + * refer to the same URL in the schema location hints, + * they will always resolve to the same schema document. This + * asusmption allows implementations to reuse parsed results of + * schema documents so that multiple validations against the same + * schema will run faster. + * + *
+ * Note that the use of schema location hints introduces a + * vulnerability to denial-of-service attacks. + * + * + *
+ * RELAX NG does not support this operation. + * + * @return + * Always return non-null valid {@link Schema} object. + * + * @throws UnsupportedOperationException + * If this operation is not supported by the callee. + * @throws SAXException + * If this operation is supported but failed for some reason. + */ + public abstract Schema newSchema() throws SAXException; +}