* is processed. If set to false,     * the DOCDECL event type is reported by nextToken()     * and ignored by next().     *     * If this featue is activated, then the document declaration     * must be processed by the parser.     *     * <p><strong>Please note:</strong> If the document type declaration     * was ignored, entity references may cause exceptions     * later in the parsing process.     * The default value of this feature is false. It cannot be changed     * during parsing.     *     * @see #getFeature     * @see #setFeature     */    String FEATURE_PROCESS_DOCDECL =        "http://xmlpull.org/v1/doc/features.html#process-docdecl";    /**     * If this feature is activated, all validation errors as     * defined in the XML 1.0 sepcification are reported.     * This implies that FEATURE_PROCESS_DOCDECL is true and both, the     * internal and external document type declaration will be processed.     * <p><strong>Please Note:</strong> This feature can not be changed     * during parsing. The default value is false.     *     * @see #getFeature     * @see #setFeature     */    String FEATURE_VALIDATION =        "http://xmlpull.org/v1/doc/features.html#validation";    /**     * Use this call to change the general behaviour of the parser,     * such as namespace processing or doctype declaration handling.     * This method must be called before the first call to next or     * nextToken. Otherwise, an exception is thrown.     * <p>Example: call setFeature(FEATURE_PROCESS_NAMESPACES, true) in order     * to switch on namespace processing. The initial settings correspond     * to the properties requested from the XML Pull Parser factory.     * If none were requested, all feautures are deactivated by default.     *     * @exception XmlPullParserException If the feature is not supported or can not be set     * @exception IllegalArgumentException If string with the feature name is null     */    void setFeature(String name,                           boolean state) throws XmlPullParserException;    /**     * Returns the current value of the given feature.     * <p><strong>Please note:</strong> unknown features are     * <strong>always</strong> returned as false.     *     * @param name The name of feature to be retrieved.     * @return The value of the feature.     * @exception IllegalArgumentException if string the feature name is null     */    boolean getFeature(String name);    /**     * Set the value of a property.     *     * The property name is any fully-qualified URI.     *     * @exception XmlPullParserException If the property is not supported or can not be set     * @exception IllegalArgumentException If string with the property name is null     */    void setProperty(String name,                            Object value) throws XmlPullParserException;    /**     * Look up the value of a property.     *     * The property name is any fully-qualified URI.     * <p><strong>NOTE:</strong> unknown properties are <strong>always</strong>     * returned as null.     *     * @param name The name of property to be retrieved.     * @return The value of named property.     */    Object getProperty(String name);    /**     * Set the input source for parser to the given reader and     * resets the parser. The event type is set to the initial value     * START_DOCUMENT.     * Setting the reader to null will just stop parsing and     * reset parser state,     * allowing the parser to free internal resources     * such as parsing buffers.     */    void setInput(Reader in) throws XmlPullParserException;    /**     * Sets the input stream the parser is going to process.     * This call resets the parser state and sets the event type     * to the initial value START_DOCUMENT.     *     * <p><strong>NOTE:</strong> If an input encoding string is passed,     *  it MUST be used. Otherwise,     *  if inputEncoding is null, the parser SHOULD try to determine     *  input encoding following XML 1.0 specification (see below).     *  If encoding detection is supported then following feature     *  <a href="http://xmlpull.org/v1/doc/features.html#detect-encoding">http://xmlpull.org/v1/doc/features.html#detect-encoding</a>     *  MUST be true amd otherwise it must be false     *     * @param inputStream contains a raw byte input stream of possibly     *     unknown encoding (when inputEncoding is null).     *     * @param inputEncoding if not null it MUST be used as encoding for inputStream     */    void setInput(InputStream inputStream, String inputEncoding)        throws XmlPullParserException;    /**     * Returns the input encoding if known, null otherwise.     * If setInput(InputStream, inputEncoding) was called with an inputEncoding     * value other than null, this value must be returned     * from this method. Otherwise, if inputEncoding is null and     * the parser suppports the encoding detection feature     * (http://xmlpull.org/v1/doc/features.html#detect-encoding),     * it must return the detected encoding.     * If setInput(Reader) was called, null is returned.     * After first call to next if XML declaration was present this method     * will return encoding declared.     */    String getInputEncoding();    /**     * Set new value for entity replacement text as defined in     * <a href="http://www.w3.org/TR/REC-xml#intern-replacement">XML 1.0 Section 4.5     * Construction of Internal Entity Replacement Text</a>.     * If FEATURE_PROCESS_DOCDECL or FEATURE_VALIDATION are set, calling this     * function will result in an exception -- when processing of DOCDECL is     * enabled, there is no need to the entity replacement text manually.     *     * <p>The motivation for this function is to allow very small     * implementations of XMLPULL that will work in J2ME environments.     * Though these implementations may not be able to process the document type     * declaration, they still can work with known DTDs by using this function.     *     * <p><b>Please notes:</b> The given value is used literally as replacement text     * and it corresponds to declaring entity in DTD that has all special characters     * escaped: left angle bracket is replaced with &amp;lt;, ampersnad with &amp;amp;     * and so on.     *     * <p><b>Note:</b> The given value is the literal replacement text and must not     * contain any other entity reference (if it contains any entity reference     * there will be no further replacement).     *     * <p><b>Note:</b> The list of pre-defined entity names will     * always contain standard XML entities such as     * amp (&amp;amp;), lt (&amp;lt;), gt (&amp;gt;), quot (&amp;quot;), and apos (&amp;apos;).     * Those cannot be redefined by this method!     *     * @see #setInput     * @see #FEATURE_PROCESS_DOCDECL     * @see #FEATURE_VALIDATION     */    void defineEntityReplacementText( String entityName,                                            String replacementText ) throws XmlPullParserException;    /**     * Returns the numbers of elements in the namespace stack for the given     * depth.     * If namespaces are not enabled, 0 is returned.     *     * <p><b>NOTE:</b> when parser is on END_TAG then it is allowed to call     *  this function with getDepth()+1 argument to retrieve position of namespace     *  prefixes and URIs that were declared on corresponding START_TAG.     * <p><b>NOTE:</b> to retrieve lsit of namespaces declared in current element:<pre>     *       XmlPullParser pp = ...     *       int nsStart = pp.getNamespaceCount(pp.getDepth()-1);     *       int nsEnd = pp.getNamespaceCount(pp.getDepth());     *       for (int i = nsStart; i < nsEnd; i++) {     *          String prefix = pp.getNamespacePrefix(i);     *          String ns = pp.getNamespaceUri(i);     *           // ...     *      }     * </pre>     *     * @see #getNamespacePrefix     * @see #getNamespaceUri     * @see #getNamespace()     * @see #getNamespace(String)     */    int getNamespaceCount(int depth) throws XmlPullParserException;    /**     * Returns the namespace prefixe for the given position     * in the namespace stack.     * Default namespace declaration (xmlns='...') will have null as prefix.     * If the given index is out of range, an exception is thrown.     * <p><b>Please note:</b> when the parser is on an END_TAG,     * namespace prefixes that were declared     * in the corresponding START_TAG are still accessible     * although they are no longer in scope.     */    String getNamespacePrefix(int pos) throws XmlPullParserException;    /**     * Returns the namespace URI for the given position in the     * namespace stack     * If the position is out of range, an exception is thrown.     * <p><b>NOTE:</b> when parser is on END_TAG then namespace prefixes that were declared     *  in corresponding START_TAG are still accessible even though they are not in scope     */    String getNamespaceUri(int pos) throws XmlPullParserException;    /**     * Returns the URI corresponding to the given prefix,     * depending on current state of the parser.     *     * <p>If the prefix was not declared in the current scope,     * null is returned. The default namespace is included     * in the namespace table and is available via     * getNamespace (null).     *     * <p>This method is a convenience method for     *     * <pre>     *  for (int i = getNamespaceCount(getDepth ())-1; i >= 0; i--) {     *   if (getNamespacePrefix(i).equals( prefix )) {     *     return getNamespaceUri(i);     *   }     *  }     *  return null;     * </pre>     *     * <p><strong>Please note:</strong> parser implementations     * may provide more efifcient lookup, e.g. using a Hashtable.     * The 'xml' prefix is bound to "http://www.w3.org/XML/1998/namespace", as     * defined in the     * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a>     * specification. Analogous, the 'xmlns' prefix is resolved to     * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>     *     * @see #getNamespaceCount     * @see #getNamespacePrefix     * @see #getNamespaceUri     */    String getNamespace (String prefix);    // --------------------------------------------------------------------------    // miscellaneous reporting methods    /**     * Returns the current depth of the element.     * Outside the root element, the depth is 0. The     * depth is incremented by 1 when a start tag is reached.     * The depth is decremented AFTER the end tag     * event was observed.     *     * <pre>     * &lt;!-- outside --&gt;     0     * &lt;root>                  1     *   sometext                 1     *     &lt;foobar&gt;         2     *     &lt;/foobar&gt;        2     * &lt;/root&gt;              1     * &lt;!-- outside --&gt;     0     * </pre>     */    int getDepth();    /**     * Returns a short text describing the current parser state, including     * the position, a     * description of the current event and the data source if known.     * This method is especially useful to provide meaningful     * error messages and for debugging purposes.     */    String getPositionDescription ();    /**     * Returns the current line number, starting from 1.     * When the parser does not know the current line number     * or can not determine it,  -1 is returned (e.g. for WBXML).     *     * @return current line number or -1 if unknown.     */    int getLineNumber();    /**     * Returns the current column number, starting from 0.     * When the parser does not know the current column number     * or can not determine it,  -1 is returned (e.g. for WBXML).     *     * @return current column number or -1 if unknown.     */    int getColumnNumber();    // --------------------------------------------------------------------------    // TEXT related methods    /**     * Checks whether the current TEXT event contains only whitespace     * characters.     * For IGNORABLE_WHITESPACE, this is always true.     * For TEXT and CDSECT, false is returned when the current event text     * contains at least one non-white space character. For any other     * event type an exception is thrown.     *     * <p><b>Please note:</b> non-validating parsers are not     * able to distinguish whitespace and ignorable whitespace,     * except from whitespace outside the root element. Ignorable     * whitespace is reported as separate event, which is exposed     * via nextToken only.     *     */    boolean isWhitespace() throws XmlPullParserException;    /**     * Returns the text content of the current event as String.     * The value returned depends on current event type,     * for example for TEXT event it is element content     * (this is typical case when next() is used).     *     * See description of nextToken() for detailed description of     * possible returned values for different types of events.     *     * <p><strong>NOTE:</strong> in case of ENTITY_REF, this method returns     * the entity replacement text (or null if not available). This is     * the only case where     * getText() and getTextCharacters() return different values.     *     * @see #getEventType     * @see #next     * @see #nextToken     */    String getText ();    /**     * Returns the buffer that contains the text of the current event,     * as well as the start offset and length relevant for the current     * event. See getText(), next() and nextToken() for description of possible returned values.     *     * <p><strong>Please note:</strong> this buffer must not     * be modified and its content MAY change after a call to     * next() or nextToken(). This method will always return the     * same value as getText(), except for ENTITY_REF. In the case     * of ENTITY ref, getText() returns the replacement text and     * this method returns the actual input buffer containing the     * entity name.     * If getText() returns null, this method returns null as well and     * the values returned in the holder array MUST be -1 (both start     * and length).     *     * @see #getText     * @see #next     * @see #nextToken     *     * @param holderForStartAndLength Must hold an 2-element int array     * into which the start offset and length values will be written.     * @return char buffer that contains the text of the current event     *  (null if the current event has no text associated).     */    char[] getTextCharacters(int [] holderForStartAndLength);    // --------------------------------------------------------------------------    // START_TAG / END_TAG shared methods    /**     * Returns the namespace URI of the current element.     * The default namespace is represented