001: /* Copyright 2000 - 2001 Quadcap Software. All rights reserved.
002: *
003: * This software is distributed under the Quadcap Free Software License.
004: * This software may be used or modified for any purpose, personal or
005: * commercial. Open Source redistributions are permitted. Commercial
006: * redistribution of larger works derived from, or works which bundle
007: * this software requires a "Commercial Redistribution License"; see
008: * http://www.quadcap.com/purchase.
009: *
010: * Redistributions qualify as "Open Source" under one of the following terms:
011: *
012: * Redistributions are made at no charge beyond the reasonable cost of
013: * materials and delivery.
014: *
015: * Redistributions are accompanied by a copy of the Source Code or by an
016: * irrevocable offer to provide a copy of the Source Code for up to three
017: * years at the cost of materials and delivery. Such redistributions
018: * must allow further use, modification, and redistribution of the Source
019: * Code under substantially the same terms as this license.
020: *
021: * Redistributions of source code must retain the copyright notices as they
022: * appear in each source code file, these license terms, and the
023: * disclaimer/limitation of liability set forth as paragraph 6 below.
024: *
025: * Redistributions in binary form must reproduce this Copyright Notice,
026: * these license terms, and the disclaimer/limitation of liability set
027: * forth as paragraph 6 below, in the documentation and/or other materials
028: * provided with the distribution.
029: *
030: * The Software is provided on an "AS IS" basis. No warranty is
031: * provided that the Software is free of defects, or fit for a
032: * particular purpose.
033: *
034: * Limitation of Liability. Quadcap Software shall not be liable
035: * for any damages suffered by the Licensee or any third party resulting
036: * from use of the Software.
037: */
038:
039: // SAX document handler.
040: // No warranty; no copyright -- use this as you will.
041: // $Id: DocumentHandler.java,v 1.3 2001/01/06 06:11:01 stan Exp $
042: package org.xml.sax;
043:
044: /**
045: * Receive notification of general document events.
046: *
047: * <p>This is the main interface that most SAX applications
048: * implement: if the application needs to be informed of basic parsing
049: * events, it implements this interface and registers an instance with
050: * the SAX parser using the setDocumentHandler method. The parser
051: * uses the instance to report basic document-related events like
052: * the start and end of elements and character data.</p>
053: *
054: * <p>The order of events in this interface is very important, and
055: * mirrors the order of information in the document itself. For
056: * example, all of an element's content (character data, processing
057: * instructions, and/or subelements) will appear, in order, between
058: * the startElement event and the corresponding endElement event.</p>
059: *
060: * <p>Application writers who do not want to implement the entire
061: * interface can derive a class from HandlerBase, which implements
062: * the default functionality; parser writers can instantiate
063: * HandlerBase to obtain a default handler. The application can find
064: * the location of any document event using the Locator interface
065: * supplied by the Parser through the setDocumentLocator method.</p>
066: *
067: * @author David Megginson (ak117@freenet.carleton.ca)
068: * @version 1.0
069: * @see org.xml.sax.Parser#setDocumentHandler
070: * @see org.xml.sax.Locator
071: * @see org.xml.sax.HandlerBase
072: */
073: public interface DocumentHandler {
074:
075: /**
076: * Receive an object for locating the origin of SAX document events.
077: *
078: * <p>SAX parsers are strongly encouraged (though not absolutely
079: * required) to supply a locator: if it does so, it must supply
080: * the locator to the application by invoking this method before
081: * invoking any of the other methods in the DocumentHandler
082: * interface.</p>
083: *
084: * <p>The locator allows the application to determine the end
085: * position of any document-related event, even if the parser is
086: * not reporting an error. Typically, the application will
087: * use this information for reporting its own errors (such as
088: * character content that does not match an application's
089: * business rules). The information returned by the locator
090: * is probably not sufficient for use with a search engine.</p>
091: *
092: * <p>Note that the locator will return correct information only
093: * during the invocation of the events in this interface. The
094: * application should not attempt to use it at any other time.</p>
095: *
096: * @param locator An object that can return the location of
097: * any SAX document event.
098: * @see org.xml.sax.Locator
099: */
100: public abstract void setDocumentLocator(Locator locator);
101:
102: /**
103: * Receive notification of the beginning of a document.
104: *
105: * <p>The SAX parser will invoke this method only once, before any
106: * other methods in this interface or in DTDHandler (except for
107: * setDocumentLocator).</p>
108: *
109: * @exception org.xml.sax.SAXException Any SAX exception, possibly
110: * wrapping another exception.
111: */
112: public abstract void startDocument() throws SAXException;
113:
114: /**
115: * Receive notification of the end of a document.
116: *
117: * <p>The SAX parser will invoke this method only once, and it will
118: * be the last method invoked during the parse. The parser shall
119: * not invoke this method until it has either abandoned parsing
120: * (because of an unrecoverable error) or reached the end of
121: * input.</p>
122: *
123: * @exception org.xml.sax.SAXException Any SAX exception, possibly
124: * wrapping another exception.
125: */
126: public abstract void endDocument() throws SAXException;
127:
128: /**
129: * Receive notification of the beginning of an element.
130: *
131: * <p>The Parser will invoke this method at the beginning of every
132: * element in the XML document; there will be a corresponding
133: * endElement() event for every startElement() event (even when the
134: * element is empty). All of the element's content will be
135: * reported, in order, before the corresponding endElement()
136: * event.</p>
137: *
138: * <p>If the element name has a namespace prefix, the prefix will
139: * still be attached. Note that the attribute list provided will
140: * contain only attributes with explicit values (specified or
141: * defaulted): #IMPLIED attributes will be omitted.</p>
142: *
143: * @param name The element type name.
144: * @param atts The attributes attached to the element, if any.
145: * @exception org.xml.sax.SAXException Any SAX exception, possibly
146: * wrapping another exception.
147: * @see #endElement
148: * @see org.xml.sax.AttributeList
149: */
150: public abstract void startElement(String name, AttributeList atts)
151: throws SAXException;
152:
153: /**
154: * Receive notification of the end of an element.
155: *
156: * <p>The SAX parser will invoke this method at the end of every
157: * element in the XML document; there will be a corresponding
158: * startElement() event for every endElement() event (even when the
159: * element is empty).</p>
160: *
161: * <p>If the element name has a namespace prefix, the prefix will
162: * still be attached to the name.</p>
163: *
164: * @param name The element type name
165: * @exception org.xml.sax.SAXException Any SAX exception, possibly
166: * wrapping another exception.
167: */
168: public abstract void endElement(String name) throws SAXException;
169:
170: /**
171: * Receive notification of character data.
172: *
173: * <p>The Parser will call this method to report each chunk of
174: * character data. SAX parsers may return all contiguous character
175: * data in a single chunk, or they may split it into several
176: * chunks; however, all of the characters in any single event
177: * must come from the same external entity, so that the Locator
178: * provides useful information.</p>
179: *
180: * <p>The application must not attempt to read from the array
181: * outside of the specified range.</p>
182: *
183: * <p>Note that some parsers will report whitespace using the
184: * ignorableWhitespace() method rather than this one (validating
185: * parsers must do so).</p>
186: *
187: * @param ch The characters from the XML document.
188: * @param start The start position in the array.
189: * @param length The number of characters to read from the array.
190: * @exception org.xml.sax.SAXException Any SAX exception, possibly
191: * wrapping another exception.
192: * @see #ignorableWhitespace
193: * @see org.xml.sax.Locator
194: */
195: public abstract void characters(char ch[], int start, int length)
196: throws SAXException;
197:
198: /**
199: * Receive notification of ignorable whitespace in element content.
200: *
201: * <p>Validating Parsers must use this method to report each chunk
202: * of ignorable whitespace (see the W3C XML 1.0 recommendation,
203: * section 2.10): non-validating parsers may also use this method
204: * if they are capable of parsing and using content models.</p>
205: *
206: * <p>SAX parsers may return all contiguous whitespace in a single
207: * chunk, or they may split it into several chunks; however, all of
208: * the characters in any single event must come from the same
209: * external entity, so that the Locator provides useful
210: * information.</p>
211: *
212: * <p>The application must not attempt to read from the array
213: * outside of the specified range.</p>
214: *
215: * @param ch The characters from the XML document.
216: * @param start The start position in the array.
217: * @param length The number of characters to read from the array.
218: * @exception org.xml.sax.SAXException Any SAX exception, possibly
219: * wrapping another exception.
220: * @see #characters
221: */
222: public abstract void ignorableWhitespace(char ch[], int start,
223: int length) throws SAXException;
224:
225: /**
226: * Receive notification of a processing instruction.
227: *
228: * <p>The Parser will invoke this method once for each processing
229: * instruction found: note that processing instructions may occur
230: * before or after the main document element.</p>
231: *
232: * <p>A SAX parser should never report an XML declaration (XML 1.0,
233: * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
234: * using this method.</p>
235: *
236: * @param target The processing instruction target.
237: * @param data The processing instruction data, or null if
238: * none was supplied.
239: * @exception org.xml.sax.SAXException Any SAX exception, possibly
240: * wrapping another exception.
241: */
242: public abstract void processingInstruction(String target,
243: String data) throws SAXException;
244:
245: }
|