001// SAX document handler.
002// http://www.saxproject.org
003// No warranty; no copyright -- use this as you will.
004// $Id: DocumentHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $
005
006package org.xml.sax;
007
008/**
009 * Receive notification of general document events.
010 *
011 * <blockquote>
012 * <em>This module, both source code and documentation, is in the
013 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
014 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
015 * for further information.
016 * </blockquote>
017 *
018 * <p>This was the main event-handling interface for SAX1; in
019 * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler
020 * ContentHandler}, which provides Namespace support and reporting
021 * of skipped entities.  This interface is included in SAX2 only
022 * to support legacy SAX1 applications.</p>
023 *
024 * <p>The order of events in this interface is very important, and
025 * mirrors the order of information in the document itself.  For
026 * example, all of an element's content (character data, processing
027 * instructions, and/or subelements) will appear, in order, between
028 * the startElement event and the corresponding endElement event.</p>
029 *
030 * <p>Application writers who do not want to implement the entire
031 * interface can derive a class from HandlerBase, which implements
032 * the default functionality; parser writers can instantiate
033 * HandlerBase to obtain a default handler.  The application can find
034 * the location of any document event using the Locator interface
035 * supplied by the Parser through the setDocumentLocator method.</p>
036 *
037 * @deprecated This interface has been replaced by the SAX2
038 *             {@link org.xml.sax.ContentHandler ContentHandler}
039 *             interface, which includes Namespace support.
040 * @since SAX 1.0
041 * @author David Megginson
042 * @version 2.0.1 (sax2r2)
043 * @see org.xml.sax.Parser#setDocumentHandler
044 * @see org.xml.sax.Locator
045 * @see org.xml.sax.HandlerBase
046 */
047public interface DocumentHandler {
048
049
050    /**
051     * Receive an object for locating the origin of SAX document events.
052     *
053     * <p>SAX parsers are strongly encouraged (though not absolutely
054     * required) to supply a locator: if it does so, it must supply
055     * the locator to the application by invoking this method before
056     * invoking any of the other methods in the DocumentHandler
057     * interface.</p>
058     *
059     * <p>The locator allows the application to determine the end
060     * position of any document-related event, even if the parser is
061     * not reporting an error.  Typically, the application will
062     * use this information for reporting its own errors (such as
063     * character content that does not match an application's
064     * business rules).  The information returned by the locator
065     * is probably not sufficient for use with a search engine.</p>
066     *
067     * <p>Note that the locator will return correct information only
068     * during the invocation of the events in this interface.  The
069     * application should not attempt to use it at any other time.</p>
070     *
071     * @param locator An object that can return the location of
072     *                any SAX document event.
073     * @see org.xml.sax.Locator
074     */
075    public abstract void setDocumentLocator (Locator locator);
076
077
078    /**
079     * Receive notification of the beginning of a document.
080     *
081     * <p>The SAX parser will invoke this method only once, before any
082     * other methods in this interface or in DTDHandler (except for
083     * setDocumentLocator).</p>
084     *
085     * @exception org.xml.sax.SAXException Any SAX exception, possibly
086     *            wrapping another exception.
087     */
088    public abstract void startDocument ()
089        throws SAXException;
090
091
092    /**
093     * Receive notification of the end of a document.
094     *
095     * <p>The SAX parser will invoke this method only once, and it will
096     * be the last method invoked during the parse.  The parser shall
097     * not invoke this method until it has either abandoned parsing
098     * (because of an unrecoverable error) or reached the end of
099     * 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