Validatorpublic abstract class Validator extends Object A processor that checks an XML document against {@link Schema}.
A validator object is not thread-safe and not reentrant.
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.
|
| 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 feature 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 for
{@link #validate(Source source, Result result)}
with result of 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.
Source / Result Accepted |
|
{@link javax.xml.transform.stream.StreamSource} |
{@link javax.xml.transform.sax.SAXSource} |
{@link javax.xml.transform.dom.DOMSource} |
{@link javax.xml.transform.stax.StAXSource} |
null |
OK |
OK |
OK |
OK |
| {@link javax.xml.transform.stream.StreamResult} |
OK |
IllegalArgumentException |
IllegalArgumentException |
IllegalArgumentException |
| {@link javax.xml.transform.sax.SAXResult} |
IllegalArgumentException |
OK |
IllegalArgumentException |
IllegalArgumentException |
| {@link javax.xml.transform.dom.DOMResult} |
IllegalArgumentException |
IllegalArgumentException |
OK |
IllegalArgumentException |
| {@link javax.xml.transform.stax.StAXResult} |
IllegalArgumentException |
IllegalArgumentException |
IllegalArgumentException |
OK |
To validate one Source into another kind of
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 ErrorHandler didn't
throw any exception, then the method returns normally.
|
|
