unused/xml/sax/helpers/XMLFilterImpl.java

   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 $
   6
   7 package org.xml.sax.helpers;
   8
   9 import java.io.IOException;
  10
  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;
  24
  25
  26 /**
  27  * Base class for deriving an XML filter.
  28  *
  29  * <blockquote>
  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.
  34  * </blockquote>
  35  *
  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>
  42  *
  43  * @since SAX 2.0
  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
  52  */
  53 public class XMLFilterImpl
  54     implements XMLFilter, EntityResolver, DTDHandler, ContentHandler, ErrorHandler
  55 {
  56
  57 \f
  58     ////////////////////////////////////////////////////////////////////
  59     // Constructors.
  60     ////////////////////////////////////////////////////////////////////
  61
  62
  63     /**
  64      * Construct an empty XML filter, with no parent.
  65      *
  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>
  70      *
  71      * @see org.xml.sax.XMLReader#setFeature
  72      * @see org.xml.sax.XMLReader#setProperty
  73      * @see #setParent
  74      */
  75     public XMLFilterImpl ()
  76     {
  77         super();
  78     }
  79
  80
  81     /**
  82      * Construct an XML filter with the specified parent.
  83      *
  84      * @see #setParent
  85      * @see #getParent
  86      */
  87     public XMLFilterImpl (XMLReader parent)
  88     {
  89         super();
  90         setParent(parent);
  91     }
  92
  93
  94 \f
  95     ////////////////////////////////////////////////////////////////////
  96     // Implementation of org.xml.sax.XMLFilter.
  97     ////////////////////////////////////////////////////////////////////
  98
  99
 100     /**
 101      * Set the parent reader.
 102      *
 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>
 106      *
 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>
 109      *
 110      * @param parent The parent XML reader.
 111      * @see #getParent
 112      */
 113     @Override
 114                 public void setParent (XMLReader parent)
 115     {
 116         this.parent = parent;
 117     }
 118
 119
 120     /**
 121      * Get the parent reader.
 122      *
 123      * @return The parent XML reader, or null if none is set.
 124      * @see #setParent
 125      */
 126     @Override
 127                 public XMLReader getParent ()
 128     {
 129         return parent;
 130     }
 131
 132
 133 \f
 134     ////////////////////////////////////////////////////////////////////
 135     // Implementation of org.xml.sax.XMLReader.
 136     ////////////////////////////////////////////////////////////////////
 137
 138
 139     /**
 140      * Set the value of a feature.
 141      *
 142      * <p>This will always fail if the parent is null.</p>
 143      *
 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.
 151      */
 152     @Override
 153                 public void setFeature (String name, boolean value)
 154         throws SAXNotRecognizedException, SAXNotSupportedException
 155     {
 156         if (parent != null) {
 157             parent.setFeature(name, value);
 158         } else {
 159             throw new SAXNotRecognizedException("Feature: " + name);
 160         }
 161     }
 162
 163
 164     /**
 165      * Look up the value of a feature.
 166      *
 167      * <p>This will always fail if the parent is null.</p>
 168      *
 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.
 176      */
 177     @Override
 178                 public boolean getFeature (String name)
 179         throws SAXNotRecognizedException, SAXNotSupportedException
 180     {
 181         if (parent != null) {
 182             return parent.getFeature(name);
 183         } else {
 184             throw new SAXNotRecognizedException("Feature: " + name);
 185         }
 186     }
 187
 188
 189     /**
 190      * Set the value of a property.
 191      *
 192      * <p>This will always fail if the parent is null.</p>
 193      *
 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.
 201      */
 202     @Override
 203                 public void setProperty (String name, Object value)
 204         throws SAXNotRecognizedException, SAXNotSupportedException
 205     {
 206         if (parent != null) {
 207             parent.setProperty(name, value);
 208         } else {
 209             throw new SAXNotRecognizedException("Property: " + name);
 210         }
 211     }
 212
 213
 214     /**
 215      * Look up the value of a property.
 216      *
 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.
 224      */
 225     @Override
 226                 public Object getProperty (String name)
 227         throws SAXNotRecognizedException, SAXNotSupportedException
 228     {
 229         if (parent != null) {
 230             return parent.getProperty(name);
 231         } else {
 232             throw new SAXNotRecognizedException("Property: " + name);
 233         }
 234     }
 235
 236
 237     /**
 238      * Set the entity resolver.
 239      *
 240      * @param resolver The new entity resolver.
 241      */
 242     @Override
 243                 public void setEntityResolver (EntityResolver resolver)
 244     {
 245         entityResolver = resolver;
 246     }
 247
 248
 249     /**
 250      * Get the current entity resolver.
 251      *
 252      * @return The current entity resolver, or null if none was set.
 253      */
 254     @Override
 255                 public EntityResolver getEntityResolver ()
 256     {
 257         return entityResolver;
 258     }
 259
 260
 261     /**
 262      * Set the DTD event handler.
 263      *
 264      * @param handler the new DTD handler
 265      */
 266     @Override
 267                 public void setDTDHandler (DTDHandler handler)
 268     {
 269         dtdHandler = handler;
 270     }
 271
 272
 273     /**
 274      * Get the current DTD event handler.
 275      *
 276      * @return The current DTD handler, or null if none was set.
 277      */
 278     @Override
 279                 public DTDHandler getDTDHandler ()
 280     {
 281         return dtdHandler;
 282     }
 283
 284
 285     /**
 286      * Set the content event handler.
 287      *
 288      * @param handler the new content handler
 289      */
 290     @Override
 291                 public void setContentHandler (ContentHandler handler)
 292     {
 293         contentHandler = handler;
 294     }
 295
 296
 297     /**
 298      * Get the content event handler.
 299      *
 300      * @return The current content handler, or null if none was set.
 301      */
 302     @Override
 303                 public ContentHandler getContentHandler ()
 304     {
 305         return contentHandler;
 306     }
 307
 308
 309     /**
 310      * Set the error event handler.
 311      *
 312      * @param handler the new error handler
 313      */
 314     @Override
 315                 public void setErrorHandler (ErrorHandler handler)
 316     {
 317         errorHandler = handler;
 318     }
 319
 320
 321     /**
 322      * Get the current error event handler.
 323      *
 324      * @return The current error handler, or null if none was set.
 325      */
 326     @Override
 327                 public ErrorHandler getErrorHandler ()
 328     {
 329         return errorHandler;
 330     }
 331
 332
 333     /**
 334      * Parse a document.
 335      *
 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.
 342      */
 343     @Override
 344                 public void parse (InputSource input)
 345         throws SAXException, IOException
 346     {
 347         setupParse();
 348         parent.parse(input);
 349     }
 350
 351
 352     /**
 353      * Parse a document.
 354      *
 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.
 361      */
 362     @Override
 363                 public void parse (String systemId)
 364         throws SAXException, IOException
 365     {
 366         parse(new InputSource(systemId));
 367     }
 368
 369
 370 \f
 371     ////////////////////////////////////////////////////////////////////
 372     // Implementation of org.xml.sax.EntityResolver.
 373     ////////////////////////////////////////////////////////////////////
 374
 375
 376     /**
 377      * Filter an external entity resolution.
 378      *
 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
 386      *            new InputSource.
 387      */
 388     @Override
 389                 public InputSource resolveEntity (String publicId, String systemId)
 390         throws SAXException, IOException
 391     {
 392         if (entityResolver != null) {
 393             return entityResolver.resolveEntity(publicId, systemId);
 394         } else {
 395             return null;
 396         }
 397     }
 398
 399
 400 \f
 401     ////////////////////////////////////////////////////////////////////
 402     // Implementation of org.xml.sax.DTDHandler.
 403     ////////////////////////////////////////////////////////////////////
 404
 405
 406     /**
 407      * Filter a notation declaration event.
 408      *
 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.
 414      */
 415     @Override
 416                 public void notationDecl (String name, String publicId, String systemId)
 417         throws SAXException
 418     {
 419         if (dtdHandler != null) {
 420             dtdHandler.notationDecl(name, publicId, systemId);
 421         }
 422     }
 423
 424
 425     /**
 426      * Filter an unparsed entity declaration event.
 427      *
 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.
 434      */
 435     @Override
 436                 public void unparsedEntityDecl (String name, String publicId,
 437                                     String systemId, String notationName)
 438         throws SAXException
 439     {
 440         if (dtdHandler != null) {
 441             dtdHandler.unparsedEntityDecl(name, publicId, systemId,
 442                                           notationName);
 443         }
 444     }
 445
 446
 447 \f
 448     ////////////////////////////////////////////////////////////////////
 449     // Implementation of org.xml.sax.ContentHandler.
 450     ////////////////////////////////////////////////////////////////////
 451
 452
 453     /**
 454      * Filter a new document locator event.
 455      *
 456      * @param locator The document locator.
 457      */
 458     @Override
 459                 public void setDocumentLocator (Locator locator)
 460     {
 461         this.locator = locator;
 462         if (contentHandler != null) {
 463             contentHandler.setDocumentLocator(locator);
 464         }
 465     }
 466
 467
 468     /**
 469      * Filter a start document event.
 470      *
 471      * @exception org.xml.sax.SAXException The client may throw
 472      *            an exception during processing.
 473      */
 474     @Override
 475                 public void startDocument ()
 476         throws SAXException
 477     {
 478         if (contentHandler != null) {
 479             contentHandler.startDocument();
 480         }
 481     }
 482
 483
 484     /**
 485      * Filter an end document event.
 486      *
 487      * @exception org.xml.sax.SAXException The client may throw
 488      *            an exception during processing.
 489      */
 490     @Override
 491                 public void endDocument ()
 492         throws SAXException
 493     {
 494         if (contentHandler != null) {
 495             contentHandler.endDocument();
 496         }
 497     }
 498
 499
 500     /**
 501      * Filter a start Namespace prefix mapping event.
 502      *
 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.
 507      */
 508     @Override
 509                 public void startPrefixMapping (String prefix, String uri)
 510         throws SAXException
 511     {
 512         if (contentHandler != null) {
 513             contentHandler.startPrefixMapping(prefix, uri);
 514         }
 515     }
 516
 517
 518     /**
 519      * Filter an end Namespace prefix mapping event.
 520      *
 521      * @param prefix The Namespace prefix.
 522      * @exception org.xml.sax.SAXException The client may throw
 523      *            an exception during processing.
 524      */
 525     @Override
 526                 public void endPrefixMapping (String prefix)
 527         throws SAXException
 528     {
 529         if (contentHandler != null) {
 530             contentHandler.endPrefixMapping(prefix);
 531         }
 532     }
 533
 534
 535     /**
 536      * Filter a start element event.
 537      *
 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
 541      *        string.
 542      * @param atts The element's attributes.
 543      * @exception org.xml.sax.SAXException The client may throw
 544      *            an exception during processing.
 545      */
 546     @Override
 547                 public void startElement (String uri, String localName, String qName,
 548                               Attributes atts)
 549         throws SAXException
 550     {
 551         if (contentHandler != null) {
 552             contentHandler.startElement(uri, localName, qName, atts);
 553         }
 554     }
 555
 556
 557     /**
 558      * Filter an end element event.
 559      *
 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
 563      *        string.
 564      * @exception org.xml.sax.SAXException The client may throw
 565      *            an exception during processing.
 566      */
 567     @Override
 568                 public void endElement (String uri, String localName, String qName)
 569         throws SAXException
 570     {
 571         if (contentHandler != null) {
 572             contentHandler.endElement(uri, localName, qName);
 573         }
 574     }
 575
 576
 577     /**
 578      * Filter a character data event.
 579      *
 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.
 585      */
 586     @Override
 587                 public void characters (char ch[], int start, int length)
 588         throws SAXException
 589     {
 590         if (contentHandler != null) {
 591             contentHandler.characters(ch, start, length);
 592         }
 593     }
 594
 595
 596     /**
 597      * Filter an ignorable whitespace event.
 598      *
 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.
 604      */
 605     @Override
 606                 public void ignorableWhitespace (char ch[], int start, int length)
 607         throws SAXException
 608     {
 609         if (contentHandler != null) {
 610             contentHandler.ignorableWhitespace(ch, start, length);
 611         }
 612     }
 613
 614
 615     /**
 616      * Filter a processing instruction event.
 617      *
 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.
 622      */
 623     @Override
 624                 public void processingInstruction (String target, String data)
 625         throws SAXException
 626     {
 627         if (contentHandler != null) {
 628             contentHandler.processingInstruction(target, data);
 629         }
 630     }
 631
 632
 633     /**
 634      * Filter a skipped entity event.
 635      *
 636      * @param name The name of the skipped entity.
 637      * @exception org.xml.sax.SAXException The client may throw
 638      *            an exception during processing.
 639      */
 640     @Override
 641                 public void skippedEntity (String name)
 642         throws SAXException
 643     {
 644         if (contentHandler != null) {
 645             contentHandler.skippedEntity(name);
 646         }
 647     }
 648
 649
 650 \f
 651     ////////////////////////////////////////////////////////////////////
 652     // Implementation of org.xml.sax.ErrorHandler.
 653     ////////////////////////////////////////////////////////////////////
 654
 655
 656     /**
 657      * Filter a warning event.
 658      *
 659      * @param e The warning as an exception.
 660      * @exception org.xml.sax.SAXException The client may throw
 661      *            an exception during processing.
 662      */
 663     @Override
 664                 public void warning (SAXParseException e)
 665         throws SAXException
 666     {
 667         if (errorHandler != null) {
 668             errorHandler.warning(e);
 669         }
 670     }
 671
 672
 673     /**
 674      * Filter an error event.
 675      *
 676      * @param e The error as an exception.
 677      * @exception org.xml.sax.SAXException The client may throw
 678      *            an exception during processing.
 679      */
 680     @Override
 681                 public void error (SAXParseException e)
 682         throws SAXException
 683     {
 684         if (errorHandler != null) {
 685             errorHandler.error(e);
 686         }
 687     }
 688
 689
 690     /**
 691      * Filter a fatal error event.
 692      *
 693      * @param e The error as an exception.
 694      * @exception org.xml.sax.SAXException The client may throw
 695      *            an exception during processing.
 696      */
 697     @Override
 698                 public void fatalError (SAXParseException e)
 699         throws SAXException
 700     {
 701         if (errorHandler != null) {
 702             errorHandler.fatalError(e);
 703         }
 704     }
 705
 706
 707 \f
 708     ////////////////////////////////////////////////////////////////////
 709     // Internal methods.
 710     ////////////////////////////////////////////////////////////////////
 711
 712
 713     /**
 714      * Set up before a parse.
 715      *
 716      * <p>Before every parse, check whether the parent is
 717      * non-null, and re-register the filter for all of the
 718      * events.</p>
 719      */
 720     private void setupParse ()
 721     {
 722         if (parent == null) {
 723             throw new NullPointerException("No parent for filter");
 724         }
 725         parent.setEntityResolver(this);
 726         parent.setDTDHandler(this);
 727         parent.setContentHandler(this);
 728         parent.setErrorHandler(this);
 729     }
 730
 731
 732 \f
 733     ////////////////////////////////////////////////////////////////////
 734     // Internal state.
 735     ////////////////////////////////////////////////////////////////////
 736
 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;
 743
 744 }
 745
 746 // end of XMLFilterImpl.java