A processor that checks an XML document against {@link Schema}.
* ** A validator is a thread-unsafe and non-reentrant object. * 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. *
*
* Note that while the {@link #validate(javax.xml.transform.Source)} and {@link #validate(javax.xml.transform.Source, javax.xml.transform.Result)}
* methods take a {@link Source} instance, the Source
* instance must be a SAXSource, DOMSource, StAXSource or StreamSource.
*
* @author Kohsuke Kawaguchi
* @version $Revision: 888884 $, $Date: 2009-12-09 09:36:46 -0800 (Wed, 09 Dec 2009) $
* @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.
* This is just a convenience method of: *
* validate(source,null);
*
*
* @see #setErrorHandler(ErrorHandler)
*/
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. * *
| * | {@link javax.xml.transform.sax.SAXSource} | *{@link javax.xml.transform.dom.DOMSource} | *{@link javax.xml.transform.stream.StreamSource} | *|
| null | *OK | *OK | *OK | *OK | *
| {@link javax.xml.transform.sax.SAXResult} | *OK | *Err | *Err | *Err | *
| {@link javax.xml.transform.dom.DOMResult} | *Err | *OK | *Err | *Err | *
| {@link javax.xml.transform.stream.StreamResult} | *Err | *Err | *Err | *OK | *
* To validate one {@link Source} into another kind of {@link 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 {@link ErrorHandler} didn't
* throw any exception, then the method returns normally.
*
* @param source
* XML to be validated. Must not be null.
*
* @param result
* The {@link Result} object that receives (possibly augmented)
* XML. This parameter can be null if the caller is not interested
* in it.
*
* Note that when a {@link javax.xml.transform.dom.DOMResult} is used,
* a validator might just pass the same DOM node from
* {@link javax.xml.transform.dom.DOMSource} to
* {@link javax.xml.transform.dom.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 {@link Result} type doesn't match the {@link Source} type,
* or if the specified source is not a
* {@link javax.xml.transform.sax.SAXSource},
* {@link javax.xml.transform.dom.DOMSource} or
* {@link javax.xml.transform.stream.StreamSource}.
*
* @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 the source parameter is null.
*
* @see #validate(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). * @exception org.xml.sax.SAXNotRecognizedException If the feature * value can't be assigned or retrieved. * @exception org.xml.sax.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 property 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). * * @exception org.xml.sax.SAXNotRecognizedException If the feature * value can't be assigned or retrieved. * @exception org.xml.sax.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. * @exception org.xml.sax.SAXNotRecognizedException If the property * value can't be assigned or retrieved. * @exception org.xml.sax.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. * @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. * @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); } }