KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xml > sax > 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 JavaDoc 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 JavaDoc;
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 JavaDoc;
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 JavaDoc name, AttributeList JavaDoc atts)
131     throws SAXException JavaDoc;
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 JavaDoc name)
150     throws SAXException JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc target, String JavaDoc data)
228     throws SAXException JavaDoc;
229     
230 }
231
232 // end of DocumentHandler.java
233
Popular Tags