/* * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.xml.validation; import com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchemaFactory; import java.io.File; import java.net.URL; import javax.xml.transform.Source; import javax.xml.transform.stream.StreamSource; import jdk.xml.internal.SecuritySupport; import org.w3c.dom.ls.LSResourceResolver; import org.xml.sax.ErrorHandler; import org.xml.sax.SAXException; import org.xml.sax.SAXNotRecognizedException; import org.xml.sax.SAXNotSupportedException; import org.xml.sax.SAXParseException; /** * Factory that creates {@link Schema} objects. Entry-point to * the validation API. * *
* {@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 {@code synchronized} to protect themselves from broken clients. * *
* {@link SchemaFactory} is not re-entrant. While one of the * {@code newSchema} methods is being invoked, applications * may not attempt to recursively invoke the {@code 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 implementors 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} ("{@code http://www.w3.org/2001/XMLSchema}") | *W3C XML Schema 1.0 | *
{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("{@code http://relaxng.org/ns/structure/1.0}") | *RELAX NG 1.0 | *
The constructor does nothing. * *
Derived classes must create {@link SchemaFactory} objects that have * {@code null} {@link ErrorHandler} and * {@code null} {@link LSResourceResolver}. */ protected SchemaFactory() { } /** * Creates a new instance of the {@code SchemaFactory} builtin * system-default implementation. * * @implSpec The {@code SchemaFactory} builtin * system-default implementation is only required to support the * W3C XML Schema 1.0, * but may support additional schema languages. * * @return A new instance of the {@code SchemaFactory} builtin * system-default implementation. * * @since 9 */ public static SchemaFactory newDefaultInstance() { return XMLSchemaFactory.newXMLSchemaFactoryNoServiceLoader(); } /** * Lookup an implementation of the {@code SchemaFactory} that supports the specified * schema language and return it. * *
To find a {@code 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: *
* If the system property * {@code "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. *
* Use the configuration file "jaxp.properties". The file is in standard * {@link java.util.Properties} format and typically located in the * conf directory of the Java installation. It contains the fully qualified * name of the implementation class with the key being the system property * defined above. *
* The jaxp.properties file is read only once by the JAXP implementation * and its values are then cached for future use. If the file does not exist * when the first attempt is made to read from it, no further attempts are * made to check for its existence. It is not possible to change the value * of any property in jaxp.properties after it has been read for the first time. *
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
* the service-provider loading facility will use the {@linkplain
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
* to attempt to load the service. If the context class
* loader is null, the {@linkplain
* ClassLoader#getSystemClassLoader() system class loader} will be used.
*
* Each potential service provider is required to implement the method
* {@link #isSchemaLanguageSupported(String schemaLanguage)}.
*
* The first service provider found that supports the specified schema
* language is returned.
*
* In case of {@link java.util.ServiceConfigurationError} a
* {@link SchemaFactoryConfigurationError} will be thrown.
*
* Platform default {@code SchemaFactory} is located * in an implementation specific way. There must be a * {@linkplain #newDefaultInstance() platform default} * {@code 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 {@code SchemaFactory} * * @throws IllegalArgumentException * If no implementation of the schema language is available. * @throws NullPointerException * If the {@code schemaLanguage} parameter is null. * @throws SchemaFactoryConfigurationError * If a configuration error is encountered. * * @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader) */ public static SchemaFactory newInstance(String schemaLanguage) { ClassLoader cl; cl = SecuritySupport.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 {@code SchemaFactory} from class name. {@code 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 {@code jaxp.debug} system property will cause * this method to print a lot of debug messages * to {@code 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 * {@code 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 {@code javax.xml.validation.SchemaFactory}. * * @param classLoader {@code ClassLoader} used to load the factory class. If {@code null} * current {@code Thread}'s context classLoader is used to load the factory class. * * @return New instance of a {@code SchemaFactory} * * @throws IllegalArgumentException * if {@code factoryClassName} is {@code null}, or * the factory class cannot be loaded, instantiated or doesn't * support the schema language specified in {@code schemLanguage} * parameter. * * @throws NullPointerException * If the {@code 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 = SecuritySupport.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 {@code SchemaFactory}? * * @param schemaLanguage Specifies the schema language which the returned {@code SchemaFactory} will understand. * {@code schemaLanguage} must specify a valid schema language. * * @return {@code true} if {@code SchemaFactory} supports {@code schemaLanguage}, else {@code false}. * * @throws NullPointerException If {@code schemaLanguage} is {@code null}. * @throws IllegalArgumentException If {@code schemaLanguage.length() == 0} * or {@code 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 If {@code name} is {@code 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 {@code 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 * {@code SchemaFactory} and the class actually loading the * schema come from different implementations, it may not be possible * for {@code 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: *
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. * *
* All implementations that implement JAXP 1.5 or newer are required to * support the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} and * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} properties. * *
Access to external DTDs in Schema files is restricted to the protocols * specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. * If access is denied during the creation of new Schema due to the restriction * of this property, {@link org.xml.sax.SAXException} will be thrown by the * {@link #newSchema(Source)} or {@link #newSchema(File)} * or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method. * *
Access to external DTDs in xml source files is restricted to the protocols * specified by the {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_DTD} property. * If access is denied during validation due to the restriction * of this property, {@link org.xml.sax.SAXException} will be thrown by the * {@link javax.xml.validation.Validator#validate(Source)} or * {@link javax.xml.validation.Validator#validate(Source, Result)} method. * *
Access to external reference set by the schemaLocation attribute is * restricted to the protocols specified by the * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property. * If access is denied during validation due to the restriction of this property, * {@link org.xml.sax.SAXException} will be thrown by the * {@link javax.xml.validation.Validator#validate(Source)} or * {@link javax.xml.validation.Validator#validate(Source, Result)} method. * *
Access to external reference set by the Import * and Include element is restricted to the protocols specified by the * {@link javax.xml.XMLConstants#ACCESS_EXTERNAL_SCHEMA} property. * If access is denied during the creation of new Schema due to the restriction * of this property, {@link org.xml.sax.SAXException} will be thrown by the * {@link #newSchema(Source)} or {@link #newSchema(File)} * or {@link #newSchema(URL)} or {@link #newSchema(Source[])} method. *
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 If {@code name} is {@code 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 {@code 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 {@code 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 {@code 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 {@code
* 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:
*
* 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 {@code 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 New {@code Schema} from parsing {@code schema}.
*
* @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if {@code schema} is null.
*/
public Schema newSchema(Source schema) throws SAXException {
return newSchema(new Source[]{schema});
}
/**
* Parses the specified {@code File} as a schema and returns it as a {@code Schema}.
*
* This is a convenience method for {@link #newSchema(Source schema)}.
*
* @param schema File that represents a schema.
*
* @return New {@code Schema} from parsing {@code schema}.
*
* @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if {@code schema} is null.
*/
public Schema newSchema(File schema) throws SAXException {
return newSchema(new StreamSource(schema));
}
/**
* Parses the specified {@code URL} as a schema and returns it as a {@code Schema}.
*
* This is a convenience method for {@link #newSchema(Source schema)}.
*
* @param schema {@code URL} that represents a schema.
*
* @return New {@code Schema} from parsing {@code schema}.
*
* @throws SAXException If a SAX error occurs during parsing.
* @throws NullPointerException if {@code 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 {@code
* 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 {@code 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 {@code 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;
}
* class DumbDOMResourceResolver implements {@link LSResourceResolver} {
* public {@link org.w3c.dom.ls.LSInput} resolveResource(
* String publicId, String systemId, String baseURI) {
*
* return null; // always return null
* }
* }
*
*
* W3C XML Schema 1.0
* RELAX NG
*
* W3C XML Schema 1.0
* RELAX NG
*