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.6 2002/01/30 21:13:43 dbrownell Exp $
5
6package 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@Deprecated
48public interface DocumentHandler {
49
50
51    /**
52     * Receive an object for locating the origin of SAX document events.
53     *
54     * <p>SAX parsers are strongly encouraged (though not absolutely
55     * required) to supply a locator: if it does so, it must supply
56     * the locator to the application by invoking this method before
57     * invoking any of the other methods in the DocumentHandler
58     * interface.</p>
59     *
60     * <p>The locator allows the application to determine the end
61     * position of any document-related event, even if the parser is
62     * not reporting an error.  Typically, the application will
63     * use this information for reporting its own errors (such as
64     * character content that does not match an application's
65     * business rules).  The information returned by the locator
66     * is probably not sufficient for use with a search engine.</p>
67     *
68     * <p>Note that the locator will return correct information only
69     * during the invocation of the events in this interface.  The
70     * application should not attempt to use it at any other time.</p>
71     *
72     * @param locator An object that can return the location of
73     *                any SAX document event.
74     * @see org.xml.sax.Locator
75     */
76    public abstract void setDocumentLocator (Locator locator);
77
78
79    /**
80     * Receive notification of the beginning of a document.
81     *
82     * <p>The SAX parser will invoke this method only once, before any
83     * other methods in this interface or in DTDHandler (except for
84     * setDocumentLocator).</p>
85     *
86     * @exception org.xml.sax.SAXException Any SAX exception, possibly
87     *            wrapping another exception.
88     */
89    public abstract void startDocument ()
90    throws SAXException;
91
92
93    /**
94     * Receive notification of the end of a document.
95     *
96     * <p>The SAX parser will invoke this method only once, and it will
97     * be the last method invoked during the parse.  The parser shall
98     * not invoke this method until it has either abandoned parsing
99     * (because of an unrecoverable error) or reached the end of
100     * input.</p>
101     *
102     * @exception org.xml.sax.SAXException Any SAX exception, possibly
103     *            wrapping another exception.
104     */
105    public abstract void endDocument ()
106    throws SAXException;
107
108
109    /**
110     * Receive notification of the beginning of an element.
111     *
112     * <p>The Parser will invoke this method at the beginning of every
113     * element in the XML document; there will be a corresponding
114     * endElement() event for every startElement() event (even when the
115     * element is empty). All of the element's content will be
116     * reported, in order, before the corresponding endElement()
117     * event.</p>
118     *
119     * <p>If the element name has a namespace prefix, the prefix will
120     * still be attached.  Note that the attribute list provided will
121     * contain only attributes with explicit values (specified or
122     * defaulted): #IMPLIED attributes will be omitted.</p>
123     *
124     * @param name The element type name.
125     * @param atts The attributes attached to the element, if any.
126     * @exception org.xml.sax.SAXException Any SAX exception, possibly
127     *            wrapping another exception.
128     * @see #endElement
129     * @see org.xml.sax.AttributeList
130     */
131    public abstract void startElement (String name, AttributeList atts)
132    throws SAXException;
133
134
135    /**
136     * Receive notification of the end of an element.
137     *
138     * <p>The SAX parser will invoke this method at the end of every
139     * element in the XML document; there will be a corresponding
140     * startElement() event for every endElement() event (even when the
141     * element is empty).</p>
142     *
143     * <p>If the element name has a namespace prefix, the prefix will
144     * still be attached to the name.</p>
145     *
146     * @param name The element type name
147     * @exception org.xml.sax.SAXException Any SAX exception, possibly
148     *            wrapping another exception.
149     */
150    public abstract void endElement (String name)
151    throws SAXException;
152
153
154    /**
155     * Receive notification of character data.
156     *
157     * <p>The Parser will call this method to report each chunk of
158     * character data.  SAX parsers may return all contiguous character
159     * data in a single chunk, or they may split it into several
160     * chunks; however, all of the characters in any single event
161     * must come from the same external entity, so that the Locator
162     * provides useful information.</p>
163     *
164     * <p>The application must not attempt to read from the array
165     * outside of the specified range.</p>
166     *
167     * <p>Note that some parsers will report whitespace using the
168     * ignorableWhitespace() method rather than this one (validating
169     * parsers must do so).</p>
170     *
171     * @param ch The characters from the XML document.
172     * @param start The start position in the array.
173     * @param length The number of characters to read from the array.
174     * @exception org.xml.sax.SAXException Any SAX exception, possibly
175     *            wrapping another exception.
176     * @see #ignorableWhitespace
177     * @see org.xml.sax.Locator
178     */
179    public abstract void characters (char ch[], int start, int length)
180    throws SAXException;
181
182
183    /**
184     * Receive notification of ignorable whitespace in element content.
185     *
186     * <p>Validating Parsers must use this method to report each chunk
187     * of ignorable whitespace (see the W3C XML 1.0 recommendation,
188     * section 2.10): non-validating parsers may also use this method
189     * if they are capable of parsing and using content models.</p>
190     *
191     * <p>SAX parsers may return all contiguous whitespace in a single
192     * chunk, or they may split it into several chunks; however, all of
193     * the characters in any single event must come from the same
194     * external entity, so that the Locator provides useful
195     * information.</p>
196     *
197     * <p>The application must not attempt to read from the array
198     * outside of the specified range.</p>
199     *
200     * @param ch The characters from the XML document.
201     * @param start The start position in the array.
202     * @param length The number of characters to read from the array.
203     * @exception org.xml.sax.SAXException Any SAX exception, possibly
204     *            wrapping another exception.
205     * @see #characters
206     */
207    public abstract void ignorableWhitespace (char ch[], int start, int length)
208    throws SAXException;
209
210
211    /**
212     * Receive notification of a processing instruction.
213     *
214     * <p>The Parser will invoke this method once for each processing
215     * instruction found: note that processing instructions may occur
216     * before or after the main document element.</p>
217     *
218     * <p>A SAX parser should never report an XML declaration (XML 1.0,
219     * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
220     * using this method.</p>
221     *
222     * @param target The processing instruction target.
223     * @param data The processing instruction data, or null if
224     *        none was supplied.
225     * @exception org.xml.sax.SAXException Any SAX exception, possibly
226     *            wrapping another exception.
227     */
228    public abstract void processingInstruction (String target, String data)
229    throws SAXException;
230
231}
232
233// end of DocumentHandler.java
234