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 ot be validated must be
   * reported by calling methods on the returned ContentHandler.
   * 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 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();

   /**
    * Prepares to parse another document.  After completing validation
    * of a document, <code>reset</code> must be called before
    * attempting to validate another document. This may create new
    * ContentHandler and DTDHandler objects or may simply reinitialize
    * the state of the existing objects.
    */
   void reset();
}

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. 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. This may create new
    * ContentHandler and DTDHandler objects or may simply reinitialize
    * the state of the existing objects.
    */
   void reset();
}

Change semantics of reset()