286N/A * Copyright (c) 2003, 2005, Oracle and/or its affiliates. All rights reserved. 286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * <p>A processor that checks an XML document against {@link Schema}.</p> 286N/A * A validator object is not thread-safe and not reentrant. 286N/A * In other words, it is the application's responsibility to make 286N/A * sure that one {@link Validator} object is not used from 286N/A * more than one thread at any given time, and while the <code>validate</code> 286N/A * method is invoked, applications may not recursively call 286N/A * the <code>validate</code> method. 286N/A * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> 286N/A * Constructor for derived classes. 286N/A * <p>The constructor does nothing.</p> 286N/A * <p>Derived classes must create {@link Validator} objects that have 286N/A * <code>null</code> {@link ErrorHandler} and 286N/A * <code>null</code> {@link LSResourceResolver}. 286N/A * <p>Reset this <code>Validator</code> to its original configuration.</p> 286N/A * <p><code>Validator</code> is reset to the same state as when it was created with 286N/A * {@link Schema#newValidator()}. 286N/A * <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s 286N/A * thus saving resources associated with the creation of new <code>Validator</code>s.</p> 286N/A * <p>The reset <code>Validator</code> is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler} 286N/A * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. It is guaranteed to have a functionally equal 286N/A * <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p> 286N/A * Validates the specified input. 286N/A * <p>This is just a convenience method for 286N/A * {@link #validate(Source source, Result result)} 286N/A * with <code>result</code> of <code>null</code>.</p> 286N/A * XML to be validated. Must be an XML document or 286N/A * XML element and must not be null. For backwards compatibility, 286N/A * the results of attempting to validate anything other than 286N/A * a document or element are implementation-dependent. 286N/A * Implementations must either recognize and process the input 286N/A * or throw an IllegalArgumentException. 286N/A * @throws IllegalArgumentException 286N/A * If the <code>Source</code> 286N/A * is an XML artifact that the implementation cannot 286N/A * validate (for example, a processing instruction). 286N/A * If the {@link ErrorHandler} throws a {@link SAXException} or 286N/A * if a fatal error is found and the {@link ErrorHandler} returns 286N/A * If the validator is processing a 286N/A * @throws NullPointerException If <code>source</code> is 286N/A * @see #validate(Source source, Result result) 286N/A * <p>Validates the specified input and send the augmented validation 286N/A * result to the specified output.</p> 286N/A * <p>This method places the following restrictions on the types of 286N/A * the {@link Source}/{@link Result} accepted.</p> 286N/A * <th colspan="5"><code>Source</code> / <code>Result</code> Accepted</th> 286N/A * <tbody align="center"> 286N/A * <td><code>null</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <td><code>IllegalArgumentException</code></td> 286N/A * <p>To validate one <code>Source</code> into another kind of 286N/A * <code>Result</code>, use the identity transformer (see 286N/A * {@link javax.xml.transform.TransformerFactory#newTransformer()}).</p> 286N/A * <p>Errors found during the validation is sent to the specified 286N/A * {@link ErrorHandler}.</p> 286N/A * <p>If a document is valid, or if a document contains some errors 286N/A * but none of them were fatal and the <code>ErrorHandler</code> didn't 286N/A * throw any exception, then the method returns normally.</p> 286N/A * XML to be validated. Must be an XML document or 286N/A * XML element and must not be null. For backwards compatibility, 286N/A * the results of attempting to validate anything other than 286N/A * a document or element are implementation-dependent. 286N/A * Implementations must either recognize and process the input 286N/A * or throw an IllegalArgumentException. 286N/A * The <code>Result</code> object that receives (possibly augmented) 286N/A * XML. This parameter can be null if the caller is not interested 286N/A * Note that when a <code>DOMResult</code> is used, 286N/A * a validator might just pass the same DOM node from 286N/A * <code>DOMSource</code> to <code>DOMResult</code> 286N/A * (in which case <code>source.getNode()==result.getNode()</code>), 286N/A * it might copy the entire DOM tree, or it might alter the 286N/A * node given by the source. 286N/A * @throws IllegalArgumentException 286N/A * If the <code>Result</code> type doesn't match the 286N/A * <code>Source</code> type of if the <code>Source</code> 286N/A * is an XML artifact that the implementation cannot 286N/A * validate (for example, a processing instruction). 286N/A * If the <code>ErrorHandler</code> throws a 286N/A * <code>SAXException</code> or 286N/A * if a fatal error is found and the <code>ErrorHandler</code> returns 286N/A * If the validator is processing a 286N/A * <code>SAXSource</code> and the 286N/A * <code>IOException</code>. 286N/A * @throws NullPointerException 286N/A * If the <code>source</code> parameter is <code>null</code>. 286N/A * @see #validate(Source source) 286N/A * Sets the {@link ErrorHandler} to receive errors encountered 286N/A * during the <code>validate</code> method invocation. 286N/A * Error handler can be used to customize the error handling process 286N/A * during a validation. When an {@link ErrorHandler} is set, 286N/A * errors found during the validation will be first sent 286N/A * to the {@link ErrorHandler}. 286N/A * The error handler can abort further validation immediately 286N/A * by throwing {@link SAXException} from the handler. Or for example 286N/A * it can print an error to the screen and try to continue the 286N/A * validation by returning normally from the {@link ErrorHandler} 286N/A * If any {@link Throwable} is thrown from an {@link ErrorHandler}, 286N/A * the caller of the <code>validate</code> method will be thrown 286N/A * the same {@link Throwable} object. 286N/A * {@link Validator} is not allowed to 286N/A * throw {@link SAXException} without first reporting it to 286N/A * {@link ErrorHandler}. 286N/A * When the {@link ErrorHandler} is null, the implementation will 286N/A * behave as if the following {@link ErrorHandler} is set: 286N/A * class DraconianErrorHandler implements {@link ErrorHandler} { 286N/A * public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { 286N/A * public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { 286N/A * public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} { 286N/A * When a new {@link Validator} object is created, initially 286N/A * this field is set to null. 286N/A * A new error handler to be set. This parameter can be null. 286N/A * Gets the current {@link ErrorHandler} set to this {@link Validator}. 286N/A * This method returns the object that was last set through 286N/A * the {@link #setErrorHandler(ErrorHandler)} method, or null 286N/A * if that method has never been called since this {@link Validator} 286N/A * @see #setErrorHandler(ErrorHandler) 286N/A * Sets the {@link LSResourceResolver} to customize 286N/A * resource resolution while in a validation episode. 286N/A * {@link Validator} uses a {@link LSResourceResolver} 286N/A * when it needs to locate external resources while a validation, 286N/A * although exactly what constitutes "locating external resources" is 286N/A * up to each schema language. 286N/A * When the {@link LSResourceResolver} is null, the implementation will 286N/A * behave as if the following {@link LSResourceResolver} is set: 286N/A * class DumbLSResourceResolver implements {@link LSResourceResolver} { 286N/A * public {@link org.w3c.dom.ls.LSInput} resolveResource( 286N/A * String publicId, String systemId, String baseURI) { 286N/A * return null; // always return null 286N/A * If a {@link LSResourceResolver} throws a {@link RuntimeException} 286N/A * (or instances of its derived classes), 286N/A * then the {@link Validator} will abort the parsing and 286N/A * the caller of the <code>validate</code> method will receive 286N/A * the same {@link RuntimeException}. 286N/A * When a new {@link Validator} object is created, initially 286N/A * this field is set to null. 286N/A * @param resourceResolver 286N/A * A new resource resolver to be set. This parameter can be null. 286N/A * Gets the current {@link LSResourceResolver} set to this {@link Validator}. 286N/A * This method returns the object that was last set through 286N/A * the {@link #setResourceResolver(LSResourceResolver)} method, or null 286N/A * if that method has never been called since this {@link Validator} 286N/A * @see #setErrorHandler(ErrorHandler) 286N/A * Look up the value of a feature flag. 286N/A * <p>The feature name is any fully-qualified URI. It is 286N/A * possible for a {@link Validator} to recognize a feature name but 286N/A * temporarily be unable to return its value. 286N/A * Some feature values may be available only in specific 286N/A * contexts, such as before, during, or after a validation. 286N/A * <p>Implementors are free (and encouraged) to invent their own features, 286N/A * using names built on their own URIs.</p> 286N/A * @param name The feature name, which is a non-null fully-qualified URI. 286N/A * @return The current value of the feature (true or false). 286N/A * @throws SAXNotRecognizedException If the feature 286N/A * value can't be assigned or retrieved. 286N/A * @throws SAXNotSupportedException When the 286N/A * {@link Validator} recognizes the feature name but 286N/A * cannot determine its value at this time. 286N/A * @throws NullPointerException 286N/A * When the name parameter is null. 286N/A * @see #setFeature(String, boolean) 286N/A * Set the value of a feature flag. 286N/A * Feature can be used to control the way a {@link Validator} 286N/A * parses schemas, although {@link Validator}s are not required 286N/A * to recognize any specific feature names.</p> 286N/A * <p>The feature name is any fully-qualified URI. It is 286N/A * possible for a {@link Validator} to expose a feature value but 286N/A * to be unable to change the current value. 286N/A * Some feature values may be immutable or mutable only 286N/A * in specific contexts, such as before, during, or after 286N/A * @param name The feature name, which is a non-null fully-qualified URI. 286N/A * @param value The requested value of the feature (true or false). 286N/A * @throws SAXNotRecognizedException If the feature 286N/A * value can't be assigned or retrieved. 286N/A * @throws SAXNotSupportedException When the 286N/A * {@link Validator} recognizes the feature name but 286N/A * cannot set the requested value. 286N/A * @throws NullPointerException 286N/A * When the name parameter is null. 286N/A * @see #getFeature(String) 286N/A * Set the value of a property. 286N/A * <p>The property name is any fully-qualified URI. It is 286N/A * possible for a {@link Validator} to recognize a property name but 286N/A * to be unable to change the current value. 286N/A * Some property values may be immutable or mutable only 286N/A * in specific contexts, such as before, during, or after 559N/A * All implementations that implement JAXP 1.5 or newer are required to 559N/A * <p>Access to external DTDs in source or Schema file is restricted to 559N/A * property. If access is denied during validation due to the restriction 559N/A * of this property, {@link org.xml.sax.SAXException} will be thrown by the 559N/A * {@link #validate(Source)} method.</p> 559N/A * <p>Access to external reference set by the schemaLocation attribute is 559N/A * restricted to the protocols specified by the 559N/A * If access is denied during validation due to the restriction of this property, 559N/A * {@link #validate(Source)} method.</p> 286N/A * @param name The property name, which is a non-null fully-qualified URI. 286N/A * @param object The requested value for the property. 286N/A * @throws SAXNotRecognizedException If the property 286N/A * value can't be assigned or retrieved. 286N/A * @throws SAXNotSupportedException When the 286N/A * {@link Validator} recognizes the property name but 286N/A * cannot set the requested value. 286N/A * @throws NullPointerException 286N/A * When the name parameter is null. 286N/A * Look up the value of a property. 286N/A * <p>The property name is any fully-qualified URI. It is 286N/A * possible for a {@link Validator} to recognize a property name but 286N/A * temporarily be unable to return its value. 286N/A * Some property values may be available only in specific 286N/A * contexts, such as before, during, or after a validation.</p> 286N/A * <p>{@link Validator}s are not required to recognize any specific 286N/A * <p>Implementors are free (and encouraged) to invent their own properties, 286N/A * using names built on their own URIs.</p> 286N/A * @param name The property name, which is a non-null fully-qualified URI. 286N/A * @return The current value of the property. 286N/A * @throws SAXNotRecognizedException If the property 286N/A * value can't be assigned or retrieved. 286N/A * @throws SAXNotSupportedException When the 286N/A * XMLReader recognizes the property name but 286N/A * cannot determine its value at this time. 286N/A * @throws NullPointerException 286N/A * When the name parameter is null. 286N/A * @see #setProperty(String, Object)