tribble.xml
Interface XmlReaderI

All Known Implementing Classes:

XmlReader

public interface XmlReaderI

XML document reader.

This interface is used to implement any kind of high-level input stream that reads XML documents.

XML documents are read in a "pull" fashion, where each item (tagged element, attribute, text content, etc.) 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 interface provides a very simplified API for reading simple XML documents. Only simple, straight XML is recognized; DTD and stylesheet markups are not required to be recognized. While this limits the universe of possible XML documents accepted by parsers implementing this interface, it also makes implementing such parsers much simpler and smaller.

Implementations of this interface should provide at least one constructor that takes some kind of input text stream (such as a java.io.Reader or java.io.InputStream) as input. For example:

    class MyXmlReader
        implements tribble.xml.XmlReaderI
    {
        // Constructor
        public MyXmlReader(java.io.Reader in)
        {
            ...
        }

        ...
    } 

Example XML

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" 

Since:

2003-04-13

Version:

$Revision: 1.5 $ $Date: 2003/07/06 14:38:13 $

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:

XmlWriterI

Field Summary

static java.lang.String	FLAG_COMBINE_TEXT Control flag: Read content text lines as a single item.
static java.lang.String	FLAG_KEEP_COMMENTS Control flag: Preserve comments.
static java.lang.String	FLAG_KEEP_SPACES Control flag: Preserve whitespace content characters.
static java.lang.String	REV Revision information.

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 for this XML input stream.

Field Detail

REV

public static final java.lang.String REV

Revision information.

See Also:

Constant Field Values

FLAG_KEEP_COMMENTS

public static final java.lang.String FLAG_KEEP_COMMENTS

Control flag: Preserve comments.

If this flag is enabled, the XML parser must return comments as they are read from the input XML document. Otherwise, the parser should discard all comments.

See Also:

Constant Field Values

FLAG_KEEP_SPACES

public static final java.lang.String FLAG_KEEP_SPACES

Control flag: Preserve whitespace content characters.

If this flag is enabled, the XML parser must preserve all whitespace characters as they occur within the text contents of each element. Otherwise, the parser is free to combine multiple adjacent whitespace characters into a single space. (This is similar to the semantics of the "xmlns:space='preserve'" attribute.)

See Also:

Constant Field Values

FLAG_COMBINE_TEXT

public static final java.lang.String FLAG_COMBINE_TEXT

Control flag: Read content text lines as a single item.

If this flag is enabled, the XML parser must return the text contents of each element as a single XmlTextI item. Otherwise, the parser is free to split the text contents into two or more separate XmlTextI items.

It is recommended, if this flag is disabled, that parsers choose to split long content text at newlines.

See Also:

Constant Field Values

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.

Throws:

java.io.IOException - Thrown if an I/O error occurs.

java.lang.IllegalStateException - (unchecked) Thrown if the XML stream is not open.

Since:

1.3, 2003-05-13

setControlFlag

public boolean setControlFlag(java.lang.String flag,
                              boolean val)

Modify a control flag for this XML input stream.

Parameters:

flag - The name of a control flag to modify. Flag names are implementation-specific, but some names are common to all implementations (see the FLAG_XXX constants).

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.4, 2003-05-15

readItem

public XmlItemI readItem()
                  throws java.io.IOException

Read the next XML item from this XML input stream.

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.3, 2003-05-13