Validatorpublic abstract class Validator extends Object 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 or DOMSource. |
| Constructors Summary |
|---|
protected 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}.
|
| Methods Summary |
|---|
| public abstract org.xml.sax.ErrorHandler | getErrorHandler()Gets the current {@link ErrorHandler} set to this {@link Validator}.
| | public boolean | getFeature(java.lang.String name)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.
if(name==null) throw new NullPointerException("the name parameter is null");
throw new SAXNotRecognizedException(name);
| | public java.lang.Object | getProperty(java.lang.String 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.
if(name==null) throw new NullPointerException("the name parameter is null");
throw new SAXNotRecognizedException(name);
| | public abstract org.w3c.dom.ls.LSResourceResolver | getResourceResolver()Gets the current {@link LSResourceResolver} set to this {@link Validator}.
| | public abstract void | reset()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 | setErrorHandler(org.xml.sax.ErrorHandler errorHandler)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.
| | public void | setFeature(java.lang.String name, boolean value)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.
if(name==null) throw new NullPointerException("the name parameter is null");
throw new SAXNotRecognizedException(name);
| | public void | setProperty(java.lang.String name, java.lang.Object object)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.
if(name==null) throw new NullPointerException("the name parameter is null");
throw new SAXNotRecognizedException(name);
| | public abstract void | setResourceResolver(org.w3c.dom.ls.LSResourceResolver resourceResolver)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.
| | public void | validate(javax.xml.transform.Source source)Validates the specified input.
This is just a convenience method of:
validate(source,null);
validate(source, null);
| | public abstract void | validate(javax.xml.transform.Source source, javax.xml.transform.Result result)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} |
| null |
OK |
OK |
| {@link javax.xml.transform.sax.SAXResult} |
OK |
Err |
| {@link javax.xml.transform.dom.DOMResult} |
Err |
OK |
Note that {@link javax.xml.transform.stream.StreamSource} instances are not allowed. To process
a StreamSource, or 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.
|
|
