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