javax.xml.validation.Validator Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the "License"). You may not use this file except
* in compliance with the License.
*
* You can obtain a copy of the license at
* https://jaxp.dev.java.net/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* HEADER in each file and include the License file at
* https://jaxp.dev.java.net/CDDLv1.0.html
* If applicable add the following below this CDDL HEADER
* with the fields enclosed by brackets "[]" replaced with
* your own identifying information: Portions Copyright
* [year] [name of copyright owner]
*/
/*
* $Id: Validator.java,v 1.5 2005/11/03 19:34:25 jeffsuttor Exp $
* %W% %E%
*
* Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
*/
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}.
*
*
* 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 validate
* method is invoked, applications may not recursively call
* the validate method.
*
*
*
* @author Kohsuke Kawaguchi
* @version $Revision: 1.5 $, $Date: 2005/11/03 19:34:25 $
* @since 1.5
*/
public abstract class Validator {
/**
* Constructor for derived classes.
*
*
The constructor does nothing.
*
* Derived classes must create {@link Validator} objects that have
* null {@link ErrorHandler} and
* null {@link LSResourceResolver}.
*
*/
protected Validator() {
}
/**
* Reset this Validator to its original configuration.
*
* Validator is reset to the same state as when it was created with
* {@link Schema#newValidator()}.
* reset() is designed to allow the reuse of existing Validators
* thus saving resources associated with the creation of new Validators.
*
* The reset Validator is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler}
* Objects, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal
* LSResourceResolver and ErrorHandler.
*/
public abstract void reset();
/**
* Validates the specified input.
*
* This is just a convenience method for
* {@link #validate(Source source, Result result)}
* with result of 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 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 source is
* 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.
*
* This method places the following restrictions on the types of
* the {@link Source}/{@link Result} accepted.
*
*
*
*
* Source / Result Accepted
*
* {@link javax.xml.transform.stream.StreamSource}
* {@link javax.xml.transform.sax.SAXSource}
* {@link javax.xml.transform.dom.DOMSource}
* {@link javax.xml.transform.stax.StAXSource}
*
*
*
*
* nullOK
* OK
* OK
* OK
*
*
* {@link javax.xml.transform.stream.StreamResult}
* OK
* IllegalArgumentExceptionIllegalArgumentExceptionIllegalArgumentException
*
* {@link javax.xml.transform.sax.SAXResult}
* IllegalArgumentExceptionOK
* IllegalArgumentExceptionIllegalArgumentException
*
* {@link javax.xml.transform.dom.DOMResult}
* IllegalArgumentExceptionIllegalArgumentExceptionOK
* IllegalArgumentException
*
* {@link javax.xml.transform.stax.StAXResult}
* IllegalArgumentExceptionIllegalArgumentExceptionIllegalArgumentExceptionOK
*
*
*
*
* To validate one Source into another kind of
* Result, use the identity transformer (see
* {@link javax.xml.transform.TransformerFactory#newTransformer()}).
*
* Errors found during the validation is sent to the specified
* {@link ErrorHandler}.
*
* If a document is valid, or if a document contains some errors
* but none of them were fatal and the 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 Result object that receives (possibly augmented)
* XML. This parameter can be null if the caller is not interested
* in it.
*
* Note that when a DOMResult is used,
* a validator might just pass the same DOM node from
* DOMSource to DOMResult
* (in which case 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 Result type doesn't match the
* Source type of if the Source
* is an XML artifact that the implementation cannot
* validate (for example, a processing instruction).
* @throws SAXException
* If the ErrorHandler throws a
* SAXException or
* if a fatal error is found and the ErrorHandler returns
* normally.
* @throws IOException
* If the validator is processing a
* SAXSource and the
* underlying {@link org.xml.sax.XMLReader} throws an
* IOException.
* @throws NullPointerException
* If the source parameter is 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 validate method invocation.
*
*
* 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}.
*
*
* 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}
*
*
* If any {@link Throwable} is thrown from an {@link ErrorHandler},
* the caller of the validate method will be thrown
* the same {@link Throwable} object.
*
*
* {@link Validator} is not allowed to
* throw {@link SAXException} without first reporting it to
* {@link ErrorHandler}.
*
*
* 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 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.
*
*
* {@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.
*
*
* When the {@link LSResourceResolver} is null, the implementation will
* behave as if the following {@link LSResourceResolver} is set:
*
* class DumbLSResourceResolver 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 Validator} will abort the parsing and
* the caller of the validate method will receive
* the same {@link RuntimeException}.
*
*
* 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.
*
*
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.
*
*
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.
*
*
* 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.
*
* 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.
*
* 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.
*
* {@link Validator}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 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.
*
* 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.
*
* {@link Validator}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
* 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);
}
}