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 * Streaming validator that works on SAX stream. 286N/A * A {@link ValidatorHandler} 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 ValidatorHandler} object is not used from 286N/A * more than one thread at any given time. 286N/A * {@link ValidatorHandler} checks if the SAX events follow 286N/A * the set of constraints described in the associated {@link Schema}, 286N/A * and additionally it may modify the SAX events (for example 286N/A * by adding default values, etc.) 286N/A * {@link ValidatorHandler} extends from {@link ContentHandler}, 286N/A * but it refines the underlying {@link ContentHandler} in 286N/A * for <code>uri</code>, <code>localName</code>, and <code>qname</code>, 286N/A * even though SAX allows some of them to be null. 286N/A * Similarly, the user-specified {@link ContentHandler} will receive non-null 286N/A * Strings for all three parameters. 286N/A * <li>Applications must ensure that {@link ValidatorHandler}'s 286N/A * {@link ContentHandler#startPrefixMapping(String,String)} and 286N/A * {@link ContentHandler#endPrefixMapping(String)} are invoked 286N/A * properly. Similarly, the user-specified {@link ContentHandler} 286N/A * If the {@link ValidatorHandler} introduces additional namespace 286N/A * bindings, the user-specified {@link ContentHandler} will receive 286N/A * {@link ContentHandler#startElement(String,String,String,Attributes)} method 286N/A * may or may not include xmlns* attributes. 286N/A * A {@link ValidatorHandler} is automatically reset every time 286N/A * the startDocument method is invoked. 286N/A * <h2>Recognized Properties and Features</h2> 286N/A * This spec defines the following feature that must be recognized 286N/A * by all {@link ValidatorHandler} implementations. 286N/A * This feature controls how a {@link ValidatorHandler} introduces 286N/A * namespace bindings that were not present in the original SAX event 286N/A * When this feature is set to true, it must make 286N/A * sure that the user's {@link ContentHandler} will see 286N/A * the corresponding <code>xmlns*</code> attribute in 286N/A * {@link ContentHandler#startElement(String,String,String,Attributes)} 286N/A * callback. Otherwise, <code>xmlns*</code> attributes must not be 286N/A * added to {@link org.xml.sax.Attributes} that's passed to the 286N/A * user-specified {@link ContentHandler}. 286N/A * (Note that regardless of this switch, namespace bindings are 286N/A * always notified to applications through 286N/A * {@link ContentHandler#startPrefixMapping(String,String)} and 286N/A * {@link ContentHandler#endPrefixMapping(String)} methods of the 286N/A * {@link ContentHandler} specified by the user.) 286N/A * Note that this feature does <em>NOT</em> affect the way 286N/A * a {@link ValidatorHandler} receives SAX events. It merely 286N/A * changes the way it augments SAX events. 286N/A * <p>This feature is set to <code>false</code> by default.</p> 286N/A * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a> 286N/A * <p>Constructor for derived classes.</p> 286N/A * <p>The constructor does nothing.</p> 286N/A * <p>Derived classes must create {@link ValidatorHandler} objects that have 286N/A * <code>null</code> {@link ErrorHandler} and 286N/A * <code>null</code> {@link LSResourceResolver}.</p> 286N/A * Sets the {@link ContentHandler} which receives 286N/A * the augmented validation result. 286N/A * When a {@link ContentHandler} is specified, a 286N/A * {@link ValidatorHandler} will work as a filter 286N/A * and basically copy the incoming events to the 286N/A * specified {@link ContentHandler}. 286N/A * In doing so, a {@link ValidatorHandler} may modify 286N/A * the events, for example by adding defaulted attributes. 286N/A * A {@link ValidatorHandler} may buffer events to certain 286N/A * extent, but to allow {@link ValidatorHandler} to be used 286N/A * by a parser, the following requirement has to be met. 286N/A * {@link ContentHandler#startElement(String, String, String, Attributes)}, 286N/A * {@link ContentHandler#endElement(String, String, String)}, 286N/A * {@link ContentHandler#startDocument()}, or 286N/A * {@link ContentHandler#endDocument()} 286N/A * are invoked on a {@link ValidatorHandler}, 286N/A * the same method on the user-specified {@link ContentHandler} 286N/A * must be invoked for the same event before the callback 286N/A * <li>{@link ValidatorHandler} may not introduce new elements that 286N/A * were not present in the input. 286N/A * <li>{@link ValidatorHandler} may not remove attributes that were 286N/A * present in the input. 286N/A * When a callback method on the specified {@link ContentHandler} 286N/A * throws an exception, the same exception object must be thrown 286N/A * from the {@link ValidatorHandler}. The {@link ErrorHandler} 286N/A * should not be notified of such an exception. 286N/A * This method can be called even during a middle of a validation. 286N/A * A {@link ContentHandler} or a null value. 286N/A * Gets the {@link ContentHandler} which receives the 286N/A * augmented validation result. 286N/A * This method returns the object that was last set through 286N/A * the {@link #getContentHandler()} method, or null 286N/A * if that method has never been called since this {@link ValidatorHandler} 286N/A * @see #setContentHandler(ContentHandler) 286N/A * Sets the {@link ErrorHandler} to receive errors encountered 286N/A * during the validation. 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 org.xml.sax.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 same {@link Throwable} object will be thrown toward the 286N/A * root of the call stack. 286N/A * {@link ValidatorHandler} is not allowed to 286N/A * throw {@link org.xml.sax.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 org.xml.sax.SAXException} { 286N/A * public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} { 286N/A * public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} { 286N/A * When a new {@link ValidatorHandler} 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 ValidatorHandler}. 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 ValidatorHandler} 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 ValidatorHandler} 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 ValidatorHandler} 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 ValidatorHandler} 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 ValidatorHandler}. 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 ValidatorHandler} 286N/A * @see #setErrorHandler(ErrorHandler) 286N/A * Obtains the {@link TypeInfoProvider} implementation of this 286N/A * {@link ValidatorHandler}. 286N/A * The obtained {@link TypeInfoProvider} can be queried during a parse 286N/A * to access the type information determined by the validator. 286N/A * Some schema languages do not define the notion of type, 286N/A * for those languages, this method may not be supported. 286N/A * However, to be compliant with this specification, implementations 286N/A * for W3C XML Schema 1.0 must support this operation. 286N/A * null if the validator / schema language does not support 286N/A * the notion of {@link org.w3c.dom.TypeInfo}. 286N/A * Otherwise a non-null valid {@link TypeInfoProvider}. 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 ValidatorHandler} 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 ValidatorHandler} recognizes the feature name but 286N/A * cannot determine its value at this time. 286N/A * @throws NullPointerException When <code>name</code> is <code>null</code>. 286N/A * @see #setFeature(String, boolean) 286N/A * <p>Set a feature for this <code>ValidatorHandler</code>.</p> 286N/A * <p>Feature can be used to control the way a 286N/A * {@link ValidatorHandler} parses schemas. The feature name is 286N/A * any fully-qualified URI. It is possible for a 286N/A * {@link SchemaFactory} to 286N/A * expose a feature value but to be unable to change the current 286N/A * value. Some feature values may be immutable or mutable only in 286N/A * specific contexts, such as before, during, or after a 286N/A * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. 286N/A * When the feature is:</p> 286N/A * <code>true</code>: the implementation will limit XML processing to conform to implementation limits. 286N/A * Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources. 286N/A * If XML processing is limited for security reasons, it will be reported via a call to the registered 286N/A * {@link ErrorHandler#fatalError(SAXParseException exception)}. 286N/A * See {@link #setErrorHandler(ErrorHandler errorHandler)}. 286N/A * <code>false</code>: the implementation will processing XML according to the XML specifications without 286N/A * regard to possible implementation limits. 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 ValidatorHandler} recognizes the feature name but 286N/A * cannot set the requested value. 286N/A * @throws NullPointerException When <code>name</code> is <code>null</code>. 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 ValidatorHandler} 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 286N/A * <p>{@link ValidatorHandler}s are not required to recognize setting 286N/A * any specific property names.</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 ValidatorHandler} recognizes the property name but 286N/A * cannot set the requested value. 286N/A * @throws NullPointerException When <code>name</code> is <code>null</code>. 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 ValidatorHandler} 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 ValidatorHandler}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 When <code>name</code> is <code>null</code>. 286N/A * @see #setProperty(String, Object)