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