001: // SAX default handler base class.
002: // No warranty; no copyright -- use this as you will.
003: // $Id$
004:
005: package org.xml.sax;
006:
007: /**
008: * Default base class for handlers.
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: * </blockquote>
014: *
015: * <p>This class implements the default behaviour for four SAX1
016: * interfaces: EntityResolver, DTDHandler, DocumentHandler,
017: * and ErrorHandler. It is now obsolete, but is included in SAX2 to
018: * support legacy SAX1 applications. SAX2 applications should use
019: * the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
020: * class instead.</p>
021: *
022: * <p>Application writers can extend this class when they need to
023: * implement only part of an interface; parser writers can
024: * instantiate this class to provide default handlers when the
025: * application has not supplied its own.</p>
026: *
027: * <p>Note that the use of this class is optional.</p>
028: *
029: * @deprecated This class works with the deprecated
030: * {@link org.xml.sax.DocumentHandler DocumentHandler}
031: * interface. It has been replaced by the SAX2
032: * {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
033: * class.
034: * @since SAX 1.0
035: * @author David Megginson,
036: * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
037: * @version 2.0
038: * @see org.xml.sax.EntityResolver
039: * @see org.xml.sax.DTDHandler
040: * @see org.xml.sax.DocumentHandler
041: * @see org.xml.sax.ErrorHandler
042: */
043: public class HandlerBase implements EntityResolver, DTDHandler,
044: DocumentHandler, ErrorHandler {
045:
046: ////////////////////////////////////////////////////////////////////
047: // Default implementation of the EntityResolver interface.
048: ////////////////////////////////////////////////////////////////////
049:
050: /**
051: * Resolve an external entity.
052: *
053: * <p>Always return null, so that the parser will use the system
054: * identifier provided in the XML document. This method implements
055: * the SAX default behaviour: application writers can override it
056: * in a subclass to do special translations such as catalog lookups
057: * or URI redirection.</p>
058: *
059: * @param publicId The public identifer, or null if none is
060: * available.
061: * @param systemId The system identifier provided in the XML
062: * document.
063: * @return The new input source, or null to require the
064: * default behaviour.
065: * @exception org.xml.sax.SAXException Any SAX exception, possibly
066: * wrapping another exception.
067: * @see org.xml.sax.EntityResolver#resolveEntity
068: */
069: public InputSource resolveEntity(String publicId, String systemId)
070: throws SAXException {
071: return null;
072: }
073:
074: ////////////////////////////////////////////////////////////////////
075: // Default implementation of DTDHandler interface.
076: ////////////////////////////////////////////////////////////////////
077:
078: /**
079: * Receive notification of a notation declaration.
080: *
081: * <p>By default, do nothing. Application writers may override this
082: * method in a subclass if they wish to keep track of the notations
083: * declared in a document.</p>
084: *
085: * @param name The notation name.
086: * @param publicId The notation public identifier, or null if not
087: * available.
088: * @param systemId The notation system identifier.
089: * @see org.xml.sax.DTDHandler#notationDecl
090: */
091: public void notationDecl(String name, String publicId,
092: String systemId) {
093: // no op
094: }
095:
096: /**
097: * Receive notification of an unparsed entity declaration.
098: *
099: * <p>By default, do nothing. Application writers may override this
100: * method in a subclass to keep track of the unparsed entities
101: * declared in a document.</p>
102: *
103: * @param name The entity name.
104: * @param publicId The entity public identifier, or null if not
105: * available.
106: * @param systemId The entity system identifier.
107: * @param notationName The name of the associated notation.
108: * @see org.xml.sax.DTDHandler#unparsedEntityDecl
109: */
110: public void unparsedEntityDecl(String name, String publicId,
111: String systemId, String notationName) {
112: // no op
113: }
114:
115: ////////////////////////////////////////////////////////////////////
116: // Default implementation of DocumentHandler interface.
117: ////////////////////////////////////////////////////////////////////
118:
119: /**
120: * Receive a Locator object for document events.
121: *
122: * <p>By default, do nothing. Application writers may override this
123: * method in a subclass if they wish to store the locator for use
124: * with other document events.</p>
125: *
126: * @param locator A locator for all SAX document events.
127: * @see org.xml.sax.DocumentHandler#setDocumentLocator
128: * @see org.xml.sax.Locator
129: */
130: public void setDocumentLocator(Locator locator) {
131: // no op
132: }
133:
134: /**
135: * Receive notification of the beginning of the document.
136: *
137: * <p>By default, do nothing. Application writers may override this
138: * method in a subclass to take specific actions at the beginning
139: * of a document (such as allocating the root node of a tree or
140: * creating an output file).</p>
141: *
142: * @exception org.xml.sax.SAXException Any SAX exception, possibly
143: * wrapping another exception.
144: * @see org.xml.sax.DocumentHandler#startDocument
145: */
146: public void startDocument() throws SAXException {
147: // no op
148: }
149:
150: /**
151: * Receive notification of the end of the document.
152: *
153: * <p>By default, do nothing. Application writers may override this
154: * method in a subclass to take specific actions at the beginning
155: * of a document (such as finalising a tree or closing an output
156: * file).</p>
157: *
158: * @exception org.xml.sax.SAXException Any SAX exception, possibly
159: * wrapping another exception.
160: * @see org.xml.sax.DocumentHandler#endDocument
161: */
162: public void endDocument() throws SAXException {
163: // no op
164: }
165:
166: /**
167: * Receive notification of the start of an element.
168: *
169: * <p>By default, do nothing. Application writers may override this
170: * method in a subclass to take specific actions at the start of
171: * each element (such as allocating a new tree node or writing
172: * output to a file).</p>
173: *
174: * @param name The element type name.
175: * @param attributes The specified or defaulted attributes.
176: * @exception org.xml.sax.SAXException Any SAX exception, possibly
177: * wrapping another exception.
178: * @see org.xml.sax.DocumentHandler#startElement
179: */
180: public void startElement(String name, AttributeList attributes)
181: throws SAXException {
182: // no op
183: }
184:
185: /**
186: * Receive notification of the end of an element.
187: *
188: * <p>By default, do nothing. Application writers may override this
189: * method in a subclass to take specific actions at the end of
190: * each element (such as finalising a tree node or writing
191: * output to a file).</p>
192: *
193: * @param name The element type name.
194: * @param attributes The specified or defaulted attributes.
195: * @exception org.xml.sax.SAXException Any SAX exception, possibly
196: * wrapping another exception.
197: * @see org.xml.sax.DocumentHandler#endElement
198: */
199: public void endElement(String name) throws SAXException {
200: // no op
201: }
202:
203: /**
204: * Receive notification of character data inside an element.
205: *
206: * <p>By default, do nothing. Application writers may override this
207: * method to take specific actions for each chunk of character data
208: * (such as adding the data to a node or buffer, or printing it to
209: * a file).</p>
210: *
211: * @param ch The characters.
212: * @param start The start position in the character array.
213: * @param length The number of characters to use from the
214: * character array.
215: * @exception org.xml.sax.SAXException Any SAX exception, possibly
216: * wrapping another exception.
217: * @see org.xml.sax.DocumentHandler#characters
218: */
219: public void characters(char ch[], int start, int length)
220: throws SAXException {
221: // no op
222: }
223:
224: /**
225: * Receive notification of ignorable whitespace in element content.
226: *
227: * <p>By default, do nothing. Application writers may override this
228: * method to take specific actions for each chunk of ignorable
229: * whitespace (such as adding data to a node or buffer, or printing
230: * it to a file).</p>
231: *
232: * @param ch The whitespace characters.
233: * @param start The start position in the character array.
234: * @param length The number of characters to use from the
235: * character array.
236: * @exception org.xml.sax.SAXException Any SAX exception, possibly
237: * wrapping another exception.
238: * @see org.xml.sax.DocumentHandler#ignorableWhitespace
239: */
240: public void ignorableWhitespace(char ch[], int start, int length)
241: throws SAXException {
242: // no op
243: }
244:
245: /**
246: * Receive notification of a processing instruction.
247: *
248: * <p>By default, do nothing. Application writers may override this
249: * method in a subclass to take specific actions for each
250: * processing instruction, such as setting status variables or
251: * invoking other methods.</p>
252: *
253: * @param target The processing instruction target.
254: * @param data The processing instruction data, or null if
255: * none is supplied.
256: * @exception org.xml.sax.SAXException Any SAX exception, possibly
257: * wrapping another exception.
258: * @see org.xml.sax.DocumentHandler#processingInstruction
259: */
260: public void processingInstruction(String target, String data)
261: throws SAXException {
262: // no op
263: }
264:
265: ////////////////////////////////////////////////////////////////////
266: // Default implementation of the ErrorHandler interface.
267: ////////////////////////////////////////////////////////////////////
268:
269: /**
270: * Receive notification of a parser warning.
271: *
272: * <p>The default implementation does nothing. Application writers
273: * may override this method in a subclass to take specific actions
274: * for each warning, such as inserting the message in a log file or
275: * printing it to the console.</p>
276: *
277: * @param e The warning information encoded as an exception.
278: * @exception org.xml.sax.SAXException Any SAX exception, possibly
279: * wrapping another exception.
280: * @see org.xml.sax.ErrorHandler#warning
281: * @see org.xml.sax.SAXParseException
282: */
283: public void warning(SAXParseException e) throws SAXException {
284: // no op
285: }
286:
287: /**
288: * Receive notification of a recoverable parser error.
289: *
290: * <p>The default implementation does nothing. Application writers
291: * may override this method in a subclass to take specific actions
292: * for each error, such as inserting the message in a log file or
293: * printing it to the console.</p>
294: *
295: * @param e The warning information encoded as an exception.
296: * @exception org.xml.sax.SAXException Any SAX exception, possibly
297: * wrapping another exception.
298: * @see org.xml.sax.ErrorHandler#warning
299: * @see org.xml.sax.SAXParseException
300: */
301: public void error(SAXParseException e) throws SAXException {
302: // no op
303: }
304:
305: /**
306: * Report a fatal XML parsing error.
307: *
308: * <p>The default implementation throws a SAXParseException.
309: * Application writers may override this method in a subclass if
310: * they need to take specific actions for each fatal error (such as
311: * collecting all of the errors into a single report): in any case,
312: * the application must stop all regular processing when this
313: * method is invoked, since the document is no longer reliable, and
314: * the parser may no longer report parsing events.</p>
315: *
316: * @param e The error information encoded as an exception.
317: * @exception org.xml.sax.SAXException Any SAX exception, possibly
318: * wrapping another exception.
319: * @see org.xml.sax.ErrorHandler#fatalError
320: * @see org.xml.sax.SAXParseException
321: */
322: public void fatalError(SAXParseException e) throws SAXException {
323: throw e;
324: }
325:
326: }
327:
328: // end of HandlerBase.java
|