001 package com.thaiopensource.validate;
002
003 import org.xml.sax.ContentHandler;
004 import org.xml.sax.DTDHandler;
005
006 /**
007 * Validates an XML document with respect to a schema. The schema is
008 * determined when the <code>Validator</code> is created and cannot be
009 * changed. The XML document is provided to the <code>Validator</code>
010 * by calling methods of the <code>ContentHandler</code> object returned
011 * by <code>getContentHandler</code>; the methods must be called in
012 * the sequence specified by the <code>ContentHandler</code>
013 * interface. If the <code>getDTDHandler</code> method returns
014 * a non-null object, then method calls must be made on it
015 * reporting DTD information.
016 *
017 * <p>Any errors will be reported to the <code>ErrorHandler</code>
018 * specified when the <code>Validator</code> was created. If, after the
019 * call to the <code>endDocument</code> method, no errors have been
020 * reported, then the XML document is valid.
021 *
022 * <p>A single <code>Validator</code> object is <em>not</em> safe for
023 * concurrent access from multiple threads. A single
024 * <code>ValidatorHandler</code> can be used to validate only a single
025 * document at a time.
026 *
027 * <p>After completing validation of an XML document (i.e. after calling
028 * the <code>endDocument</code> on the <code>ContentHandler</code>),
029 * <code>reset</code> can be called to allow validation of another
030 * document. The <code>reset</code> method may create new <code>ContentHandler</code>
031 * and <code>DTDHandler</code> objects or may simply reinitialize the
032 * state of the existing objects. Therefore, <code>getContentHandler</code>
033 * and <code>getDTDHandler</code> must be called after <code>reset</code>
034 * to retrieve the objects to which the XML document to be validated
035 * must be provided.
036 *
037 * @author <a href="mailto:jjc@jclark.com">James Clark</a>
038 */
039 public interface Validator {
040 /**
041 * Returns the ContentHandler that will receive the XML document.
042 * Information about the XML document to be validated must be
043 * reported by calling methods on the returned ContentHandler.
044 * When validation of an XML document has been completed (either
045 * endDocument() has been called or validation has been abandoned
046 * prematurely), reset() must be called. If no calls are made
047 * on the ContentHandler, then reset() need not be called.
048 * Implementations should allocate resources that require
049 * cleanup (e.g. threads, open files) lazily, typically
050 * in startDocument().
051 *
052 * This method does not change the state of the Validator: the same
053 * object will always be returned unless <code>reset</code> is called.
054 *
055 * @see #reset()
056 * @return a ContentHandler, never <code>null</code>
057 */
058 ContentHandler getContentHandler();
059
060 /**
061 * Returns a DTDHandler. Information about the DTD must be reported
062 * by calling methods on the returned object, unless <code>null</code>
063 * is returned. The same object will always be returned unless
064 * <code>reset</code> is called: this method does not change the state
065 * of the Validator.
066 *
067 * @return a DTDHandler, maybe <code>null</code> if DTD information is
068 * not significant to the <code>Validator</code>
069 */
070 DTDHandler getDTDHandler();
071
072 /**
073 * Cleans up after validating a document. After completing validation
074 * of a document, <code>reset</code> must be called. After calling
075 * reset(), another document may be validated. Calling this method
076 * may create new ContentHandler and DTDHandler objects or may simply
077 * reinitialize the state of the existing objects.
078 */
079 void reset();
080 }