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