DocumentHandler


1   // SAX document handler.
2   // http://www.saxproject.org
3   // No warranty; no copyright -- use this as you will.
4   // $Id: DocumentHandler.java,v 1.1.24.1 2004/05/01 08:34:39 jsuttor Exp $
5   
6   package org.xml.sax;
7   
8   /**
9    * Receive notification of general document events.
10   *
11   * <blockquote>
12   * <em>This module, both source code and documentation, is in the
13   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
14   * See <a HREF='http://www.saxproject.org'>http://www.saxproject.org</a>
15   * for further information.
16   * </blockquote>
17   *
18   * <p>This was the main event-handling interface for SAX1; in
19   * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler
20   * ContentHandler}, which provides Namespace support and reporting
21   * of skipped entities.  This interface is included in SAX2 only
22   * to support legacy SAX1 applications.</p>
23   *
24   * <p>The order of events in this interface is very important, and
25   * mirrors the order of information in the document itself.  For
26   * example, all of an element's content (character data, processing
27   * instructions, and/or subelements) will appear, in order, between
28   * the startElement event and the corresponding endElement event.</p>
29   *
30   * <p>Application writers who do not want to implement the entire
31   * interface can derive a class from HandlerBase, which implements
32   * the default functionality; parser writers can instantiate
33   * HandlerBase to obtain a default handler.  The application can find
34   * the location of any document event using the Locator interface
35   * supplied by the Parser through the setDocumentLocator method.</p>
36   *
37   * @deprecated This interface has been replaced by the SAX2
38   *             {@link org.xml.sax.ContentHandler ContentHandler}
39   *             interface, which includes Namespace support.
40   * @since SAX 1.0
41   * @author David Megginson
42   * @version 2.0.1 (sax2r2)
43   * @see org.xml.sax.Parser#setDocumentHandler
44   * @see org.xml.sax.Locator
45   * @see org.xml.sax.HandlerBase
46   */
47  public interface DocumentHandler {
48      
49      
50      /**
51       * Receive an object for locating the origin of SAX document events.
52       *
53       * <p>SAX parsers are strongly encouraged (though not absolutely
54       * required) to supply a locator: if it does so, it must supply
55       * the locator to the application by invoking this method before
56       * invoking any of the other methods in the DocumentHandler
57       * interface.</p>
58       *
59       * <p>The locator allows the application to determine the end
60       * position of any document-related event, even if the parser is
61       * not reporting an error.  Typically, the application will
62       * use this information for reporting its own errors (such as
63       * character content that does not match an application's
64       * business rules).  The information returned by the locator
65       * is probably not sufficient for use with a search engine.</p>
66       *
67       * <p>Note that the locator will return correct information only
68       * during the invocation of the events in this interface.  The
69       * application should not attempt to use it at any other time.</p>
70       *
71       * @param locator An object that can return the location of
72       *                any SAX document event.
73       * @see org.xml.sax.Locator
74       */
75      public abstract void setDocumentLocator (Locator   locator);
76      
77      
78      /**
79       * Receive notification of the beginning of a document.
80       *
81       * <p>The SAX parser will invoke this method only once, before any
82       * other methods in this interface or in DTDHandler (except for
83       * setDocumentLocator).</p>
84       *
85       * @exception org.xml.sax.SAXException Any SAX exception, possibly
86       *            wrapping another exception.
87       */
88      public abstract void startDocument ()
89      throws SAXException  ;
90      
91      
92      /**
93       * Receive notification of the end of a document.
94       *
95       * <p>The SAX parser will invoke this method only once, and it will
96       * be the last method invoked during the parse.  The parser shall
97       * not invoke this method until it has either abandoned parsing
98       * (because of an unrecoverable error) or reached the end of
99       * input.</p>
100      *
101      * @exception org.xml.sax.SAXException Any SAX exception, possibly
102      *            wrapping another exception.
103      */
104     public abstract void endDocument ()
105     throws SAXException  ;
106     
107     
108     /**
109      * Receive notification of the beginning of an element.
110      *
111      * <p>The Parser will invoke this method at the beginning of every
112      * element in the XML document; there will be a corresponding
113      * endElement() event for every startElement() event (even when the
114      * element is empty). All of the element's content will be
115      * reported, in order, before the corresponding endElement()
116      * event.</p>
117      *
118      * <p>If the element name has a namespace prefix, the prefix will
119      * still be attached.  Note that the attribute list provided will
120      * contain only attributes with explicit values (specified or
121      * defaulted): #IMPLIED attributes will be omitted.</p>
122      *
123      * @param name The element type name.
124      * @param atts The attributes attached to the element, if any.
125      * @exception org.xml.sax.SAXException Any SAX exception, possibly
126      *            wrapping another exception.
127      * @see #endElement
128      * @see org.xml.sax.AttributeList 
129      */
130     public abstract void startElement (String   name, AttributeList   atts)
131     throws SAXException  ;
132     
133     
134     /**
135      * Receive notification of the end of an element.
136      *
137      * <p>The SAX parser will invoke this method at the end of every
138      * element in the XML document; there will be a corresponding
139      * startElement() event for every endElement() event (even when the
140      * element is empty).</p>
141      *
142      * <p>If the element name has a namespace prefix, the prefix will
143      * still be attached to the name.</p>
144      *
145      * @param name The element type name
146      * @exception org.xml.sax.SAXException Any SAX exception, possibly
147      *            wrapping another exception.
148      */
149     public abstract void endElement (String   name)
150     throws SAXException  ;
151     
152     
153     /**
154      * Receive notification of character data.
155      *
156      * <p>The Parser will call this method to report each chunk of
157      * character data.  SAX parsers may return all contiguous character
158      * data in a single chunk, or they may split it into several
159      * chunks; however, all of the characters in any single event
160      * must come from the same external entity, so that the Locator
161      * provides useful information.</p>
162      *
163      * <p>The application must not attempt to read from the array
164      * outside of the specified range.</p>
165      *
166      * <p>Note that some parsers will report whitespace using the
167      * ignorableWhitespace() method rather than this one (validating
168      * parsers must do so).</p>
169      *
170      * @param ch The characters from the XML document.
171      * @param start The start position in the array.
172      * @param length The number of characters to read from the array.
173      * @exception org.xml.sax.SAXException Any SAX exception, possibly
174      *            wrapping another exception.
175      * @see #ignorableWhitespace 
176      * @see org.xml.sax.Locator
177      */
178     public abstract void characters (char ch[], int start, int length)
179     throws SAXException  ;
180     
181     
182     /**
183      * Receive notification of ignorable whitespace in element content.
184      *
185      * <p>Validating Parsers must use this method to report each chunk
186      * of ignorable whitespace (see the W3C XML 1.0 recommendation,
187      * section 2.10): non-validating parsers may also use this method
188      * if they are capable of parsing and using content models.</p>
189      *
190      * <p>SAX parsers may return all contiguous whitespace in a single
191      * chunk, or they may split it into several chunks; however, all of
192      * the characters in any single event must come from the same
193      * external entity, so that the Locator provides useful
194      * information.</p>
195      *
196      * <p>The application must not attempt to read from the array
197      * outside of the specified range.</p>
198      *
199      * @param ch The characters from the XML document.
200      * @param start The start position in the array.
201      * @param length The number of characters to read from the array.
202      * @exception org.xml.sax.SAXException Any SAX exception, possibly
203      *            wrapping another exception.
204      * @see #characters
205      */
206     public abstract void ignorableWhitespace (char ch[], int start, int length)
207     throws SAXException  ;
208     
209     
210     /**
211      * Receive notification of a processing instruction.
212      *
213      * <p>The Parser will invoke this method once for each processing
214      * instruction found: note that processing instructions may occur
215      * before or after the main document element.</p>
216      *
217      * <p>A SAX parser should never report an XML declaration (XML 1.0,
218      * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
219      * using this method.</p>
220      *
221      * @param target The processing instruction target.
222      * @param data The processing instruction data, or null if
223      *        none was supplied.
224      * @exception org.xml.sax.SAXException Any SAX exception, possibly
225      *            wrapping another exception.
226      */
227     public abstract void processingInstruction (String   target, String   data)
228     throws SAXException  ;
229     
230 }
231 
232 // end of DocumentHandler.java
233
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags