/* -*-             c-basic-offset: 4; indent-tabs-mode: nil; -*-  //------100-columns-wide------>|*/// for license please see accompanying LICENSE.txt file (available also at http://www.xmlpull.org/)package org.xmlpull.v1;import java.io.InputStream;import java.io.IOException;import java.io.Reader;/** * XML Pull Parser is an interface that defines parsing functionlity provided * in <a href="http://www.xmlpull.org/">XMLPULL V1 API</a> (visit this website to * learn more about API and its implementations). * * <p>There are following different * kinds of parser depending on which features are set:<ul> * <li><b>non-validating</b> parser as defined in XML 1.0 spec when *   FEATURE_PROCESS_DOCDECL is set to true * <li><b>validating parser</b> as defined in XML 1.0 spec when *   FEATURE_VALIDATION is true (and that implies that FEATURE_PROCESS_DOCDECL is true) * <li>when FEATURE_PROCESS_DOCDECL is false (this is default and *   if different value is required necessary must be changed before parsing is started) *   then parser behaves like XML 1.0 compliant non-validating parser under condition that *  <em>no DOCDECL is present</em> in XML documents *   (internal entites can still be defined with defineEntityReplacementText()). *   This mode of operation is intened <b>for operation in constrained environments</b> such as J2ME. * </ul> * * * <p>There are two key methods: next() and nextToken(). While next() provides * access to high level parsing events, nextToken() allows access to lower * level tokens. * * <p>The current event state of the parser * can be determined by calling the * <a href="#getEventType()">getEventType()</a> method. * Initially, the parser is in the <a href="#START_DOCUMENT">START_DOCUMENT</a> * state. * * <p>The method <a href="#next()">next()</a> advances the parser to the * next event. The int value returned from next determines the current parser * state and is identical to the value returned from following calls to * getEventType (). * * <p>Th following event types are seen by next()<dl> * <dt><a href="#START_TAG">START_TAG</a><dd> An XML start tag was read. * <dt><a href="#TEXT">TEXT</a><dd> Text content was read; * the text content can be retreived using the getText() method. *  (when in validating mode next() will not report ignorable whitespaces, use nextToken() instead) * <dt><a href="#END_TAG">END_TAG</a><dd> An end tag was read * <dt><a href="#END_DOCUMENT">END_DOCUMENT</a><dd> No more events are available * </dl> * * <p>after first next() or nextToken() (or any other next*() method) * is called user application can obtain * XML version, standalone and encoding from XML declaration * in following ways:<ul> * <li><b>version</b>: *  getProperty(&quot;<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-version">http://xmlpull.org/v1/doc/properties.html#xmldecl-version</a>&quot;) *       returns String ("1.0") or null if XMLDecl was not read or if property is not supported * <li><b>standalone</b>: *  getProperty(&quot;<a href="http://xmlpull.org/v1/doc/features.html#xmldecl-standalone">http://xmlpull.org/v1/doc/features.html#xmldecl-standalone</a>&quot;) *       returns Boolean: null if there was no standalone declaration *  or if property is not supported *         otherwise returns Boolean(true) if standalon="yes" and Boolean(false) when standalone="no" * <li><b>encoding</b>: obtained from getInputEncoding() *       null if stream had unknown encoding (not set in setInputStream) *           and it was not declared in XMLDecl * </ul> * * A minimal example for using this API may look as follows: * <pre> * import java.io.IOException; * import java.io.StringReader; * * import org.xmlpull.v1.XmlPullParser; * import org.xmlpull.v1.<a href="XmlPullParserException.html">XmlPullParserException.html</a>; * import org.xmlpull.v1.<a href="XmlPullParserFactory.html">XmlPullParserFactory</a>; * * public class SimpleXmlPullApp * { * *     public static void main (String args[]) *         throws XmlPullParserException, IOException *     { *         XmlPullParserFactory factory = XmlPullParserFactory.newInstance(); *         factory.setNamespaceAware(true); *         XmlPullParser xpp = factory.newPullParser(); * *         xpp.<a href="#setInput">setInput</a>( new StringReader ( "&lt;foo>Hello World!&lt;/foo>" ) ); *         int eventType = xpp.getEventType(); *         while (eventType != XmlPullParser.END_DOCUMENT) { *          if(eventType == XmlPullParser.START_DOCUMENT) { *              System.out.println("Start document"); *          } else if(eventType == XmlPullParser.END_DOCUMENT) { *              System.out.println("End document"); *          } else if(eventType == XmlPullParser.START_TAG) { *              System.out.println("Start tag "+xpp.<a href="#getName()">getName()</a>); *          } else if(eventType == XmlPullParser.END_TAG) { *              System.out.println("End tag "+xpp.getName()); *          } else if(eventType == XmlPullParser.TEXT) { *              System.out.println("Text "+xpp.<a href="#getText()">getText()</a>); *          } *          eventType = xpp.next(); *         } *     } * } * </pre> * * <p>The above example will generate the following output: * <pre> * Start document * Start tag foo * Text Hello World! * End tag foo * </pre> * * <p>For more details on API usage, please refer to the * quick Introduction available at <a href="http://www.xmlpull.org">http://www.xmlpull.org</a> * * @see XmlPullParserFactory * @see #defineEntityReplacementText * @see #getName * @see #getNamespace * @see #getText * @see #next * @see #nextToken * @see #setInput * @see #FEATURE_PROCESS_DOCDECL * @see #FEATURE_VALIDATION * @see #START_DOCUMENT * @see #START_TAG * @see #TEXT * @see #END_TAG * @see #END_DOCUMENT * * @author <a href="http://www-ai.cs.uni-dortmund.de/PERSONAL/haustein.html">Stefan Haustein</a> * @author <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a> */public interface XmlPullParser {    /** This constant represents the default namespace (empty string "") */    String NO_NAMESPACE = "";    // ----------------------------------------------------------------------------    // EVENT TYPES as reported by next()    /**     * Signalize that parser is at the very beginning of the document     * and nothing was read yet.     * This event type can only be observed by calling getEvent()     * before the first call to next(), nextToken, or nextTag()</a>).     *     * @see #next     * @see #nextToken     */    int START_DOCUMENT = 0;    /**     * Logical end of the xml document. Returned from getEventType, next()     * and nextToken()     * when the end of the input document has been reached.     * <p><strong>NOTE:</strong> calling again     * <a href="#next()">next()</a> or <a href="#nextToken()">nextToken()</a>     * will result in exception being thrown.     *     * @see #next     * @see #nextToken     */    int END_DOCUMENT = 1;    /**     * Returned from getEventType(),     * <a href="#next()">next()</a>, <a href="#nextToken()">nextToken()</a> when     * a start tag was read.     * The name of start tag is available from getName(), its namespace and prefix are     * available from getNamespace() and getPrefix()     * if <a href='#FEATURE_PROCESS_NAMESPACES'>namespaces are enabled</a>.     * See getAttribute* methods to retrieve element attributes.     * See getNamespace* methods to retrieve newly declared namespaces.     *     * @see #next     * @see #nextToken     * @see #getName     * @see #getPrefix     * @see #getNamespace     * @see #getAttributeCount     * @see #getDepth     * @see #getNamespaceCount     * @see #getNamespace     * @see #FEATURE_PROCESS_NAMESPACES     */    int START_TAG = 2;    /**     * Returned from getEventType(), <a href="#next()">next()</a>, or     * <a href="#nextToken()">nextToken()</a> when an end tag was read.     * The name of start tag is available from getName(), its     * namespace and prefix are     * available from getNamespace() and getPrefix().     *     * @see #next     * @see #nextToken     * @see #getName     * @see #getPrefix     * @see #getNamespace     * @see #FEATURE_PROCESS_NAMESPACES     */    int END_TAG = 3;    /**     * Character data was read and will is available by calling getText().     * <p><strong>Please note:</strong> <a href="#next()">next()</a> will     * accumulate multiple     * events into one TEXT event, skipping IGNORABLE_WHITESPACE,     * PROCESSING_INSTRUCTION and COMMENT events,     * In contrast, <a href="#nextToken()">nextToken()</a> will stop reading     * text when any other event is observed.     * Also, when the state was reached by calling next(), the text value will     * be normalized, whereas getText() will     * return unnormalized content in the case of nextToken(). This allows     * an exact roundtrip without chnanging line ends when examining low     * level events, whereas for high level applications the text is     * normalized apropriately.     *     * @see #next     * @see #nextToken     * @see #getText     */    int TEXT = 4;    // ----------------------------------------------------------------------------    // additional events exposed by lower level nextToken()    /**     * A CDATA sections was just read;     * this token is available only from calls to <a href="#nextToken()">nextToken()</a>.     * A call to next() will accumulate various text events into a single event     * of type TEXT. The text contained in the CDATA section is available     * by callling getText().     *     * @see #nextToken     * @see #getText     */    int CDSECT = 5;    /**     * An entity reference was just read;     * this token is available from <a href="#nextToken()">nextToken()</a>     * only. The entity name is available by calling getName(). If available,     * the replacement text can be obtained by calling getTextt(); otherwise,     * the user is responsibile for resolving the entity reference.     * This event type is never returned from next(); next() will     * accumulate the replacement text and other text     * events to a single TEXT event.     *     * @see #nextToken     * @see #getText     */    int ENTITY_REF = 6;    /**     * Ignorable whitespace was just read.     * This token is available only from <a href="#nextToken()">nextToken()</a>).     * For non-validating     * parsers, this event is only reported by nextToken() when outside     * the root element.     * Validating parsers may be able to detect ignorable whitespace at     * other locations.     * The ignorable whitespace string is available by calling getText()     *     * <p><strong>NOTE:</strong> this is different from calling the     *  isWhitespace() method, since text content     *  may be whitespace but not ignorable.     *     * Ignorable whitespace is skipped by next() automatically; this event     * type is never returned from next().     *     * @see #nextToken     * @see #getText     */    int IGNORABLE_WHITESPACE = 7;    /**     * An XML processing instruction declaration was just read. This     * event type is available only via <a href="#nextToken()">nextToken()</a>.     * getText() will return text that is inside the processing instruction.     * Calls to next() will skip processing instructions automatically.     * @see #nextToken     * @see #getText     */    int PROCESSING_INSTRUCTION = 8;    /**     * An XML comment was just read. This event type is this token is     * available via <a href="#nextToken()">nextToken()</a> only;     * calls to next() will skip comments automatically.     * The content of the comment can be accessed using the getText()     * method.     *     * @see #nextToken     * @see #getText     */    int COMMENT = 9;    /**     * An XML document type declaration was just read. This token is     * available from <a href="#nextToken()">nextToken()</a> only.     * The unparsed text inside the doctype is available via     * the getText() method.     *     * @see #nextToken     * @see #getText     */    int DOCDECL = 10;    /**     * This array can be used to convert the event type integer constants     * such as START_TAG or TEXT to     * to a string. For example, the value of TYPES[START_TAG] is     * the string "START_TAG".     *     * This array is intended for diagnostic output only. Relying     * on the contents of the array may be dangerous since malicous     * applications may alter the array, although it is final, due     * to limitations of the Java language.     */    String [] TYPES = {        "START_DOCUMENT",            "END_DOCUMENT",            "START_TAG",            "END_TAG",            "TEXT",            "CDSECT",            "ENTITY_REF",            "IGNORABLE_WHITESPACE",            "PROCESSING_INSTRUCTION",            "COMMENT",            "DOCDECL"    };    // ----------------------------------------------------------------------------    // namespace related features    /**     * This feature determines whether the parser processes     * namespaces. As for all features, the default value is false.     * <p><strong>NOTE:</strong> The value can not be changed during     * parsing an must be set before parsing.     *     * @see #getFeature     * @see #setFeature     */    String FEATURE_PROCESS_NAMESPACES =        "http://xmlpull.org/v1/doc/features.html#process-namespaces";    /**     * This feature determines whether namespace attributes are     * exposed via the attribute access methods. Like all features,     * the default value is false. This feature cannot be changed     * during parsing.     *     * @see #getFeature     * @see #setFeature     */    String FEATURE_REPORT_NAMESPACE_ATTRIBUTES =        "http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes";    /**     * This feature determines whether the document declaration