* as empty string.     * If namespaces are not enabled, an empty String ("") is always returned.     * The current event must be START_TAG or END_TAG; otherwise,     * null is returned.     */    String getNamespace ();    /**     * For START_TAG or END_TAG events, the (local) name of the current     * element is returned when namespaces are enabled. When namespace     * processing is disabled, the raw name is returned.     * For ENTITY_REF events, the entity name is returned.     * If the current event is not START_TAG, END_TAG, or ENTITY_REF,     * null is returned.     * <p><b>Please note:</b> To reconstruct the raw element name     *  when namespaces are enabled and the prefix is not null,     * you will need to  add the prefix and a colon to localName..     *     */    String getName();    /**     * Returns the prefix of the current element.     * If the element is in the default namespace (has no prefix),     * null is returned.     * If namespaces are not enabled, or the current event     * is not  START_TAG or END_TAG, null is returned.     */    String getPrefix();    /**     * Returns true if the current event is START_TAG and the tag     * is degenerated     * (e.g. &lt;foobar/&gt;).     * <p><b>NOTE:</b> if the parser is not on START_TAG, an exception     * will be thrown.     */    boolean isEmptyElementTag() throws XmlPullParserException;    // --------------------------------------------------------------------------    // START_TAG Attributes retrieval methods    /**     * Returns the number of attributes of the current start tag, or     * -1 if the current event type is not START_TAG     *     * @see #getAttributeNamespace     * @see #getAttributeName     * @see #getAttributePrefix     * @see #getAttributeValue     */    int getAttributeCount();    /**     * Returns the namespace URI of the attribute     * with the given index (starts from 0).     * Returns an empty string ("") if namespaces are not enabled     * or the attribute has no namespace.     * Throws an IndexOutOfBoundsException if the index is out of range     * or the current event type is not START_TAG.     *     * <p><strong>NOTE:</strong> if FEATURE_REPORT_NAMESPACE_ATTRIBUTES is set     * then namespace attributes (xmlns:ns='...') must be reported     * with namespace     * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>     * (visit this URL for description!).     * The default namespace attribute (xmlns="...") will be reported with empty namespace.     * <p><strong>NOTE:</strong>The xml prefix is bound as defined in     * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a>     * specification to "http://www.w3.org/XML/1998/namespace".     *     * @param zero based index of attribute     * @return attribute namespace,     *   empty string ("") is returned  if namesapces processing is not enabled or     *   namespaces processing is enabled but attribute has no namespace (it has no prefix).     */    String getAttributeNamespace (int index);    /**     * Returns the local name of the specified attribute     * if namespaces are enabled or just attribute name if namespaces are disabled.     * Throws an IndexOutOfBoundsException if the index is out of range     * or current event type is not START_TAG.     *     * @param zero based index of attribute     * @return attribute name (null is never returned)     */    String getAttributeName (int index);    /**     * Returns the prefix of the specified attribute     * Returns null if the element has no prefix.     * If namespaces are disabled it will always return null.     * Throws an IndexOutOfBoundsException if the index is out of range     * or current event type is not START_TAG.     *     * @param zero based index of attribute     * @return attribute prefix or null if namespaces processing is not enabled.     */    String getAttributePrefix(int index);    /**     * Returns the type of the specified attribute     * If parser is non-validating it MUST return CDATA.     *     * @param zero based index of attribute     * @return attribute type (null is never returned)     */    String getAttributeType(int index);    /**     * Returns if the specified attribute was not in input was declared in XML.     * If parser is non-validating it MUST always return false.     * This information is part of XML infoset:     *     * @param zero based index of attribute     * @return false if attribute was in input     */    boolean isAttributeDefault(int index);    /**     * Returns the given attributes value.     * Throws an IndexOutOfBoundsException if the index is out of range     * or current event type is not START_TAG.     *     * <p><strong>NOTE:</strong> attribute value must be normalized     * (including entity replacement text if PROCESS_DOCDECL is false) as described in     * <a href="http://www.w3.org/TR/REC-xml#AVNormalize">XML 1.0 section     * 3.3.3 Attribute-Value Normalization</a>     *     * @see #defineEntityReplacementText     *     * @param zero based index of attribute     * @return value of attribute (null is never returned)     */    String getAttributeValue(int index);    /**     * Returns the attributes value identified by namespace URI and namespace localName.     * If namespaces are disabled namespace must be null.     * If current event type is not START_TAG then IndexOutOfBoundsException will be thrown.     *     * <p><strong>NOTE:</strong> attribute value must be normalized     * (including entity replacement text if PROCESS_DOCDECL is false) as described in     * <a href="http://www.w3.org/TR/REC-xml#AVNormalize">XML 1.0 section     * 3.3.3 Attribute-Value Normalization</a>     *     * @see #defineEntityReplacementText     *     * @param namespace Namespace of the attribute if namespaces are enabled otherwise must be null     * @param name If namespaces enabled local name of attribute otherwise just attribute name     * @return value of attribute or null if attribute with given name does not exist     */    String getAttributeValue(String namespace,                                    String name);    // --------------------------------------------------------------------------    // actual parsing methods    /**     * Returns the type of the current event (START_TAG, END_TAG, TEXT, etc.)     *     * @see #next()     * @see #nextToken()     */    int getEventType()        throws XmlPullParserException;    /**     * Get next parsing event - element content wil be coalesced and only one     * TEXT event must be returned for whole element content     * (comments and processing instructions will be ignored and emtity references     * must be expanded or exception mus be thrown if entity reerence can not be exapnded).     * If element content is empty (content is "") then no TEXT event will be reported.     *     * <p><b>NOTE:</b> empty element (such as &lt;tag/>) will be reported     *  with  two separate events: START_TAG, END_TAG - it must be so to preserve     *   parsing equivalency of empty element to &lt;tag>&lt;/tag>.     *  (see isEmptyElementTag ())     *     * @see #isEmptyElementTag     * @see #START_TAG     * @see #TEXT     * @see #END_TAG     * @see #END_DOCUMENT     */    int next()        throws XmlPullParserException, IOException;    /**     * This method works similarly to next() but will expose     * additional event types (COMMENT, CDSECT, DOCDECL, ENTITY_REF, PROCESSING_INSTRUCTION, or     * IGNORABLE_WHITESPACE) if they are available in input.     *     * <p>If special feature     * <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">FEATURE_XML_ROUNDTRIP</a>     * (identified by URI: http://xmlpull.org/v1/doc/features.html#xml-roundtrip)     * is enabled it is possible to do XML document round trip ie. reproduce     * exectly on output the XML input using getText():     * returned content is always unnormalized (exactly as in input).     * Otherwise returned content is end-of-line normalized as described     * <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line Handling</a>     * and. Also when this feature is enabled exact content of START_TAG, END_TAG,     * DOCDECL and PROCESSING_INSTRUCTION is available.     *     * <p>Here is the list of tokens that can be  returned from nextToken()     * and what getText() and getTextCharacters() returns:<dl>     * <dt>START_DOCUMENT<dd>null     * <dt>END_DOCUMENT<dd>null     * <dt>START_TAG<dd>null unless FEATURE_XML_ROUNDTRIP     *   enabled and then returns XML tag, ex: &lt;tag attr='val'>     * <dt>END_TAG<dd>null unless FEATURE_XML_ROUNDTRIP     *  id enabled and then returns XML tag, ex: &lt;/tag>     * <dt>TEXT<dd>return element content.     *  <br>Note: that element content may be delivered in multiple consecutive TEXT events.     * <dt>IGNORABLE_WHITESPACE<dd>return characters that are determined to be ignorable white     * space. If the FEATURE_XML_ROUNDTRIP is enabled all whitespace content outside root     * element will always reported as IGNORABLE_WHITESPACE otherise rteporting is optional.     *  <br>Note: that element content may be delevered in multiple consecutive IGNORABLE_WHITESPACE events.     * <dt>CDSECT<dd>     * return text <em>inside</em> CDATA     *  (ex. 'fo&lt;o' from &lt;!CDATA[fo&lt;o]]>)     * <dt>PROCESSING_INSTRUCTION<dd>     *  if FEATURE_XML_ROUNDTRIP is true     *  return exact PI content ex: 'pi foo' from &lt;?pi foo?>     *  otherwise it may be exact PI content or concatenation of PI target,     * space and data so for example for     *   &lt;?target    data?> string &quot;target data&quot; may     *       be returned if FEATURE_XML_ROUNDTRIP is false.     * <dt>COMMENT<dd>return comment content ex. 'foo bar' from &lt;!--foo bar-->     * <dt>ENTITY_REF<dd>getText() MUST return entity replacement text if PROCESS_DOCDECL is false     * otherwise getText() MAY return null,     * additionally getTextCharacters() MUST return entity name     * (for example 'entity_name' for &amp;entity_name;).     * <br><b>NOTE:</b> this is the only place where value returned from getText() and     *   getTextCharacters() <b>are different</b>     * <br><b>NOTE:</b> it is user responsibility to resolve entity reference     *    if PROCESS_DOCDECL is false and there is no entity replacement text set in     *    defineEntityReplacementText() method (getText() will be null)     * <br><b>NOTE:</b> character entities (ex. &amp;#32;) and standard entities such as     *  &amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos; are reported as well     *  and are <b>not</b> reported as TEXT tokens but as ENTITY_REF tokens!     *  This requirement is added to allow to do roundtrip of XML documents!     * <dt>DOCDECL<dd>     * if FEATURE_XML_ROUNDTRIP is true or PROCESS_DOCDECL is false     * then return what is inside of DOCDECL for example it returns:<pre>     * &quot; titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"     * [&lt;!ENTITY % active.links "INCLUDE">]&quot;</pre>     * <p>for input document that contained:<pre>     * &lt;!DOCTYPE titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"     * [&lt;!ENTITY % active.links "INCLUDE">]></pre>     * otherwise if FEATURE_XML_ROUNDTRIP is false and PROCESS_DOCDECL is true     *    then what is returned is undefined (it may be even null)     * </dd>     * </dl>     *     * <p><strong>NOTE:</strong> there is no gurantee that there will only one TEXT or     * IGNORABLE_WHITESPACE event from nextToken() as parser may chose to deliver element content in     * multiple tokens (dividing element content into chunks)     *     * <p><strong>NOTE:</strong> whether returned text of token is end-of-line normalized     *  is depending on FEATURE_XML_ROUNDTRIP.     *     * <p><strong>NOTE:</strong> XMLDecl (&lt;?xml ...?&gt;) is not reported but its content     * is available through optional properties (see class description above).     *     * @see #next     * @see #START_TAG     * @see #TEXT     * @see #END_TAG     * @see #END_DOCUMENT     * @see #COMMENT     * @see #DOCDECL     * @see #PROCESSING_INSTRUCTION     * @see #ENTITY_REF     * @see #IGNORABLE_WHITESPACE     */    int nextToken()        throws XmlPullParserException, IOException;    //-----------------------------------------------------------------------------    // utility methods to mak XML parsing easier ...    /**     * Test if the current event is of the given type and if the     * namespace and name do match. null will match any namespace     * and any name. If the test is not passed, an exception is     * thrown. The exception text indicates the parser position,     * the expected event and the current event that is not meeting the     * requirement.     *     * <p>Essentially it does this     * <pre>     *  if (type != getEventType()     *  || (namespace != null &amp;&amp;  !namespace.equals( getNamespace () ) )     *  || (name != null &amp;&amp;  !name.equals( getName() ) ) )     *     throw new XmlPullParserException( "expected "+ TYPES[ type ]+getPositionDescription());     * </pre>     */    void require(int type, String namespace, String name)        throws XmlPullParserException, IOException;    /**     * If current event is START_TAG then if next element is TEXT then element content is returned     * or if next event is END_TAG then empty string is returned, otherwise exception is thrown.     * After calling this function successfully parser will be positioned on END_TAG.     *     * <p>The motivation for this function is to allow to parse consistently both     * empty elements and elements that has non empty content, for example for input: <ol>     * <li>&lt;tag&gt;foo&lt;/tag&gt;     * <li>&lt;tag&gt;&lt;/tag&gt; (which is equivalent to &lt;tag/&gt;     * both input can be parsed with the same code:     * <pre>     *   p.nextTag()     *   p.requireEvent(p.START_TAG, "", "tag");     *   String content = p.nextText();     *   p.requireEvent(p.END_TAG, "", "tag");     * </pre>     * This function together with nextTag make it very easy to parse XML that has     * no mixed content.     *     *     * <p>Essentially it does this     * <pre>     *  if(getEventType() != START_TAG) {     *     throw new XmlPullParserException(     *       "parser must be on START_TAG to read next text", this, null);     *  }     *  int eventType = next();     *  if(eventType == TEXT) {     *     String result = getText();     *     eventType = next();     *     if(eventType != END_TAG) {     *       throw new XmlPullParserException(     *          "event TEXT it must be immediately followed by END_TAG", this, null);     *      }     *      return result;     *  } else if(eventType == END_TAG) {     *     return "";     *  } else {     *     throw new XmlPullParserException(     *       "parser must be on START_TAG or TEXT to read text", this, null);     *  }     * </pre>     */    String nextText() throws XmlPullParserException, IOException;    /**     * Call next() and return event if it is START_TAG or END_TAG     * otherwise throw an exception.     * It will skip whitespace TEXT before actual tag if any.     *     * <p>essentially it does this     * <pre>     *   int eventType = next();     *   if(eventType == TEXT &amp;&amp;  isWhitespace()) {   // skip whitespace     *      eventType = next();     *   }     *   if (eventType != START_TAG &amp;&amp;  eventType != END_TAG) {     *      throw new XmlPullParserException("expected start or end tag", this, null);     *   }     *   return eventType;     * </pre>     */    int nextTag() throws XmlPullParserException, IOException;}