javax.xml.validation.SchemaFactory Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// $Id: SchemaFactory.java 446598 2006-09-15 12:55:40Z jeremias $
package javax.xml.validation;
import java.io.File;
import java.net.URL;
import javax.xml.transform.Source;
import javax.xml.transform.stream.StreamSource;
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;
/**
* 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 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.
*
*
Schema Language
*
* 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
*
*
*
*
* @author Kohsuke Kawaguchi
* @version $Revision: 446598 $, $Date: 2006-09-15 08:55:40 -0400 (Fri, 15 Sep 2006) $
* @since 1.5
*/
public abstract class SchemaFactory {
/**
* Constructor for derived classes.
*
* The constructor does nothing.
*
* Derived classes must create {@link SchemaFactory} objects that have
* null {@link ErrorHandler} and
* null {@link LSResourceResolver}.
*/
protected SchemaFactory() {
}
/**
* 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:
*
* -
* If the system property
*
"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.
*
* -
* Platform default
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 schemLanguage parameter is null.
*/
public static final 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(schemaLanguage);
}
return f;
}
/**
* Is specified schema supported by this SchemaFactory?
*
* @param schemaLanguage Specifies the schema language which the returned 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).
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but
* cannot determine its value at this time.
* @exception NullPointerException
* if the name parameter 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 the value of a feature flag.
*
*
* Feature can be used to control the way a {@link SchemaFactory}
* parses schemas, although {@link SchemaFactory}s are not required
* to recognize any specific feature names.
*
* 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.
*
*
*
* @param name The feature name, which is a non-null fully-qualified URI.
* @param value The requested value of the feature (true or false).
*
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the feature name but
* cannot set the requested value.
* @exception NullPointerException
* if the name parameter 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.
* @exception org.xml.sax.SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* {@link SchemaFactory} recognizes the property name but
* cannot set the requested value.
* @exception NullPointerException
* if the name parameter 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.
* @exception org.xml.sax.SAXNotRecognizedException If the property
* value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot determine its value at this time.
* @exception NullPointerException
* if the name parameter 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 New Schema 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 New Schema 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 schema URL 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.
*
*
W3C XML Schema 1.0
*
* 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}.
*
*
RELAX NG
*
* 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}, and {@link javax.xml.transform.dom.DOMSource}.
*
* @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 depends
* on the schema language that this {@link SchemaFactory} is created
* for.
*
*
* Also, implementations are allowed to use implementation-specific
* property/feature to alter the semantics of this method.
*
*
*
W3C XML Schema 1.0
*
* 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
*
* 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;
}