Validator


1   package com.thaiopensource.validate;
2   
3   import org.xml.sax.ContentHandler  ;
4   import org.xml.sax.DTDHandler  ;
5   
6   /**
7    * Validates an XML document with respect to a schema.  The schema is
8    * determined when the <code>Validator</code> is created and cannot be
9    * changed.  The XML document is provided to the <code>Validator</code>
10   * by calling methods of the <code>ContentHandler</code> object returned
11   * by <code>getContentHandler</code>; the methods must be called in
12   * the sequence specified by the <code>ContentHandler</code>
13   * interface.  If the <code>getDTDHandler</code> method returns
14   * a non-null object, then method calls must be made on it
15   * reporting DTD information.
16   *
17   * <p>Any errors will be reported to the <code>ErrorHandler</code>
18   * specified when the <code>Validator</code> was created.  If, after the
19   * call to the <code>endDocument</code> method, no errors have been
20   * reported, then the XML document is valid.
21   *
22   * <p>A single <code>Validator</code> object is <em>not</em> safe for
23   * concurrent access from multiple threads. A single
24   * <code>ValidatorHandler</code> can be used to validate only a single
25   * document at a time.
26   *
27   * <p>After completing validation of an XML document (i.e. after calling
28   * the <code>endDocument</code> on the <code>ContentHandler</code>),
29   * <code>reset</code> can be called to allow validation of another
30   * document. The <code>reset</code> method may create new <code>ContentHandler</code>
31   * and <code>DTDHandler</code> objects or may simply reinitialize the
32   * state of the existing objects.  Therefore, <code>getContentHandler</code>
33   * and <code>getDTDHandler</code> must be called after <code>reset</code>
34   * to retrieve the objects to which the XML document to be validated
35   * must be provided.
36   *
37   * @author <a HREF="mailto:jjc@jclark.com">James Clark</a>
38   */
39  public interface Validator {
40    /**
41     * Returns the ContentHandler that will receive the XML document.
42     * Information about the XML document to be validated must be
43     * reported by calling methods on the returned ContentHandler.
44     * When validation of an XML document has been completed (either
45     * endDocument() has been called or validation has been abandoned
46     * prematurely), reset() must be called.  If no calls are made
47     * on the ContentHandler, then reset() need not be called.
48     * Implementations should allocate resources that require
49     * cleanup (e.g. threads, open files) lazily, typically
50     * in startDocument().
51     *
52     * This method does not change the state of the Validator: the same
53     * object will always be returned unless <code>reset</code> is called.
54     *
55     * @see #reset()
56     * @return a ContentHandler, never <code>null</code>
57     */
58    ContentHandler   getContentHandler();
59  
60    /**
61     * Returns a DTDHandler. Information about the DTD must be reported
62     * by calling methods on the returned object, unless <code>null</code>
63     * is returned.  The same object will always be returned unless
64     * <code>reset</code> is called: this method does not change the state
65     * of the Validator.
66     *
67     * @return a DTDHandler, maybe <code>null</code> if DTD information is
68     * not significant to the <code>Validator</code>
69     */
70    DTDHandler   getDTDHandler();
71  
72     /**
73      * Cleans up after validating a document.  After completing validation
74      * of a document, <code>reset</code> must be called. After calling
75      * reset(), another document may be validated.  Calling this method
76      * may create new ContentHandler and DTDHandler objects or may simply
77      * reinitialize the state of the existing objects.
78      */
79     void reset();
80  }
81
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags