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