All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.xml.validation.Validator 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: Validator.java 888884 2009-12-09 17:36:46Z mrglavas $

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 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 12:36:46 -0500 (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.

*/ public abstract void reset(); /** * Validates the specified input. * *

* 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 Source}/{@link Result} accepted:

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
{@link javax.xml.transform.sax.SAXSource}{@link javax.xml.transform.dom.DOMSource}{@link javax.xml.transform.stax.StAXSource}{@link javax.xml.transform.stream.StreamSource}
nullOKOKOKOK
{@link javax.xml.transform.sax.SAXResult}OKErrErrErr
{@link javax.xml.transform.dom.DOMResult}ErrOKErrErr
{@link javax.xml.transform.stax.StAXResult}ErrErrOKErr
{@link javax.xml.transform.stream.StreamResult}ErrErrErrOK
* *

* 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}, * {@link javax.xml.transform.stax.StAXSource} 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); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy