tribble.xml.impl
Class XmlReader

java.lang.Object
  tribble.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:

• The opening '<' for tagged elements can be followed by an arbitrary amount of whitespace characters.

• The closing tag '</tag>' of a given tagged element can be abbreviated as '</>.

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