tribble.xml.impl
Class XmlReader

java.lang.Object
  extended bytribble.xml.impl.XmlReader
All Implemented Interfaces:
XmlReaderI

public class XmlReader
extends java.lang.Object
implements XmlReaderI

XML document reader.

XML documents are read in a "pull" fashion, where each item (tagged element, attribute, text content, and comment) is read individually by request. This is in contrast to other parser designs, such as SAX, which reads XML text and calls registered "callback" methods as each item is parsed, and DOM, which reads XML documents in their entirety.

This particular implementation relaxes some of the constraints of normal XML text:

Note that these enhancements allow nonconforming XML text to be accepted as valid XML.

Example

Consider the following XML document:

    <?xml version='1.0'?>
    <!-- Generated: 2003-05-13 21:52 Z -->
    <purchase-order form="A001">
      <customer>
        <address>2500 Main Street, Dallas,  TX 75025</address>
        <Shipping-Code   CODE =  "4B"/>
        <!-- Query: SKU="HG-52814(J)-F" -->
        <item
          Count="20" SKU="HG-52814(J)-F" Unit-Cost="149.95">
          Oak business desk, <![CDATA[cherry & chrome]]> finish
        </item>
      </customer>
      <!-- Tax rate: NJ -->
    </purchase-order> 

The XML document above is read as the following sequence of XML items:

    directive  "xml"
      attribute  "version", "1.0"
      comment  " Generated: 2003-05-13 21:52 Z "
      element  "purchase-order"
        attribute  "form", "A001"
        element  "customer"
          element  "address"
            text  "2500 Main Street, Dallas,  TX 75025"
          element  "Shipping-Code"
            attribute  "code", "4B"
          comment  " Query: SKU=\"HG-52814(J)-F\" "
          element  "item"
            attribute  "Count", "20"
            attribute  "SKU", "HG-52814(J)-F"
            attribute  "Unit-Cost", "149.95"
            text  "Oak business desk, cherry & chrome finish"
        comment  " Tax rate: NJ " 

Since:
2003-05-04
Version:
$Revision: 1.2 $ $Date: 2003/07/06 14:48:03 $
Author:
David R. Tribble (david@tribble.com).
Copyright 2003 by David R. Tribble, all rights reserved.
Permission is granted to freely use and distribute this source code provided that the original copyright and authorship notices remain intact.
See Also:
XmlWriter

Field Summary
 
Fields inherited from interface tribble.xml.XmlReaderI
FLAG_COMBINE_TEXT, FLAG_KEEP_COMMENTS, FLAG_KEEP_SPACES
 
Constructor Summary
XmlReader(java.io.InputStream in)
          Constructor.
XmlReader(java.io.Reader in)
          Constructor.
 
Method Summary
 void close()
          Close this XML input stream.
 XmlItemI readItem()
          Read the next XML item from this XML input stream.
 boolean setControlFlag(java.lang.String flag, boolean val)
          Modify a control flag of this XML input stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlReader

public XmlReader(java.io.Reader in)
Constructor.

Parameters:
in - A character input stream from which to read XML documents.
Since:
1.1, 2003-05-15

XmlReader

public XmlReader(java.io.InputStream in)
Constructor.

Parameters:
in - A byte input stream from which to read XML documents. The input stream is assumed to be UTF-8 encoded characters.
Since:
1.1, 2003-05-16
Method Detail

close

public void close()
           throws java.io.IOException
Close this XML input stream. This closes the underlying input stream and disassociates it from this XML stream. Also disassociates this parser from its internal memory objects.

Note that the parser is no longer usable after this method has been called.

Specified by:
close in interface XmlReaderI
Throws:
java.io.IOException - Thrown if an I/O error occurs.
Since:
1.1, 2003-05-15

setControlFlag

public boolean setControlFlag(java.lang.String flag,
                              boolean val)
Modify a control flag of this XML input stream.

Specified by:
setControlFlag in interface XmlReaderI
Parameters:
flag - The name of a control flag to modify.
val - The value to change the control flag to.
Returns:
The previous setting of the specified control flag.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if flag does not name a supported control flag.
Since:
1.1, 2003-05-15

readItem

public XmlItemI readItem()
                  throws java.io.IOException
Read the next XML item from this XML input stream.

Specified by:
readItem in interface XmlReaderI
Returns:
An XML item, or null if the end of the XML input has been reached.
Throws:
java.io.IOException - Thrown if an I/O (read) error occurs.
java.lang.IllegalStateException - (unchecked) Thrown if this reader is not in the proper state for reading an XML item (e.g., after the end of the XML input stream has been reached).
Since:
1.1, 2003-05-15