package com.thaiopensource.validate;

import org.xml.sax.ContentHandler;
import org.xml.sax.DTDHandler;

/**
 * Validates an XML document with respect to a schema.  The schema is
 * determined when the <code>Validator</code> is created and cannot be
 * changed.  The XML document is provided to the <code>Validator</code>
 * by calling methods of the <code>ContentHandler</code> object returned
 * by <code>getContentHandler</code>; the methods must be called in
 * the sequence specified by the <code>ContentHandler</code>
 * interface.  If the <code>getDTDHandler</code> method returns
 * a non-null object, then method calls must be made on it
 * reporting DTD information.
 *
 * <p>Any errors will be reported to the <code>ErrorHandler</code>
 * specified when the <code>Validator</code> was created.  If, after the
 * call to the <code>endDocument</code> method, no errors have been
 * reported, then the XML document is valid.
 *
 * <p>A single <code>Validator</code> object is <em>not</em> safe for
 * concurrent access from multiple threads. A single
 * <code>ValidatorHandler</code> can be used to validate only a single
 * document at a time.
 *
 * <p>After completing validation of an XML document (i.e. after calling
 * the <code>endDocument</code> on the <code>ContentHandler</code>),
 * <code>reset</code> can be called to allow validation of another
 * document. The <code>reset</code> method may create new <code>ContentHandler</code>
 * and <code>DTDHandler</code> objects or may simply reinitialize the
 * state of the existing objects.  Therefore, <code>getContentHandler</code>
 * and <code>getDTDHandler</code> must be called after <code>reset</code>
 * to retrieve the objects to which the XML document to be validated
 * must be provided.
 *
 * @author <a href="mailto:jjc@jclark.com">James Clark</a>
 */
public interface Validator {
  /**
   * Returns the ContentHandler that will receive the XML document.
   * Information about the XML document to be validated must be
   * reported by calling methods on the returned ContentHandler.
   * When validation of an XML document has been completed (either
   * endDocument() has been called or validation has been abandoned
   * prematurely), reset() must be called.  If no calls are made
   * on the ContentHandler, then reset() need not be called.
   * Implementations should allocate resources that require
   * cleanup (e.g. threads, open files) lazily, typically
   * in startDocument().
   *
   * This method does not change the state of the Validator: the same
   * object will always be returned unless <code>reset</code> is called.
   *
   * @see #reset()
   * @return a ContentHandler, never <code>null</code>
   */
  ContentHandler getContentHandler();

  /**
   * Returns a DTDHandler. Information about the DTD must be reported
   * by calling methods on the returned object, unless <code>null</code>
   * is returned.  The same object will always be returned unless
   * <code>reset</code> is called: this method does not change the state
   * of the Validator.
   *
   * @return a DTDHandler, maybe <code>null</code> if DTD information is
   * not significant to the <code>Validator</code>
   */
  DTDHandler getDTDHandler();

   /**
    * Cleans up after validating a document.  After completing validation
    * of a document, <code>reset</code> must be called. After calling
    * reset(), another document may be validated.  Calling this method
    * may create new ContentHandler and DTDHandler objects or may simply
    * reinitialize the state of the existing objects.
    */
   void reset();
}