455 lines
18 KiB
Java
455 lines
18 KiB
Java
/*
|
|
* 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: ValidatorHandler.java 446598 2006-09-15 12:55:40Z jeremias $
|
|
|
|
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 a thread-unsafe, non-reentrant object.
|
|
* 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 <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
|
|
* @version $Revision: 446598 $, $Date: 2006-09-15 05:55:40 -0700 (Fri, 15 Sep 2006) $
|
|
* @since 1.5
|
|
*/
|
|
public abstract class ValidatorHandler implements ContentHandler {
|
|
|
|
/**
|
|
* Constructor for derived classes.
|
|
*
|
|
* <p>
|
|
* The constructor does nothing.
|
|
*
|
|
* <p>
|
|
* Derived classes must create {@link ValidatorHandler} objects that have
|
|
* <tt>null</tt> {@link ErrorHandler} and
|
|
* <tt>null</tt> {@link LSResourceResolver}.
|
|
*/
|
|
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).
|
|
* @exception org.xml.sax.SAXNotRecognizedException If the feature
|
|
* value can't be assigned or retrieved.
|
|
* @exception org.xml.sax.SAXNotSupportedException When the
|
|
* {@link ValidatorHandler} 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("name == null");
|
|
}
|
|
throw new SAXNotRecognizedException(name);
|
|
}
|
|
|
|
/**
|
|
* Set the value of a feature flag.
|
|
*
|
|
* <p>
|
|
* Feature can be used to control the way a {@link ValidatorHandler}
|
|
* parses schemas, although {@link ValidatorHandler}s are not required
|
|
* to recognize any specific property names.</p>
|
|
*
|
|
* <p>The feature name is any fully-qualified URI. It is
|
|
* possible for a {@link ValidatorHandler} 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>
|
|
*
|
|
* @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 ValidatorHandler} 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("name == null");
|
|
}
|
|
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.
|
|
*
|
|
* @exception org.xml.sax.SAXNotRecognizedException If the property
|
|
* value can't be assigned or retrieved.
|
|
* @exception org.xml.sax.SAXNotSupportedException When the
|
|
* {@link ValidatorHandler} 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("name == null");
|
|
}
|
|
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.
|
|
* @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("name == null");
|
|
}
|
|
throw new SAXNotRecognizedException(name);
|
|
}
|
|
}
|