Back to index...

	/*
	* Copyright (c) 2003, 2005, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package javax.xml.validation;

	import org.w3c.dom.ls.LSResourceResolver;
	import org.xml.sax.ContentHandler;
	import org.xml.sax.ErrorHandler;
	import org.xml.sax.SAXNotRecognizedException;
	import org.xml.sax.SAXNotSupportedException;

	/**
	* Streaming validator that works on SAX stream.
	*
	* <p>
	* A {@link ValidatorHandler} object is not thread-safe and not reentrant.
	* In other words, it is the application's responsibility to make
	* sure that one {@link ValidatorHandler} object is not used from
	* more than one thread at any given time.
	*
	* <p>
	* {@link ValidatorHandler} checks if the SAX events follow
	* the set of constraints described in the associated {@link Schema},
	* and additionally it may modify the SAX events (for example
	* by adding default values, etc.)
	*
	* <p>
	* {@link ValidatorHandler} extends from {@link ContentHandler},
	* but it refines the underlying {@link ContentHandler} in
	* the following way:
	* <ol>
	* <li>startElement/endElement events must receive non-null String
	* for <code>uri</code>, <code>localName</code>, and <code>qname</code>,
	* even though SAX allows some of them to be null.
	* Similarly, the user-specified {@link ContentHandler} will receive non-null
	* Strings for all three parameters.
	*
	* <li>Applications must ensure that {@link ValidatorHandler}'s
	* {@link ContentHandler#startPrefixMapping(String,String)} and
	* {@link ContentHandler#endPrefixMapping(String)} are invoked
	* properly. Similarly, the user-specified {@link ContentHandler}
	* will receive startPrefixMapping/endPrefixMapping events.
	* If the {@link ValidatorHandler} introduces additional namespace
	* bindings, the user-specified {@link ContentHandler} will receive
	* additional startPrefixMapping/endPrefixMapping events.
	*
	* <li>{@link org.xml.sax.Attributes} for the
	* {@link ContentHandler#startElement(String,String,String,Attributes)} method
	* may or may not include xmlns* attributes.
	* </ol>
	*
	* <p>
	* A {@link ValidatorHandler} is automatically reset every time
	* the startDocument method is invoked.
	*
	* <h2>Recognized Properties and Features</h2>
	* <p>
	* This spec defines the following feature that must be recognized
	* by all {@link ValidatorHandler} implementations.
	*
	* <h3><code>http://xml.org/sax/features/namespace-prefixes</code></h3>
	* <p>
	* This feature controls how a {@link ValidatorHandler} introduces
	* namespace bindings that were not present in the original SAX event
	* stream.
	* When this feature is set to true, it must make
	* sure that the user's {@link ContentHandler} will see
	* the corresponding <code>xmlns*</code> attribute in
	* the {@link org.xml.sax.Attributes} object of the
	* {@link ContentHandler#startElement(String,String,String,Attributes)}
	* callback. Otherwise, <code>xmlns*</code> attributes must not be
	* added to {@link org.xml.sax.Attributes} that's passed to the
	* user-specified {@link ContentHandler}.
	* <p>
	* (Note that regardless of this switch, namespace bindings are
	* always notified to applications through
	* {@link ContentHandler#startPrefixMapping(String,String)} and
	* {@link ContentHandler#endPrefixMapping(String)} methods of the
	* {@link ContentHandler} specified by the user.)
	*
	* <p>
	* Note that this feature does <em>NOT</em> affect the way
	* a {@link ValidatorHandler} receives SAX events. It merely
	* changes the way it augments SAX events.
	*
	* <p>This feature is set to <code>false</code> by default.</p>
	*
	* @author Kohsuke Kawaguchi
	* @since 1.5
	*/
	public abstract class ValidatorHandler implements ContentHandler {

	/**
	* <p>Constructor for derived classes.</p>
	*
	* <p>The constructor does nothing.</p>
	*
	* <p>Derived classes must create {@link ValidatorHandler} objects that have
	* <code>null</code> {@link ErrorHandler} and
	* <code>null</code> {@link LSResourceResolver}.</p>
	*/
	protected ValidatorHandler() {
	}

	/**
	* Sets the {@link ContentHandler} which receives
	* the augmented validation result.
	*
	* <p>
	* When a {@link ContentHandler} is specified, a
	* {@link ValidatorHandler} will work as a filter
	* and basically copy the incoming events to the
	* specified {@link ContentHandler}.
	*
	* <p>
	* In doing so, a {@link ValidatorHandler} may modify
	* the events, for example by adding defaulted attributes.
	*
	* <p>
	* A {@link ValidatorHandler} may buffer events to certain
	* extent, but to allow {@link ValidatorHandler} to be used
	* by a parser, the following requirement has to be met.
	*
	* <ol>
	* <li>When
	* {@link ContentHandler#startElement(String, String, String, Attributes)},
	* {@link ContentHandler#endElement(String, String, String)},
	* {@link ContentHandler#startDocument()}, or
	* {@link ContentHandler#endDocument()}
	* are invoked on a {@link ValidatorHandler},
	* the same method on the user-specified {@link ContentHandler}
	* must be invoked for the same event before the callback
	* returns.
	* <li>{@link ValidatorHandler} may not introduce new elements that
	* were not present in the input.
	*
	* <li>{@link ValidatorHandler} may not remove attributes that were
	* present in the input.
	* </ol>
	*
	* <p>
	* When a callback method on the specified {@link ContentHandler}
	* throws an exception, the same exception object must be thrown
	* from the {@link ValidatorHandler}. The {@link ErrorHandler}
	* should not be notified of such an exception.
	*
	* <p>
	* This method can be called even during a middle of a validation.
	*
	* @param receiver
	* A {@link ContentHandler} or a null value.
	*/
	public abstract void setContentHandler(ContentHandler receiver);

	/**
	* Gets the {@link ContentHandler} which receives the
	* augmented validation result.
	*
	* @return
	* This method returns the object that was last set through
	* the {@link #getContentHandler()} method, or null
	* if that method has never been called since this {@link ValidatorHandler}
	* has created.
	*
	* @see #setContentHandler(ContentHandler)
	*/
	public abstract ContentHandler getContentHandler();

	/**
	* Sets the {@link ErrorHandler} to receive errors encountered
	* during the validation.
	*
	* <p>
	* 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}.
	*
	* <p>
	* The error handler can abort further validation immediately
	* by throwing {@link org.xml.sax.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}
	*
	* <p>
	* If any {@link Throwable} is thrown from an {@link ErrorHandler},
	* the same {@link Throwable} object will be thrown toward the
	* root of the call stack.
	*
	* <p>
	* {@link ValidatorHandler} is not allowed to
	* throw {@link org.xml.sax.SAXException} without first reporting it to
	* {@link ErrorHandler}.
	*
	* <p>
	* When the {@link ErrorHandler} is null, the implementation will
	* behave as if the following {@link ErrorHandler} is set:
	* <pre>
	* class DraconianErrorHandler implements {@link ErrorHandler} {
	* public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
	* throw e;
	* }
	* public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
	* throw e;
	* }
	* public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
	* // noop
	* }
	* }
	* </pre>
	*
	* <p>
	* When a new {@link ValidatorHandler} 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 ValidatorHandler}.
	*
	* @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 ValidatorHandler}
	* has created.
	*
	* @see #setErrorHandler(ErrorHandler)
	*/
	public abstract ErrorHandler getErrorHandler();

	/**
	* Sets the {@link LSResourceResolver} to customize
	* resource resolution while in a validation episode.
	*
	* <p>
	* {@link ValidatorHandler} 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.
	*
	* <p>
	* When the {@link LSResourceResolver} is null, the implementation will
	* behave as if the following {@link LSResourceResolver} is set:
	* <pre>
	* class DumbLSResourceResolver implements {@link LSResourceResolver} {
	* public {@link org.w3c.dom.ls.LSInput} resolveResource(
	* String publicId, String systemId, String baseURI) {
	*
	* return null; // always return null
	* }
	* }
	* </pre>
	*
	* <p>
	* If a {@link LSResourceResolver} throws a {@link RuntimeException}
	* (or instances of its derived classes),
	* then the {@link ValidatorHandler} will abort the parsing and
	* the caller of the <code>validate</code> method will receive
	* the same {@link RuntimeException}.
	*
	* <p>
	* When a new {@link ValidatorHandler} 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 ValidatorHandler}.
	*
	* @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 ValidatorHandler}
	* has created.
	*
	* @see #setErrorHandler(ErrorHandler)
	*/
	public abstract LSResourceResolver getResourceResolver();

	/**
	* Obtains the {@link TypeInfoProvider} implementation of this
	* {@link ValidatorHandler}.
	*
	* <p>
	* The obtained {@link TypeInfoProvider} can be queried during a parse
	* to access the type information determined by the validator.
	*
	* <p>
	* Some schema languages do not define the notion of type,
	* for those languages, this method may not be supported.
	* However, to be compliant with this specification, implementations
	* for W3C XML Schema 1.0 must support this operation.
	*
	* @return
	* null if the validator / schema language does not support
	* the notion of {@link org.w3c.dom.TypeInfo}.
	* Otherwise a non-null valid {@link TypeInfoProvider}.
	*/
	public abstract TypeInfoProvider getTypeInfoProvider();


	/**
	* Look up the value of a feature flag.
	*
	* <p>The feature name is any fully-qualified URI. It is
	* possible for a {@link ValidatorHandler} 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.
	*
	* <p>Implementors are free (and encouraged) to invent their own features,
	* using names built on their own URIs.</p>
	*
	* @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 ValidatorHandler} recognizes the feature name but
	* cannot determine its value at this time.
	* @throws NullPointerException When <code>name</code> is <code>null</code>.
	*
	* @see #setFeature(String, boolean)
	*/
	public boolean getFeature(String name)
	throws SAXNotRecognizedException, SAXNotSupportedException {

	if (name == null) {
	throw new NullPointerException();
	}

	throw new SAXNotRecognizedException(name);
	}

	/**
	* <p>Set a feature for this <code>ValidatorHandler</code>.</p>
	*
	* <p>Feature can be used to control the way a
	* {@link ValidatorHandler} parses schemas. The feature name is
	* any fully-qualified URI. It is possible for a
	* {@link SchemaFactory} 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.</p>
	*
	* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
	* When the feature is:</p>
	* <ul>
	* <li>
	* <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
	* Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
	* If XML processing is limited for security reasons, it will be reported via a call to the registered
	* {@link ErrorHandler#fatalError(SAXParseException exception)}.
	* See {@link #setErrorHandler(ErrorHandler errorHandler)}.
	* </li>
	* <li>
	* <code>false</code>: the implementation will processing XML according to the XML specifications without
	* regard to possible implementation limits.
	* </li>
	* </ul>
	*
	* @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 ValidatorHandler} recognizes the feature name but
	* cannot set the requested value.
	* @throws NullPointerException When <code>name</code> is <code>null</code>.
	*
	* @see #getFeature(String)
	*/
	public void setFeature(String name, boolean value)
	throws SAXNotRecognizedException, SAXNotSupportedException {

	if (name == null) {
	throw new NullPointerException();
	}

	throw new SAXNotRecognizedException(name);
	}

	/**
	* Set the value of a property.
	*
	* <p>The property name is any fully-qualified URI. It is
	* possible for a {@link ValidatorHandler} 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.</p>
	*
	* <p>{@link ValidatorHandler}s are not required to recognize setting
	* any specific property names.</p>
	*
	* @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 ValidatorHandler} recognizes the property name but
	* cannot set the requested value.
	* @throws NullPointerException When <code>name</code> is <code>null</code>.
	*/
	public void setProperty(String name, Object object)
	throws SAXNotRecognizedException, SAXNotSupportedException {

	if (name == null) {
	throw new NullPointerException();
	}

	throw new SAXNotRecognizedException(name);
	}

	/**
	* Look up the value of a property.
	*
	* <p>The property name is any fully-qualified URI. It is
	* possible for a {@link ValidatorHandler} 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.</p>
	*
	* <p>{@link ValidatorHandler}s are not required to recognize any specific
	* property names.</p>
	*
	* <p>Implementors are free (and encouraged) to invent their own properties,
	* using names built on their own URIs.</p>
	*
	* @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 <code>name</code> is <code>null</code>.
	*
	* @see #setProperty(String, Object)
	*/
	public Object getProperty(String name)
	throws SAXNotRecognizedException, SAXNotSupportedException {

	if (name == null) {
	throw new NullPointerException();
	}

	throw new SAXNotRecognizedException(name);
	}
	}

Back to index...