unused/xml/sax/helpers/XMLReaderAdapter.java

   1 // XMLReaderAdapter.java - adapt an SAX2 XMLReader to a SAX1 Parser
   2 // http://www.saxproject.org
   3 // Written by David Megginson
   4 // NO WARRANTY!  This class is in the public domain.
   5 // $Id: XMLReaderAdapter.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 import java.util.Locale;
  11
  12 import org.xml.sax.Parser;      // deprecated
  13 import org.xml.sax.Locator;
  14 import org.xml.sax.InputSource;
  15 import org.xml.sax.AttributeList; // deprecated
  16 import org.xml.sax.EntityResolver;
  17 import org.xml.sax.DTDHandler;
  18 import org.xml.sax.DocumentHandler; // deprecated
  19 import org.xml.sax.ErrorHandler;
  20 import org.xml.sax.SAXException;
  21
  22 import org.xml.sax.XMLReader;
  23 import org.xml.sax.Attributes;
  24 import org.xml.sax.ContentHandler;
  25 import org.xml.sax.SAXNotSupportedException;
  26
  27
  28 /**
  29  * Adapt a SAX2 XMLReader as a SAX1 Parser.
  30  *
  31  * <blockquote>
  32  * <em>This module, both source code and documentation, is in the
  33  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  34  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  35  * for further information.
  36  * </blockquote>
  37  *
  38  * <p>This class wraps a SAX2 {@link org.xml.sax.XMLReader XMLReader}
  39  * and makes it act as a SAX1 {@link org.xml.sax.Parser Parser}.  The XMLReader
  40  * must support a true value for the
  41  * http://xml.org/sax/features/namespace-prefixes property or parsing will fail
  42  * with a {@link org.xml.sax.SAXException SAXException}; if the XMLReader
  43  * supports a false value for the http://xml.org/sax/features/namespaces
  44  * property, that will also be used to improve efficiency.</p>
  45  *
  46  * @since SAX 2.0
  47  * @author David Megginson
  48  * @version 2.0.1 (sax2r2)
  49  * @see org.xml.sax.Parser
  50  * @see org.xml.sax.XMLReader
  51  */
  52 public class XMLReaderAdapter implements Parser, ContentHandler
  53 {
  54
  55 \f
  56     ////////////////////////////////////////////////////////////////////
  57     // Constructor.
  58     ////////////////////////////////////////////////////////////////////
  59
  60
  61     /**
  62      * Create a new adapter.
  63      *
  64      * <p>Use the "org.xml.sax.driver" property to locate the SAX2
  65      * driver to embed.</p>
  66      *
  67      * @exception org.xml.sax.SAXException If the embedded driver
  68      *            cannot be instantiated or if the
  69      *            org.xml.sax.driver property is not specified.
  70      */
  71     public XMLReaderAdapter ()
  72       throws SAXException
  73     {
  74         setup(XMLReaderFactory.createXMLReader());
  75     }
  76
  77
  78     /**
  79      * Create a new adapter.
  80      *
  81      * <p>Create a new adapter, wrapped around a SAX2 XMLReader.
  82      * The adapter will make the XMLReader act like a SAX1
  83      * Parser.</p>
  84      *
  85      * @param xmlReader The SAX2 XMLReader to wrap.
  86      * @exception java.lang.NullPointerException If the argument is null.
  87      */
  88     public XMLReaderAdapter (XMLReader xmlReader)
  89     {
  90         setup(xmlReader);
  91     }
  92
  93
  94
  95     /**
  96      * Internal setup.
  97      *
  98      * @param xmlReader The embedded XMLReader.
  99      */
 100     private void setup (XMLReader xmlReader)
 101     {
 102         if (xmlReader == null) {
 103             throw new NullPointerException("XMLReader must not be null");
 104         }
 105         this.xmlReader = xmlReader;
 106         qAtts = new AttributesAdapter();
 107     }
 108
 109
 110
 111     ////////////////////////////////////////////////////////////////////
 112     // Implementation of org.xml.sax.Parser.
 113     ////////////////////////////////////////////////////////////////////
 114
 115
 116     /**
 117      * Set the locale for error reporting.
 118      *
 119      * <p>This is not supported in SAX2, and will always throw
 120      * an exception.</p>
 121      *
 122      * @param locale the locale for error reporting.
 123      * @see org.xml.sax.Parser#setLocale
 124      * @exception org.xml.sax.SAXException Thrown unless overridden.
 125      */
 126     @Override
 127                 public void setLocale (Locale locale)
 128         throws SAXException
 129     {
 130         throw new SAXNotSupportedException("setLocale not supported");
 131     }
 132
 133
 134     /**
 135      * Register the entity resolver.
 136      *
 137      * @param resolver The new resolver.
 138      * @see org.xml.sax.Parser#setEntityResolver
 139      */
 140     @Override
 141                 public void setEntityResolver (EntityResolver resolver)
 142     {
 143         xmlReader.setEntityResolver(resolver);
 144     }
 145
 146
 147     /**
 148      * Register the DTD event handler.
 149      *
 150      * @param handler The new DTD event handler.
 151      * @see org.xml.sax.Parser#setDTDHandler
 152      */
 153     @Override
 154                 public void setDTDHandler (DTDHandler handler)
 155     {
 156         xmlReader.setDTDHandler(handler);
 157     }
 158
 159
 160     /**
 161      * Register the SAX1 document event handler.
 162      *
 163      * <p>Note that the SAX1 document handler has no Namespace
 164      * support.</p>
 165      *
 166      * @param handler The new SAX1 document event handler.
 167      * @see org.xml.sax.Parser#setDocumentHandler
 168      */
 169     @Override
 170                 public void setDocumentHandler (DocumentHandler handler)
 171     {
 172         documentHandler = handler;
 173     }
 174
 175
 176     /**
 177      * Register the error event handler.
 178      *
 179      * @param handler The new error event handler.
 180      * @see org.xml.sax.Parser#setErrorHandler
 181      */
 182     @Override
 183                 public void setErrorHandler (ErrorHandler handler)
 184     {
 185         xmlReader.setErrorHandler(handler);
 186     }
 187
 188
 189     /**
 190      * Parse the document.
 191      *
 192      * <p>This method will throw an exception if the embedded
 193      * XMLReader does not support the
 194      * http://xml.org/sax/features/namespace-prefixes property.</p>
 195      *
 196      * @param systemId The absolute URL of the document.
 197      * @exception java.io.IOException If there is a problem reading
 198      *            the raw content of the document.
 199      * @exception org.xml.sax.SAXException If there is a problem
 200      *            processing the document.
 201      * @see #parse(org.xml.sax.InputSource)
 202      * @see org.xml.sax.Parser#parse(java.lang.String)
 203      */
 204     @Override
 205                 public void parse (String systemId)
 206         throws IOException, SAXException
 207     {
 208         parse(new InputSource(systemId));
 209     }
 210
 211
 212     /**
 213      * Parse the document.
 214      *
 215      * <p>This method will throw an exception if the embedded
 216      * XMLReader does not support the
 217      * http://xml.org/sax/features/namespace-prefixes property.</p>
 218      *
 219      * @param input An input source for the document.
 220      * @exception java.io.IOException If there is a problem reading
 221      *            the raw content of the document.
 222      * @exception org.xml.sax.SAXException If there is a problem
 223      *            processing the document.
 224      * @see #parse(java.lang.String)
 225      * @see org.xml.sax.Parser#parse(org.xml.sax.InputSource)
 226      */
 227     @Override
 228                 public void parse (InputSource input)
 229         throws IOException, SAXException
 230     {
 231         setupXMLReader();
 232         xmlReader.parse(input);
 233     }
 234
 235
 236     /**
 237      * Set up the XML reader.
 238      */
 239     private void setupXMLReader ()
 240         throws SAXException
 241     {
 242         xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true);
 243         try {
 244             xmlReader.setFeature("http://xml.org/sax/features/namespaces",
 245                                  false);
 246         } catch (SAXException e) {
 247             // NO OP: it's just extra information, and we can ignore it
 248         }
 249         xmlReader.setContentHandler(this);
 250     }
 251
 252
 253 \f
 254     ////////////////////////////////////////////////////////////////////
 255     // Implementation of org.xml.sax.ContentHandler.
 256     ////////////////////////////////////////////////////////////////////
 257
 258
 259     /**
 260      * Set a document locator.
 261      *
 262      * @param locator The document locator.
 263      * @see org.xml.sax.ContentHandler#setDocumentLocator
 264      */
 265     @Override
 266                 public void setDocumentLocator (Locator locator)
 267     {
 268         if (documentHandler != null)
 269             documentHandler.setDocumentLocator(locator);
 270     }
 271
 272
 273     /**
 274      * Start document event.
 275      *
 276      * @exception org.xml.sax.SAXException The client may raise a
 277      *            processing exception.
 278      * @see org.xml.sax.ContentHandler#startDocument
 279      */
 280     @Override
 281                 public void startDocument ()
 282         throws SAXException
 283     {
 284         if (documentHandler != null)
 285             documentHandler.startDocument();
 286     }
 287
 288
 289     /**
 290      * End document event.
 291      *
 292      * @exception org.xml.sax.SAXException The client may raise a
 293      *            processing exception.
 294      * @see org.xml.sax.ContentHandler#endDocument
 295      */
 296     @Override
 297                 public void endDocument ()
 298         throws SAXException
 299     {
 300         if (documentHandler != null)
 301             documentHandler.endDocument();
 302     }
 303
 304
 305     /**
 306      * Adapt a SAX2 start prefix mapping event.
 307      *
 308      * @param prefix The prefix being mapped.
 309      * @param uri The Namespace URI being mapped to.
 310      * @see org.xml.sax.ContentHandler#startPrefixMapping
 311      */
 312     @Override
 313                 public void startPrefixMapping (String prefix, String uri)
 314     {
 315     }
 316
 317
 318     /**
 319      * Adapt a SAX2 end prefix mapping event.
 320      *
 321      * @param prefix The prefix being mapped.
 322      * @see org.xml.sax.ContentHandler#endPrefixMapping
 323      */
 324     @Override
 325                 public void endPrefixMapping (String prefix)
 326     {
 327     }
 328
 329
 330     /**
 331      * Adapt a SAX2 start element event.
 332      *
 333      * @param uri The Namespace URI.
 334      * @param localName The Namespace local name.
 335      * @param qName The qualified (prefixed) name.
 336      * @param atts The SAX2 attributes.
 337      * @exception org.xml.sax.SAXException The client may raise a
 338      *            processing exception.
 339      * @see org.xml.sax.ContentHandler#endDocument
 340      */
 341     @Override
 342                 public void startElement (String uri, String localName,
 343                               String qName, Attributes atts)
 344         throws SAXException
 345     {
 346         if (documentHandler != null) {
 347             qAtts.setAttributes(atts);
 348             documentHandler.startElement(qName, qAtts);
 349         }
 350     }
 351
 352
 353     /**
 354      * Adapt a SAX2 end element event.
 355      *
 356      * @param uri The Namespace URI.
 357      * @param localName The Namespace local name.
 358      * @param qName The qualified (prefixed) name.
 359      * @exception org.xml.sax.SAXException The client may raise a
 360      *            processing exception.
 361      * @see org.xml.sax.ContentHandler#endElement
 362      */
 363     @Override
 364                 public void endElement (String uri, String localName,
 365                             String qName)
 366         throws SAXException
 367     {
 368         if (documentHandler != null)
 369             documentHandler.endElement(qName);
 370     }
 371
 372
 373     /**
 374      * Adapt a SAX2 characters event.
 375      *
 376      * @param ch An array of characters.
 377      * @param start The starting position in the array.
 378      * @param length The number of characters to use.
 379      * @exception org.xml.sax.SAXException The client may raise a
 380      *            processing exception.
 381      * @see org.xml.sax.ContentHandler#characters
 382      */
 383     @Override
 384                 public void characters (char ch[], int start, int length)
 385         throws SAXException
 386     {
 387         if (documentHandler != null)
 388             documentHandler.characters(ch, start, length);
 389     }
 390
 391
 392     /**
 393      * Adapt a SAX2 ignorable whitespace event.
 394      *
 395      * @param ch An array of characters.
 396      * @param start The starting position in the array.
 397      * @param length The number of characters to use.
 398      * @exception org.xml.sax.SAXException The client may raise a
 399      *            processing exception.
 400      * @see org.xml.sax.ContentHandler#ignorableWhitespace
 401      */
 402     @Override
 403                 public void ignorableWhitespace (char ch[], int start, int length)
 404         throws SAXException
 405     {
 406         if (documentHandler != null)
 407             documentHandler.ignorableWhitespace(ch, start, length);
 408     }
 409
 410
 411     /**
 412      * Adapt a SAX2 processing instruction event.
 413      *
 414      * @param target The processing instruction target.
 415      * @param data The remainder of the processing instruction
 416      * @exception org.xml.sax.SAXException The client may raise a
 417      *            processing exception.
 418      * @see org.xml.sax.ContentHandler#processingInstruction
 419      */
 420     @Override
 421                 public void processingInstruction (String target, String data)
 422         throws SAXException
 423     {
 424         if (documentHandler != null)
 425             documentHandler.processingInstruction(target, data);
 426     }
 427
 428
 429     /**
 430      * Adapt a SAX2 skipped entity event.
 431      *
 432      * @param name The name of the skipped entity.
 433      * @see org.xml.sax.ContentHandler#skippedEntity
 434      * @exception org.xml.sax.SAXException Throwable by subclasses.
 435      */
 436     @Override
 437                 public void skippedEntity (String name)
 438         throws SAXException
 439     {
 440     }
 441
 442
 443 \f
 444     ////////////////////////////////////////////////////////////////////
 445     // Internal state.
 446     ////////////////////////////////////////////////////////////////////
 447
 448     XMLReader xmlReader;
 449     DocumentHandler documentHandler;
 450     AttributesAdapter qAtts;
 451
 452
 453 \f
 454     ////////////////////////////////////////////////////////////////////
 455     // Internal class.
 456     ////////////////////////////////////////////////////////////////////
 457
 458
 459     /**
 460      * Internal class to wrap a SAX2 Attributes object for SAX1.
 461      */
 462     final class AttributesAdapter implements AttributeList
 463     {
 464         AttributesAdapter ()
 465         {
 466         }
 467
 468
 469         /**
 470          * Set the embedded Attributes object.
 471          *
 472          * @param The embedded SAX2 Attributes.
 473          */
 474         void setAttributes (Attributes attributes)
 475         {
 476             this.attributes = attributes;
 477         }
 478
 479
 480         /**
 481          * Return the number of attributes.
 482          *
 483          * @return The length of the attribute list.
 484          * @see org.xml.sax.AttributeList#getLength
 485          */
 486         @Override
 487         public int getLength ()
 488         {
 489             return attributes.getLength();
 490         }
 491
 492
 493         /**
 494          * Return the qualified (prefixed) name of an attribute by position.
 495          *
 496          * @return The qualified name.
 497          * @see org.xml.sax.AttributeList#getName
 498          */
 499         @Override
 500         public String getName (int i)
 501         {
 502             return attributes.getQName(i);
 503         }
 504
 505
 506         /**
 507          * Return the type of an attribute by position.
 508          *
 509          * @return The type.
 510          * @see org.xml.sax.AttributeList#getType(int)
 511          */
 512         @Override
 513         public String getType (int i)
 514         {
 515             return attributes.getType(i);
 516         }
 517
 518
 519         /**
 520          * Return the value of an attribute by position.
 521          *
 522          * @return The value.
 523          * @see org.xml.sax.AttributeList#getValue(int)
 524          */
 525         @Override
 526         public String getValue (int i)
 527         {
 528             return attributes.getValue(i);
 529         }
 530
 531
 532         /**
 533          * Return the type of an attribute by qualified (prefixed) name.
 534          *
 535          * @return The type.
 536          * @see org.xml.sax.AttributeList#getType(java.lang.String)
 537          */
 538         @Override
 539         public String getType (String qName)
 540         {
 541             return attributes.getType(qName);
 542         }
 543
 544
 545         /**
 546          * Return the value of an attribute by qualified (prefixed) name.
 547          *
 548          * @return The value.
 549          * @see org.xml.sax.AttributeList#getValue(java.lang.String)
 550          */
 551         @Override
 552         public String getValue (String qName)
 553         {
 554             return attributes.getValue(qName);
 555         }
 556
 557         private Attributes attributes;
 558     }
 559
 560 }
 561
 562 // end of XMLReaderAdapter.java