001// SAX document handler.
002// No warranty; no copyright -- use this as you will.
003// $Id: DocumentHandler.java,v 1.1 2001/03/05 21:40:05 jstrachan Exp $
004
005package org.xml.sax;
006
007/**
008 * Receive notification of general document events.
009 *
010 * <blockquote>
011 * <em>This module, both source code and documentation, is in the
012 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
013 * </blockquote>
014 *
015 * <p>This was the main event-handling interface for SAX1; in
016 * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler
017 * ContentHandler}, which provides Namespace support and reporting
018 * of skipped entities.  This interface is included in SAX2 only
019 * to support legacy SAX1 applications.</p>
020 *
021 * <p>The order of events in this interface is very important, and
022 * mirrors the order of information in the document itself.  For
023 * example, all of an element's content (character data, processing
024 * instructions, and/or subelements) will appear, in order, between
025 * the startElement event and the corresponding endElement event.</p>
026 *
027 * <p>Application writers who do not want to implement the entire
028 * interface can derive a class from HandlerBase, which implements
029 * the default functionality; parser writers can instantiate
030 * HandlerBase to obtain a default handler.  The application can find
031 * the location of any document event using the Locator interface
032 * supplied by the Parser through the setDocumentLocator method.</p>
033 *
034 * @deprecated This interface has been replaced by the SAX2
035 *             {@link org.xml.sax.ContentHandler ContentHandler}
036 *             interface, which includes Namespace support.
037 * @since SAX 1.0
038 * @author David Megginson, 
039 *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>
040 * @version 2.0
041 * @see org.xml.sax.Parser#setDocumentHandler
042 * @see org.xml.sax.Locator
043 * @see org.xml.sax.HandlerBase
044 */
045public interface DocumentHandler {
046    
047    
048    /**
049     * Receive an object for locating the origin of SAX document events.
050     *
051     * <p>SAX parsers are strongly encouraged (though not absolutely
052     * required) to supply a locator: if it does so, it must supply
053     * the locator to the application by invoking this method before
054     * invoking any of the other methods in the DocumentHandler
055     * interface.</p>
056     *
057     * <p>The locator allows the application to determine the end
058     * position of any document-related event, even if the parser is
059     * not reporting an error.  Typically, the application will
060     * use this information for reporting its own errors (such as
061     * character content that does not match an application's
062     * business rules).  The information returned by the locator
063     * is probably not sufficient for use with a search engine.</p>
064     *
065     * <p>Note that the locator will return correct information only
066     * during the invocation of the events in this interface.  The
067     * application should not attempt to use it at any other time.</p>
068     *
069     * @param locator An object that can return the location of
070     *                any SAX document event.
071     * @see org.xml.sax.Locator
072     */
073    public abstract void setDocumentLocator (Locator locator);
074    
075    
076    /**
077     * Receive notification of the beginning of a document.
078     *
079     * <p>The SAX parser will invoke this method only once, before any
080     * other methods in this interface or in DTDHandler (except for
081     * setDocumentLocator).</p>
082     *
083     * @exception org.xml.sax.SAXException Any SAX exception, possibly
084     *            wrapping another exception.
085     */
086    public abstract void startDocument ()
087        throws SAXException;
088    
089    
090    /**
091     * Receive notification of the end of a document.
092     *
093     * <p>The SAX parser will invoke this method only once, and it will
094     * be the last method invoked during the parse.  The parser shall
095     * not invoke this method until it has either abandoned parsing
096     * (because of an unrecoverable error) or reached the end of
097     * input.</p>
098     *
099     * @exception org.xml.sax.SAXException Any SAX exception, possibly
100     *            wrapping another exception.
101     */
102    public abstract void endDocument ()
103        throws SAXException;
104    
105    
106    /**
107     * Receive notification of the beginning of an element.
108     *
109     * <p>The Parser will invoke this method at the beginning of every
110     * element in the XML document; there will be a corresponding
111     * endElement() event for every startElement() event (even when the
112     * element is empty). All of the element's content will be
113     * reported, in order, before the corresponding endElement()
114     * event.</p>
115     *
116     * <p>If the element name has a namespace prefix, the prefix will
117     * still be attached.  Note that the attribute list provided will
118     * contain only attributes with explicit values (specified or
119     * defaulted): #IMPLIED attributes will be omitted.</p>
120     *
121     * @param name The element type name.
122     * @param atts The attributes attached to the element, if any.
123     * @exception org.xml.sax.SAXException Any SAX exception, possibly
124     *            wrapping another exception.
125     * @see #endElement
126     * @see org.xml.sax.AttributeList 
127     */
128    public abstract void startElement (String name, AttributeList atts)
129        throws SAXException;
130    
131    
132    /**
133     * Receive notification of the end of an element.
134     *
135     * <p>The SAX parser will invoke this method at the end of every
136     * element in the XML document; there will be a corresponding
137     * startElement() event for every endElement() event (even when the
138     * element is empty).</p>
139     *
140     * <p>If the element name has a namespace prefix, the prefix will
141     * still be attached to the name.</p>
142     *
143     * @param name The element type name
144     * @exception org.xml.sax.SAXException Any SAX exception, possibly
145     *            wrapping another exception.
146     */
147    public abstract void endElement (String name)
148        throws SAXException;
149    
150    
151    /**
152     * Receive notification of character data.
153     *
154     * <p>The Parser will call this method to report each chunk of
155     * character data.  SAX parsers may return all contiguous character
156     * data in a single chunk, or they may split it into several
157     * chunks; however, all of the characters in any single event
158     * must come from the same external entity, so that the Locator
159     * provides useful information.</p>
160     *
161     * <p>The application must not attempt to read from the array
162     * outside of the specified range.</p>
163     *
164     * <p>Note that some parsers will report whitespace using the
165     * ignorableWhitespace() method rather than this one (validating
166     * parsers must do so).</p>
167     *
168     * @param ch The characters from the XML document.
169     * @param start The start position in the array.
170     * @param length The number of characters to read from the array.
171     * @exception org.xml.sax.SAXException Any SAX exception, possibly
172     *            wrapping another exception.
173     * @see #ignorableWhitespace 
174     * @see org.xml.sax.Locator
175     */
176    public abstract void characters (char ch[], int start, int length)
177        throws SAXException;
178    
179    
180    /**
181     * Receive notification of ignorable whitespace in element content.
182     *
183     * <p>Validating Parsers must use this method to report each chunk
184     * of ignorable whitespace (see the W3C XML 1.0 recommendation,
185     * section 2.10): non-validating parsers may also use this method
186     * if they are capable of parsing and using content models.</p>
187     *
188     * <p>SAX parsers may return all contiguous whitespace in a single
189     * chunk, or they may split it into several chunks; however, all of
190     * the characters in any single event must come from the same
191     * external entity, so that the Locator provides useful
192     * information.</p>
193     *
194     * <p>The application must not attempt to read from the array
195     * outside of the specified range.</p>
196     *
197     * @param ch The characters from the XML document.
198     * @param start The start position in the array.
199     * @param length The number of characters to read from the array.
200     * @exception org.xml.sax.SAXException Any SAX exception, possibly
201     *            wrapping another exception.
202     * @see #characters
203     */
204    public abstract void ignorableWhitespace (char ch[], int start, int length)
205        throws SAXException;
206    
207    
208    /**
209     * Receive notification of a processing instruction.
210     *
211     * <p>The Parser will invoke this method once for each processing
212     * instruction found: note that processing instructions may occur
213     * before or after the main document element.</p>
214     *
215     * <p>A SAX parser should never report an XML declaration (XML 1.0,
216     * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
217     * using this method.</p>
218     *
219     * @param target The processing instruction target.
220     * @param data The processing instruction data, or null if
221     *        none was supplied.
222     * @exception org.xml.sax.SAXException Any SAX exception, possibly
223     *            wrapping another exception.
224     */
225    public abstract void processingInstruction (String target, String data)
226        throws SAXException;
227    
228}
229
230// end of DocumentHandler.java