001: // ContentHandler.java - handle main document content.
002: // http://www.saxproject.org
003: // Written by David Megginson
004: // NO WARRANTY! This class is in the public domain.
005:
006: package org.xml.sax;
007:
008: /**
009: * Receive notification of the logical content of a document.
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 is the main interface that most SAX applications
019: * implement: if the application needs to be informed of basic parsing
020: * events, it implements this interface and registers an instance with
021: * the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler
022: * setContentHandler} method. The parser uses the instance to report
023: * basic document-related events like the start and end of elements
024: * and character data.</p>
025: *
026: * <p>The order of events in this interface is very important, and
027: * mirrors the order of information in the document itself. For
028: * example, all of an element's content (character data, processing
029: * instructions, and/or subelements) will appear, in order, between
030: * the startElement event and the corresponding endElement event.</p>
031: *
032: * <p>This interface is similar to the now-deprecated SAX 1.0
033: * DocumentHandler interface, but it adds support for Namespaces
034: * and for reporting skipped entities (in non-validating XML
035: * processors).</p>
036: *
037: * <p>Implementors should note that there is also a
038: * <code>ContentHandler</code> class in the <code>java.net</code>
039: * package; that means that it's probably a bad idea to do</p>
040: *
041: * <pre>import java.net.*;
042: * import org.xml.sax.*;
043: * </pre>
044: *
045: * <p>In fact, "import ...*" is usually a sign of sloppy programming
046: * anyway, so the user should consider this a feature rather than a
047: * bug.</p>
048: *
049: * @since SAX 2.0
050: * @author David Megginson
051: * @version 2.0.1+ (sax2r3pre1)
052: * @see org.xml.sax.XMLReader
053: * @see org.xml.sax.DTDHandler
054: * @see org.xml.sax.ErrorHandler
055: */
056: public interface ContentHandler {
057:
058: /**
059: * Receive an object for locating the origin of SAX document events.
060: *
061: * <p>SAX parsers are strongly encouraged (though not absolutely
062: * required) to supply a locator: if it does so, it must supply
063: * the locator to the application by invoking this method before
064: * invoking any of the other methods in the ContentHandler
065: * interface.</p>
066: *
067: * <p>The locator allows the application to determine the end
068: * position of any document-related event, even if the parser is
069: * not reporting an error. Typically, the application will
070: * use this information for reporting its own errors (such as
071: * character content that does not match an application's
072: * business rules). The information returned by the locator
073: * is probably not sufficient for use with a search engine.</p>
074: *
075: * <p>Note that the locator will return correct information only
076: * during the invocation SAX event callbacks after
077: * {@link #startDocument startDocument} returns and before
078: * {@link #endDocument endDocument} is called. The
079: * application should not attempt to use it at any other time.</p>
080: *
081: * @param locator an object that can return the location of
082: * any SAX document event
083: * @see org.xml.sax.Locator
084: */
085: public void setDocumentLocator(Locator locator);
086:
087: /**
088: * Receive notification of the beginning of a document.
089: *
090: * <p>The SAX parser will invoke this method only once, before any
091: * other event callbacks (except for {@link #setDocumentLocator
092: * setDocumentLocator}).</p>
093: *
094: * @throws org.xml.sax.SAXException any SAX exception, possibly
095: * wrapping another exception
096: * @see #endDocument
097: */
098: public void startDocument() throws SAXException;
099:
100: /**
101: * Receive notification of the end of a document.
102: *
103: * <p><strong>There is an apparent contradiction between the
104: * documentation for this method and the documentation for {@link
105: * org.xml.sax.ErrorHandler#fatalError}. Until this ambiguity is
106: * resolved in a future major release, clients should make no
107: * assumptions about whether endDocument() will or will not be
108: * invoked when the parser has reported a fatalError() or thrown
109: * an exception.</strong></p>
110: *
111: * <p>The SAX parser will invoke this method only once, and it will
112: * be the last method invoked during the parse. The parser shall
113: * not invoke this method until it has either abandoned parsing
114: * (because of an unrecoverable error) or reached the end of
115: * input.</p>
116: *
117: * @throws org.xml.sax.SAXException any SAX exception, possibly
118: * wrapping another exception
119: * @see #startDocument
120: */
121: public void endDocument() throws SAXException;
122:
123: /**
124: * Begin the scope of a prefix-URI Namespace mapping.
125: *
126: * <p>The information from this event is not necessary for
127: * normal Namespace processing: the SAX XML reader will
128: * automatically replace prefixes for element and attribute
129: * names when the <code>http://xml.org/sax/features/namespaces</code>
130: * feature is <var>true</var> (the default).</p>
131: *
132: * <p>There are cases, however, when applications need to
133: * use prefixes in character data or in attribute values,
134: * where they cannot safely be expanded automatically; the
135: * start/endPrefixMapping event supplies the information
136: * to the application to expand prefixes in those contexts
137: * itself, if necessary.</p>
138: *
139: * <p>Note that start/endPrefixMapping events are not
140: * guaranteed to be properly nested relative to each other:
141: * all startPrefixMapping events will occur immediately before the
142: * corresponding {@link #startElement startElement} event,
143: * and all {@link #endPrefixMapping endPrefixMapping}
144: * events will occur immediately after the corresponding
145: * {@link #endElement endElement} event,
146: * but their order is not otherwise
147: * guaranteed.</p>
148: *
149: * <p>There should never be start/endPrefixMapping events for the
150: * "xml" prefix, since it is predeclared and immutable.</p>
151: *
152: * @param prefix the Namespace prefix being declared.
153: * An empty string is used for the default element namespace,
154: * which has no prefix.
155: * @param uri the Namespace URI the prefix is mapped to
156: * @throws org.xml.sax.SAXException the client may throw
157: * an exception during processing
158: * @see #endPrefixMapping
159: * @see #startElement
160: */
161: public void startPrefixMapping(String prefix, String uri)
162: throws SAXException;
163:
164: /**
165: * End the scope of a prefix-URI mapping.
166: *
167: * <p>See {@link #startPrefixMapping startPrefixMapping} for
168: * details. These events will always occur immediately after the
169: * corresponding {@link #endElement endElement} event, but the order of
170: * {@link #endPrefixMapping endPrefixMapping} events is not otherwise
171: * guaranteed.</p>
172: *
173: * @param prefix the prefix that was being mapped.
174: * This is the empty string when a default mapping scope ends.
175: * @throws org.xml.sax.SAXException the client may throw
176: * an exception during processing
177: * @see #startPrefixMapping
178: * @see #endElement
179: */
180: public void endPrefixMapping(String prefix) throws SAXException;
181:
182: /**
183: * Receive notification of the beginning of an element.
184: *
185: * <p>The Parser will invoke this method at the beginning of every
186: * element in the XML document; there will be a corresponding
187: * {@link #endElement endElement} event for every startElement event
188: * (even when the element is empty). All of the element's content will be
189: * reported, in order, before the corresponding endElement
190: * event.</p>
191: *
192: * <p>This event allows up to three name components for each
193: * element:</p>
194: *
195: * <ol>
196: * <li>the Namespace URI;</li>
197: * <li>the local name; and</li>
198: * <li>the qualified (prefixed) name.</li>
199: * </ol>
200: *
201: * <p>Any or all of these may be provided, depending on the
202: * values of the <var>http://xml.org/sax/features/namespaces</var>
203: * and the <var>http://xml.org/sax/features/namespace-prefixes</var>
204: * properties:</p>
205: *
206: * <ul>
207: * <li>the Namespace URI and local name are required when
208: * the namespaces property is <var>true</var> (the default), and are
209: * optional when the namespaces property is <var>false</var> (if one is
210: * specified, both must be);</li>
211: * <li>the qualified name is required when the namespace-prefixes property
212: * is <var>true</var>, and is optional when the namespace-prefixes property
213: * is <var>false</var> (the default).</li>
214: * </ul>
215: *
216: * <p>Note that the attribute list provided will contain only
217: * attributes with explicit values (specified or defaulted):
218: * #IMPLIED attributes will be omitted. The attribute list
219: * will contain attributes used for Namespace declarations
220: * (xmlns* attributes) only if the
221: * <code>http://xml.org/sax/features/namespace-prefixes</code>
222: * property is true (it is false by default, and support for a
223: * true value is optional).</p>
224: *
225: * <p>Like {@link #characters characters()}, attribute values may have
226: * characters that need more than one <code>char</code> value. </p>
227: *
228: * @param uri the Namespace URI, or the empty string if the
229: * element has no Namespace URI or if Namespace
230: * processing is not being performed
231: * @param localName the local name (without prefix), or the
232: * empty string if Namespace processing is not being
233: * performed
234: * @param qName the qualified name (with prefix), or the
235: * empty string if qualified names are not available
236: * @param atts the attributes attached to the element. If
237: * there are no attributes, it shall be an empty
238: * Attributes object. The value of this object after
239: * startElement returns is undefined
240: * @throws org.xml.sax.SAXException any SAX exception, possibly
241: * wrapping another exception
242: * @see #endElement
243: * @see org.xml.sax.Attributes
244: * @see org.xml.sax.helpers.SaxAttributes
245: */
246: public void startElement(String uri, String localName,
247: String qName, Attributes atts) throws SAXException;
248:
249: /**
250: * Receive notification of the end of an element.
251: *
252: * <p>The SAX parser will invoke this method at the end of every
253: * element in the XML document; there will be a corresponding
254: * {@link #startElement startElement} event for every endElement
255: * event (even when the element is empty).</p>
256: *
257: * <p>For information on the names, see startElement.</p>
258: *
259: * @param uri the Namespace URI, or the empty string if the
260: * element has no Namespace URI or if Namespace
261: * processing is not being performed
262: * @param localName the local name (without prefix), or the
263: * empty string if Namespace processing is not being
264: * performed
265: * @param qName the qualified XML name (with prefix), or the
266: * empty string if qualified names are not available
267: * @throws org.xml.sax.SAXException any SAX exception, possibly
268: * wrapping another exception
269: */
270: public void endElement(String uri, String localName, String qName)
271: throws SAXException;
272:
273: /**
274: * Receive notification of character data.
275: *
276: * <p>The Parser will call this method to report each chunk of
277: * character data. SAX parsers may return all contiguous character
278: * data in a single chunk, or they may split it into several
279: * chunks; however, all of the characters in any single event
280: * must come from the same external entity so that the Locator
281: * provides useful information.</p>
282: *
283: * <p>The application must not attempt to read from the array
284: * outside of the specified range.</p>
285: *
286: * <p>Individual characters may consist of more than one Java
287: * <code>char</code> value. There are two important cases where this
288: * happens, because characters can't be represented in just sixteen bits.
289: * In one case, characters are represented in a <em>Surrogate Pair</em>,
290: * using two special Unicode values. Such characters are in the so-called
291: * "Astral Planes", with a code point above U+FFFF. A second case involves
292: * composite characters, such as a base character combining with one or
293: * more accent characters. </p>
294: *
295: * <p> Your code should not assume that algorithms using
296: * <code>char</code>-at-a-time idioms will be working in character
297: * units; in some cases they will split characters. This is relevant
298: * wherever XML permits arbitrary characters, such as attribute values,
299: * processing instruction data, and comments as well as in data reported
300: * from this method. It's also generally relevant whenever Java code
301: * manipulates internationalized text; the issue isn't unique to XML.</p>
302: *
303: * <p>Note that some parsers will report whitespace in element
304: * content using the {@link #ignorableWhitespace ignorableWhitespace}
305: * method rather than this one (validating parsers <em>must</em>
306: * do so).</p>
307: *
308: * @param ch the characters from the XML document
309: * @param start the start position in the array
310: * @param length the number of characters to read from the array
311: * @throws org.xml.sax.SAXException any SAX exception, possibly
312: * wrapping another exception
313: * @see #ignorableWhitespace
314: * @see org.xml.sax.Locator
315: */
316: public void characters(char ch[], int start, int length)
317: throws SAXException;
318:
319: /**
320: * Receive notification of ignorable whitespace in element content.
321: *
322: * <p>Validating Parsers must use this method to report each chunk
323: * of whitespace in element content (see the W3C XML 1.0
324: * recommendation, section 2.10): non-validating parsers may also
325: * use this method if they are capable of parsing and using
326: * content models.</p>
327: *
328: * <p>SAX parsers may return all contiguous whitespace in a single
329: * chunk, or they may split it into several chunks; however, all of
330: * the characters in any single event must come from the same
331: * external entity, so that the Locator provides useful
332: * information.</p>
333: *
334: * <p>The application must not attempt to read from the array
335: * outside of the specified range.</p>
336: *
337: * @param ch the characters from the XML document
338: * @param start the start position in the array
339: * @param length the number of characters to read from the array
340: * @throws org.xml.sax.SAXException any SAX exception, possibly
341: * wrapping another exception
342: * @see #characters
343: */
344: public void ignorableWhitespace(char ch[], int start, int length)
345: throws SAXException;
346:
347: /**
348: * Receive notification of a processing instruction.
349: *
350: * <p>The Parser will invoke this method once for each processing
351: * instruction found: note that processing instructions may occur
352: * before or after the main document element.</p>
353: *
354: * <p>A SAX parser must never report an XML declaration (XML 1.0,
355: * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
356: * using this method.</p>
357: *
358: * <p>Like {@link #characters characters()}, processing instruction
359: * data may have characters that need more than one <code>char</code>
360: * value. </p>
361: *
362: * @param target the processing instruction target
363: * @param data the processing instruction data, or null if
364: * none was supplied. The data does not include any
365: * whitespace separating it from the target
366: * @throws org.xml.sax.SAXException any SAX exception, possibly
367: * wrapping another exception
368: */
369: public void processingInstruction(String target, String data)
370: throws SAXException;
371:
372: /**
373: * Receive notification of a skipped entity.
374: * This is not called for entity references within markup constructs
375: * such as element start tags or markup declarations. (The XML
376: * recommendation requires reporting skipped external entities.
377: * SAX also reports internal entity expansion/non-expansion, except
378: * within markup constructs.)
379: *
380: * <p>The Parser will invoke this method each time the entity is
381: * skipped. Non-validating processors may skip entities if they
382: * have not seen the declarations (because, for example, the
383: * entity was declared in an external DTD subset). All processors
384: * may skip external entities, depending on the values of the
385: * <code>http://xml.org/sax/features/external-general-entities</code>
386: * and the
387: * <code>http://xml.org/sax/features/external-parameter-entities</code>
388: * properties.</p>
389: *
390: * @param name the name of the skipped entity. If it is a
391: * parameter entity, the name will begin with '%', and if
392: * it is the external DTD subset, it will be the string
393: * "[dtd]"
394: * @throws org.xml.sax.SAXException any SAX exception, possibly
395: * wrapping another exception
396: */
397: public void skippedEntity(String name) throws SAXException;
398: }
399:
400: // end of ContentHandler.java
|