1 // XMLFilterImpl.java - base SAX2 filter implementation.
2 // http://www.saxproject.org
3 // Written by David Megginson
4 // NO WARRANTY! This class is in the Public Domain.
5 // $Id: XMLFilterImpl.java,v 1.9 2004/04/26 17:34:35 dmegginson Exp $
7 package org.xml.sax.helpers;
9 import java.io.IOException;
11 import org.xml.sax.XMLReader;
12 import org.xml.sax.XMLFilter;
13 import org.xml.sax.InputSource;
14 import org.xml.sax.Locator;
15 import org.xml.sax.Attributes;
16 import org.xml.sax.EntityResolver;
17 import org.xml.sax.DTDHandler;
18 import org.xml.sax.ContentHandler;
19 import org.xml.sax.ErrorHandler;
20 import org.xml.sax.SAXException;
21 import org.xml.sax.SAXParseException;
22 import org.xml.sax.SAXNotSupportedException;
23 import org.xml.sax.SAXNotRecognizedException;
27 * Base class for deriving an XML filter.
30 * <em>This module, both source code and documentation, is in the
31 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
32 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
33 * for further information.
36 * <p>This class is designed to sit between an {@link org.xml.sax.XMLReader
37 * XMLReader} and the client application's event handlers. By default, it
38 * does nothing but pass requests up to the reader and events
39 * on to the handlers unmodified, but subclasses can override
40 * specific methods to modify the event stream or the configuration
41 * requests as they pass through.</p>
44 * @author David Megginson
45 * @version 2.0.1 (sax2r2)
46 * @see org.xml.sax.XMLFilter
47 * @see org.xml.sax.XMLReader
48 * @see org.xml.sax.EntityResolver
49 * @see org.xml.sax.DTDHandler
50 * @see org.xml.sax.ContentHandler
51 * @see org.xml.sax.ErrorHandler
53 public class XMLFilterImpl
54 implements XMLFilter, EntityResolver, DTDHandler, ContentHandler, ErrorHandler
58 ////////////////////////////////////////////////////////////////////
60 ////////////////////////////////////////////////////////////////////
64 * Construct an empty XML filter, with no parent.
66 * <p>This filter will have no parent: you must assign a parent
67 * before you start a parse or do any configuration with
68 * setFeature or setProperty, unless you use this as a pure event
69 * consumer rather than as an {@link XMLReader}.</p>
71 * @see org.xml.sax.XMLReader#setFeature
72 * @see org.xml.sax.XMLReader#setProperty
75 public XMLFilterImpl ()
82 * Construct an XML filter with the specified parent.
87 public XMLFilterImpl (XMLReader parent)
95 ////////////////////////////////////////////////////////////////////
96 // Implementation of org.xml.sax.XMLFilter.
97 ////////////////////////////////////////////////////////////////////
101 * Set the parent reader.
103 * <p>This is the {@link org.xml.sax.XMLReader XMLReader} from which
104 * this filter will obtain its events and to which it will pass its
105 * configuration requests. The parent may itself be another filter.</p>
107 * <p>If there is no parent reader set, any attempt to parse
108 * or to set or get a feature or property will fail.</p>
110 * @param parent The parent XML reader.
114 public void setParent (XMLReader parent)
116 this.parent = parent;
121 * Get the parent reader.
123 * @return The parent XML reader, or null if none is set.
127 public XMLReader getParent ()
134 ////////////////////////////////////////////////////////////////////
135 // Implementation of org.xml.sax.XMLReader.
136 ////////////////////////////////////////////////////////////////////
140 * Set the value of a feature.
142 * <p>This will always fail if the parent is null.</p>
144 * @param name The feature name.
145 * @param value The requested feature value.
146 * @exception org.xml.sax.SAXNotRecognizedException If the feature
147 * value can't be assigned or retrieved from the parent.
148 * @exception org.xml.sax.SAXNotSupportedException When the
149 * parent recognizes the feature name but
150 * cannot set the requested value.
153 public void setFeature (String name, boolean value)
154 throws SAXNotRecognizedException, SAXNotSupportedException
156 if (parent != null) {
157 parent.setFeature(name, value);
159 throw new SAXNotRecognizedException("Feature: " + name);
165 * Look up the value of a feature.
167 * <p>This will always fail if the parent is null.</p>
169 * @param name The feature name.
170 * @return The current value of the feature.
171 * @exception org.xml.sax.SAXNotRecognizedException If the feature
172 * value can't be assigned or retrieved from the parent.
173 * @exception org.xml.sax.SAXNotSupportedException When the
174 * parent recognizes the feature name but
175 * cannot determine its value at this time.
178 public boolean getFeature (String name)
179 throws SAXNotRecognizedException, SAXNotSupportedException
181 if (parent != null) {
182 return parent.getFeature(name);
184 throw new SAXNotRecognizedException("Feature: " + name);
190 * Set the value of a property.
192 * <p>This will always fail if the parent is null.</p>
194 * @param name The property name.
195 * @param value The requested property value.
196 * @exception org.xml.sax.SAXNotRecognizedException If the property
197 * value can't be assigned or retrieved from the parent.
198 * @exception org.xml.sax.SAXNotSupportedException When the
199 * parent recognizes the property name but
200 * cannot set the requested value.
203 public void setProperty (String name, Object value)
204 throws SAXNotRecognizedException, SAXNotSupportedException
206 if (parent != null) {
207 parent.setProperty(name, value);
209 throw new SAXNotRecognizedException("Property: " + name);
215 * Look up the value of a property.
217 * @param name The property name.
218 * @return The current value of the property.
219 * @exception org.xml.sax.SAXNotRecognizedException If the property
220 * value can't be assigned or retrieved from the parent.
221 * @exception org.xml.sax.SAXNotSupportedException When the
222 * parent recognizes the property name but
223 * cannot determine its value at this time.
226 public Object getProperty (String name)
227 throws SAXNotRecognizedException, SAXNotSupportedException
229 if (parent != null) {
230 return parent.getProperty(name);
232 throw new SAXNotRecognizedException("Property: " + name);
238 * Set the entity resolver.
240 * @param resolver The new entity resolver.
243 public void setEntityResolver (EntityResolver resolver)
245 entityResolver = resolver;
250 * Get the current entity resolver.
252 * @return The current entity resolver, or null if none was set.
255 public EntityResolver getEntityResolver ()
257 return entityResolver;
262 * Set the DTD event handler.
264 * @param handler the new DTD handler
267 public void setDTDHandler (DTDHandler handler)
269 dtdHandler = handler;
274 * Get the current DTD event handler.
276 * @return The current DTD handler, or null if none was set.
279 public DTDHandler getDTDHandler ()
286 * Set the content event handler.
288 * @param handler the new content handler
291 public void setContentHandler (ContentHandler handler)
293 contentHandler = handler;
298 * Get the content event handler.
300 * @return The current content handler, or null if none was set.
303 public ContentHandler getContentHandler ()
305 return contentHandler;
310 * Set the error event handler.
312 * @param handler the new error handler
315 public void setErrorHandler (ErrorHandler handler)
317 errorHandler = handler;
322 * Get the current error event handler.
324 * @return The current error handler, or null if none was set.
327 public ErrorHandler getErrorHandler ()
336 * @param input The input source for the document entity.
337 * @exception org.xml.sax.SAXException Any SAX exception, possibly
338 * wrapping another exception.
339 * @exception java.io.IOException An IO exception from the parser,
340 * possibly from a byte stream or character stream
341 * supplied by the application.
344 public void parse (InputSource input)
345 throws SAXException, IOException
355 * @param systemId The system identifier as a fully-qualified URI.
356 * @exception org.xml.sax.SAXException Any SAX exception, possibly
357 * wrapping another exception.
358 * @exception java.io.IOException An IO exception from the parser,
359 * possibly from a byte stream or character stream
360 * supplied by the application.
363 public void parse (String systemId)
364 throws SAXException, IOException
366 parse(new InputSource(systemId));
371 ////////////////////////////////////////////////////////////////////
372 // Implementation of org.xml.sax.EntityResolver.
373 ////////////////////////////////////////////////////////////////////
377 * Filter an external entity resolution.
379 * @param publicId The entity's public identifier, or null.
380 * @param systemId The entity's system identifier.
381 * @return A new InputSource or null for the default.
382 * @exception org.xml.sax.SAXException The client may throw
383 * an exception during processing.
384 * @exception java.io.IOException The client may throw an
385 * I/O-related exception while obtaining the
389 public InputSource resolveEntity (String publicId, String systemId)
390 throws SAXException, IOException
392 if (entityResolver != null) {
393 return entityResolver.resolveEntity(publicId, systemId);
401 ////////////////////////////////////////////////////////////////////
402 // Implementation of org.xml.sax.DTDHandler.
403 ////////////////////////////////////////////////////////////////////
407 * Filter a notation declaration event.
409 * @param name The notation name.
410 * @param publicId The notation's public identifier, or null.
411 * @param systemId The notation's system identifier, or null.
412 * @exception org.xml.sax.SAXException The client may throw
413 * an exception during processing.
416 public void notationDecl (String name, String publicId, String systemId)
419 if (dtdHandler != null) {
420 dtdHandler.notationDecl(name, publicId, systemId);
426 * Filter an unparsed entity declaration event.
428 * @param name The entity name.
429 * @param publicId The entity's public identifier, or null.
430 * @param systemId The entity's system identifier, or null.
431 * @param notationName The name of the associated notation.
432 * @exception org.xml.sax.SAXException The client may throw
433 * an exception during processing.
436 public void unparsedEntityDecl (String name, String publicId,
437 String systemId, String notationName)
440 if (dtdHandler != null) {
441 dtdHandler.unparsedEntityDecl(name, publicId, systemId,
448 ////////////////////////////////////////////////////////////////////
449 // Implementation of org.xml.sax.ContentHandler.
450 ////////////////////////////////////////////////////////////////////
454 * Filter a new document locator event.
456 * @param locator The document locator.
459 public void setDocumentLocator (Locator locator)
461 this.locator = locator;
462 if (contentHandler != null) {
463 contentHandler.setDocumentLocator(locator);
469 * Filter a start document event.
471 * @exception org.xml.sax.SAXException The client may throw
472 * an exception during processing.
475 public void startDocument ()
478 if (contentHandler != null) {
479 contentHandler.startDocument();
485 * Filter an end document event.
487 * @exception org.xml.sax.SAXException The client may throw
488 * an exception during processing.
491 public void endDocument ()
494 if (contentHandler != null) {
495 contentHandler.endDocument();
501 * Filter a start Namespace prefix mapping event.
503 * @param prefix The Namespace prefix.
504 * @param uri The Namespace URI.
505 * @exception org.xml.sax.SAXException The client may throw
506 * an exception during processing.
509 public void startPrefixMapping (String prefix, String uri)
512 if (contentHandler != null) {
513 contentHandler.startPrefixMapping(prefix, uri);
519 * Filter an end Namespace prefix mapping event.
521 * @param prefix The Namespace prefix.
522 * @exception org.xml.sax.SAXException The client may throw
523 * an exception during processing.
526 public void endPrefixMapping (String prefix)
529 if (contentHandler != null) {
530 contentHandler.endPrefixMapping(prefix);
536 * Filter a start element event.
538 * @param uri The element's Namespace URI, or the empty string.
539 * @param localName The element's local name, or the empty string.
540 * @param qName The element's qualified (prefixed) name, or the empty
542 * @param atts The element's attributes.
543 * @exception org.xml.sax.SAXException The client may throw
544 * an exception during processing.
547 public void startElement (String uri, String localName, String qName,
551 if (contentHandler != null) {
552 contentHandler.startElement(uri, localName, qName, atts);
558 * Filter an end element event.
560 * @param uri The element's Namespace URI, or the empty string.
561 * @param localName The element's local name, or the empty string.
562 * @param qName The element's qualified (prefixed) name, or the empty
564 * @exception org.xml.sax.SAXException The client may throw
565 * an exception during processing.
568 public void endElement (String uri, String localName, String qName)
571 if (contentHandler != null) {
572 contentHandler.endElement(uri, localName, qName);
578 * Filter a character data event.
580 * @param ch An array of characters.
581 * @param start The starting position in the array.
582 * @param length The number of characters to use from the array.
583 * @exception org.xml.sax.SAXException The client may throw
584 * an exception during processing.
587 public void characters (char ch[], int start, int length)
590 if (contentHandler != null) {
591 contentHandler.characters(ch, start, length);
597 * Filter an ignorable whitespace event.
599 * @param ch An array of characters.
600 * @param start The starting position in the array.
601 * @param length The number of characters to use from the array.
602 * @exception org.xml.sax.SAXException The client may throw
603 * an exception during processing.
606 public void ignorableWhitespace (char ch[], int start, int length)
609 if (contentHandler != null) {
610 contentHandler.ignorableWhitespace(ch, start, length);
616 * Filter a processing instruction event.
618 * @param target The processing instruction target.
619 * @param data The text following the target.
620 * @exception org.xml.sax.SAXException The client may throw
621 * an exception during processing.
624 public void processingInstruction (String target, String data)
627 if (contentHandler != null) {
628 contentHandler.processingInstruction(target, data);
634 * Filter a skipped entity event.
636 * @param name The name of the skipped entity.
637 * @exception org.xml.sax.SAXException The client may throw
638 * an exception during processing.
641 public void skippedEntity (String name)
644 if (contentHandler != null) {
645 contentHandler.skippedEntity(name);
651 ////////////////////////////////////////////////////////////////////
652 // Implementation of org.xml.sax.ErrorHandler.
653 ////////////////////////////////////////////////////////////////////
657 * Filter a warning event.
659 * @param e The warning as an exception.
660 * @exception org.xml.sax.SAXException The client may throw
661 * an exception during processing.
664 public void warning (SAXParseException e)
667 if (errorHandler != null) {
668 errorHandler.warning(e);
674 * Filter an error event.
676 * @param e The error as an exception.
677 * @exception org.xml.sax.SAXException The client may throw
678 * an exception during processing.
681 public void error (SAXParseException e)
684 if (errorHandler != null) {
685 errorHandler.error(e);
691 * Filter a fatal error event.
693 * @param e The error as an exception.
694 * @exception org.xml.sax.SAXException The client may throw
695 * an exception during processing.
698 public void fatalError (SAXParseException e)
701 if (errorHandler != null) {
702 errorHandler.fatalError(e);
708 ////////////////////////////////////////////////////////////////////
710 ////////////////////////////////////////////////////////////////////
714 * Set up before a parse.
716 * <p>Before every parse, check whether the parent is
717 * non-null, and re-register the filter for all of the
720 private void setupParse ()
722 if (parent == null) {
723 throw new NullPointerException("No parent for filter");
725 parent.setEntityResolver(this);
726 parent.setDTDHandler(this);
727 parent.setContentHandler(this);
728 parent.setErrorHandler(this);
733 ////////////////////////////////////////////////////////////////////
735 ////////////////////////////////////////////////////////////////////
737 private XMLReader parent = null;
738 private Locator locator = null;
739 private EntityResolver entityResolver = null;
740 private DTDHandler dtdHandler = null;
741 private ContentHandler contentHandler = null;
742 private ErrorHandler errorHandler = null;
746 // end of XMLFilterImpl.java