Back to index...

	/*
	* 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 java.io.IOException;

	import javax.xml.transform.Result;
	import javax.xml.transform.Source;

	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;

	/**
	* A processor that checks an XML document against {@link Schema}.
	*
	* <p>
	* A validator object is not thread-safe and not reentrant.
	* In other words, it is the application's responsibility to make
	* sure that one {@link Validator} object is not used from
	* more than one thread at any given time, and while the {@code validate}
	* method is invoked, applications may not recursively call
	* the {@code validate} method.
	*
	*
	* @author Kohsuke Kawaguchi
	* @since 1.5
	*/
	public abstract class Validator {

	/**
	* Constructor for derived classes.
	*
	* <p>The constructor does nothing.
	*
	* <p>Derived classes must create {@link Validator} objects that have
	* {@code null} {@link ErrorHandler} and
	* {@code null} {@link LSResourceResolver}.
	*/
	protected Validator() {
	}

	/**
	* Reset this {@code Validator} to its original configuration.
	*
	* <p>{@code Validator} is reset to the same state as when it was created with
	* {@link Schema#newValidator()}.
	* {@code reset()} is designed to allow the reuse of existing {@code Validator}s
	* thus saving resources associated with the creation of new {@code Validator}s.
	*
	* <p>The reset {@code Validator} is not guaranteed to have
	* the same {@link LSResourceResolver} or {@link ErrorHandler}
	* {@code Object}s, e.g. {@link Object#equals(Object obj)}.
	* It is guaranteed to have a functionally equal
	* {@code LSResourceResolver} and {@code ErrorHandler}.
	*/
	public abstract void reset();

	/**
	* Validates the specified input.
	*
	* <p>This is just a convenience method for
	* {@link #validate(Source source, Result result)}
	* with {@code result} of {@code null}.
	*
	* @param source
	* XML to be validated. Must be an XML document or
	* XML element and must not be null. For backwards compatibility,
	* the results of attempting to validate anything other than
	* a document or element are implementation-dependent.
	* Implementations must either recognize and process the input
	* or throw an IllegalArgumentException.
	*
	* @throws IllegalArgumentException
	* If the {@code Source}
	* is an XML artifact that the implementation cannot
	* validate (for example, a processing instruction).
	*
	* @throws SAXException
	* If the {@link ErrorHandler} throws a {@link SAXException} or
	* if a fatal error is found and the {@link ErrorHandler} returns
	* normally.
	*
	* @throws IOException
	* If the validator is processing a
	* {@link javax.xml.transform.sax.SAXSource} and the
	* underlying {@link org.xml.sax.XMLReader} throws an
	* {@link IOException}.
	*
	*
	* @throws NullPointerException If {@code source} is
	* {@code null}.
	*
	* @see #validate(Source source, Result result)
	*/
	public void validate(Source source)
	throws SAXException, IOException {

	validate(source, null);
	}

	/**
	* Validates the specified input and send the augmented validation
	* result to the specified output.
	*
	* <p>This method places the following restrictions on the types of
	* the {@link Source}/{@link Result} accepted.
	*
	* <table class="plain">
	* <caption>{@code Source} / {@code Result} Accepted</caption>
	* <thead>
	* <tr>
	* <td></td>
	* <th scope="col">{@link javax.xml.transform.stream.StreamSource}</th>
	* <th scope="col">{@link javax.xml.transform.sax.SAXSource}</th>
	* <th scope="col">{@link javax.xml.transform.dom.DOMSource}</th>
	* <th scope="col">{@link javax.xml.transform.stax.StAXSource}</th>
	* </tr>
	* </thead>
	* <tbody style="text-align:center">
	* <tr>
	* <th scope="row">{@code null}</th>
	* <td>OK</td>
	* <td>OK</td>
	* <td>OK</td>
	* <td>OK</td>
	* </tr>
	* <tr>
	* <th scope="row">{@link javax.xml.transform.stream.StreamResult}</th>
	* <td>OK</td>
	* <td>{@code IllegalArgumentException}</td>
	* <td>{@code IllegalArgumentException}</td>
	* <td>{@code IllegalArgumentException}</td>
	* </tr>
	* <tr>
	* <th scope="row">{@link javax.xml.transform.sax.SAXResult}</th>
	* <td>{@code IllegalArgumentException}</td>
	* <td>OK</td>
	* <td>{@code IllegalArgumentException}</td>
	* <td>{@code IllegalArgumentException}</td>
	* </tr>
	* <tr>
	* <th scope="row">{@link javax.xml.transform.dom.DOMResult}</th>
	* <td>{@code IllegalArgumentException}</td>
	* <td>{@code IllegalArgumentException}</td>
	* <td>OK</td>
	* <td>{@code IllegalArgumentException}</td>
	* </tr>
	* <tr>
	* <th scope="row">{@link javax.xml.transform.stax.StAXResult}</th>
	* <td>{@code IllegalArgumentException}</td>
	* <td>{@code IllegalArgumentException}</td>
	* <td>{@code IllegalArgumentException}</td>
	* <td>OK</td>
	* </tr>
	* </tbody>
	* </table>
	*
	* <p>To validate one {@code Source} into another kind of
	* {@code Result}, use the identity transformer (see
	* {@link javax.xml.transform.TransformerFactory#newTransformer()}).
	*
	* <p>Errors found during the validation is sent to the specified
	* {@link ErrorHandler}.
	*
	* <p>If a document is valid, or if a document contains some errors
	* but none of them were fatal and the {@code ErrorHandler} didn't
	* throw any exception, then the method returns normally.
	*
	* @param source
	* XML to be validated. Must be an XML document or
	* XML element and must not be null. For backwards compatibility,
	* the results of attempting to validate anything other than
	* a document or element are implementation-dependent.
	* Implementations must either recognize and process the input
	* or throw an IllegalArgumentException.
	*
	* @param result
	* The {@code Result} object that receives (possibly augmented)
	* XML. This parameter can be null if the caller is not interested
	* in it.
	*
	* Note that when a {@code DOMResult} is used,
	* a validator might just pass the same DOM node from
	* {@code DOMSource} to {@code DOMResult}
	* (in which case {@code source.getNode()==result.getNode()}),
	* it might copy the entire DOM tree, or it might alter the
	* node given by the source.
	*
	* @throws IllegalArgumentException
	* If the {@code Result} type doesn't match the
	* {@code Source} type of if the {@code Source}
	* is an XML artifact that the implementation cannot
	* validate (for example, a processing instruction).
	* @throws SAXException
	* If the {@code ErrorHandler} throws a
	* {@code SAXException} or
	* if a fatal error is found and the {@code ErrorHandler} returns
	* normally.
	* @throws IOException
	* If the validator is processing a
	* {@code SAXSource} and the
	* underlying {@link org.xml.sax.XMLReader} throws an
	* {@code IOException}.
	* @throws NullPointerException
	* If the {@code source} parameter is {@code null}.
	*
	* @see #validate(Source source)
	*/
	public abstract void validate(Source source, Result result)
	throws SAXException, IOException;

	/**
	* Sets the {@link ErrorHandler} to receive errors encountered
	* during the {@code validate} method invocation.
	*
	* <p>
	* Error handler can be used to customize the error handling process
	* during a validation. When an {@link ErrorHandler} is set,
	* errors found during the validation will be first sent
	* to the {@link ErrorHandler}.
	*
	* <p>
	* The error handler can abort further validation immediately
	* by throwing {@link SAXException} from the handler. Or for example
	* it can print an error to the screen and try to continue the
	* validation by returning normally from the {@link ErrorHandler}
	*
	* <p>
	* If any {@link Throwable} is thrown from an {@link ErrorHandler},
	* the caller of the {@code validate} method will be thrown
	* the same {@link Throwable} object.
	*
	* <p>
	* {@link Validator} is not allowed to
	* throw {@link SAXException} without first reporting it to
	* {@link ErrorHandler}.
	*
	* <p>
	* When the {@link ErrorHandler} is null, the implementation will
	* behave as if the following {@link ErrorHandler} is set:
	* <pre>
	* 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
	* }
	* }
	* </pre>
	*
	* <p>
	* When a new {@link Validator} object is created, initially
	* this field is set to null.
	*
	* @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 Validator}.
	*
	* @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 Validator}
	* has created.
	*
	* @see #setErrorHandler(ErrorHandler)
	*/
	public abstract ErrorHandler getErrorHandler();

	/**
	* Sets the {@link LSResourceResolver} to customize
	* resource resolution while in a validation episode.
	*
	* <p>
	* {@link Validator} uses a {@link LSResourceResolver}
	* when it needs to locate external resources while a validation,
	* although exactly what constitutes "locating external resources" is
	* up to each schema language.
	*
	* <p>
	* When the {@link LSResourceResolver} is null, the implementation will
	* behave as if the following {@link LSResourceResolver} is set:
	* <pre>
	* class DumbLSResourceResolver implements {@link LSResourceResolver} {
	* public {@link org.w3c.dom.ls.LSInput} resolveResource(
	* String publicId, String systemId, String baseURI) {
	*
	* return null; // always return null
	* }
	* }
	* </pre>
	*
	* <p>
	* If a {@link LSResourceResolver} throws a {@link RuntimeException}
	* (or instances of its derived classes),
	* then the {@link Validator} will abort the parsing and
	* the caller of the {@code validate} method will receive
	* the same {@link RuntimeException}.
	*
	* <p>
	* When a new {@link Validator} object is created, initially
	* this field is set to null.
	*
	* @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 Validator}.
	*
	* @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 Validator}
	* has created.
	*
	* @see #setErrorHandler(ErrorHandler)
	*/
	public abstract LSResourceResolver getResourceResolver();



	/**
	* Look up the value of a feature flag.
	*
	* <p>The feature name is any fully-qualified URI. It is
	* possible for a {@link Validator} to recognize a feature name but
	* temporarily be unable to return its value.
	* Some feature values may be available only in specific
	* contexts, such as before, during, or after a validation.
	*
	* <p>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 Validator} recognizes the feature name but
	* cannot determine its value at this time.
	* @throws NullPointerException
	* When 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.
	*
	* <p>
	* Feature can be used to control the way a {@link Validator}
	* parses schemas, although {@link Validator}s are not required
	* to recognize any specific feature names.
	*
	* <p>The feature name is any fully-qualified URI. It is
	* possible for a {@link Validator} to expose a feature value but
	* to be unable to change the current value.
	* Some feature values may be immutable or mutable only
	* in specific contexts, such as before, during, or after
	* a validation.
	*
	* @param name The feature name, which is a non-null fully-qualified URI.
	* @param value The requested value of the feature (true or false).
	*
	* @throws SAXNotRecognizedException If the feature
	* value can't be assigned or retrieved.
	* @throws SAXNotSupportedException When the
	* {@link Validator} recognizes the feature name but
	* cannot set the requested value.
	* @throws NullPointerException
	* When 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.
	*
	* <p>The property name is any fully-qualified URI. It is
	* possible for a {@link Validator} to recognize a property name but
	* to be unable to change the current value.
	* Some property values may be immutable or mutable only
	* in specific contexts, such as before, during, or after
	* a validation.
	*
	* <p>
	* 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.
	*
	* <ul>
	* <li>
	* <p>Access to external DTDs in source or Schema file 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 #validate(Source)} method.
	*
	* <p>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 #validate(Source)} method.
	* </li>
	* </ul>
	*
	* @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 Validator} recognizes the property name but
	* cannot set the requested value.
	* @throws NullPointerException
	* When 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.
	*
	* <p>The property name is any fully-qualified URI. It is
	* possible for a {@link Validator} to recognize a property name but
	* temporarily be unable to return its value.
	* Some property values may be available only in specific
	* contexts, such as before, during, or after a validation.
	*
	* <p>{@link Validator}s are not required to recognize any specific
	* property names.
	*
	* <p>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
	* When 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);
	}
	}

Back to index...