* 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"* * * @version $Revision: 1.5 $ $Date: 2003/07/06 14:38:13 $ * @since 2003-04-13 * @author * David R. Tribble * (david@tribble.com). *
* 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. */ public static final String FLAG_KEEP_COMMENTS = "KEEP_COMMENTS"; /** 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.) */ public static final String FLAG_KEEP_SPACES = "KEEP_SPACES"; /** 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 {@link XmlTextI} item. Otherwise, the parser is * free to split the text contents into two or more separate * {@link XmlTextI} items. * *
* It is recommended, if this flag is disabled, that parsers choose to split * long content text at newlines. */ public static final String FLAG_COMBINE_TEXT = "COMBINE_TEXT"; // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Public methods /*************************************************************************** * Close this XML input stream. * This closes the underlying input stream and disassociates it from this XML * stream. * * @throws IOException * Thrown if an I/O error occurs. * * @throws IllegalStateException (unchecked) * Thrown if the XML stream is not open. * * @since 1.3, 2003-05-13 */ public void close() throws IOException; /*************************************************************************** * Modify a control flag for this XML input stream. * * @param 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). * * @param val * The value to change the control flag to. * * @return * The previous setting of the specified control flag. * * @throws IllegalArgumentException (unchecked) * Thrown if flag does not name a supported control flag. * * @since 1.4, 2003-05-15 */ public boolean setControlFlag(String flag, boolean val); /*************************************************************************** * Read the next XML item from this XML input stream. * * @return * An XML item, or null if the end of the XML input has been reached. * * @throws IOException * Thrown if an I/O (read) error occurs. * * @throws 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 */ public XmlItemI readItem() throws IOException; } // End XmlReaderI.java