/* -*-             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.codehaus.plexus.util.xml.pull;

import java.io.InputStream;
import java.io.IOException;
import java.io.Reader;

/**
 * XML Pull Parser is an interface that defines parsing functionality 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 entities can still be defined with
 * defineEntityReplacementText()). This mode of operation is intended <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>
 * The 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 retrieved 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 standalone="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.XmlPullParserException;
 * import org.xmlpull.v1.XmlPullParserFactory;
 *
 * public class SimpleXmlPullApp
 * {
 *
 *     public static void main (String args[])
 *         throws XmlPullParserException, IOException
 *     {
 *         XmlPullParserFactory factory = XmlPullParserFactory.newInstance();
 *         factory.setNamespaceAware(true);
 *         XmlPullParser xpp = factory.newPullParser();
 *
 *         xpp.setInput( new StringReader ( "&lt;foo%gt;Hello World!&lt;/foo&gt;" ) );
 *         int eventType = xpp.getEventType();
 *         while (eventType != xpp.END_DOCUMENT) {
 *          if(eventType == xpp.START_DOCUMENT) {
 *              System.out.println("Start document");
 *          } else if(eventType == xpp.END_DOCUMENT) {
 *              System.out.println("End document");
 *          } else if(eventType == xpp.START_TAG) {
 *              System.out.println("Start tag "+xpp.getName());
 *          } else if(eventType == xpp.END_TAG) {
 *              System.out.println("End tag "+xpp.getName());
 *          } else if(eventType == xpp.TEXT) {
 *              System.out.println("Text "+xpp.getText());
 *          }
 *          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>
 * 
 * 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 #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()).
     *
     * @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 changing line ends when
     * examining low level events, whereas for high level applications the text is normalized appropriately.
     *
     * @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 calling 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 responsible 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 malicious 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 is processed. If set to false, the DOCDECL event type is
     * reported by nextToken() and ignored by next(). If this feature 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 specification 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 features are deactivated by default.
     * @param name feature name
     * @param state feature state
     * @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.
     * @param name property name
     * @param value property value
     * @exception XmlPullParserException If the property is not supported or can not be set
     * @exception IllegalArgumentException If string with the property name is null
     * @throws XmlPullParserException parsing issue
     */
    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.
     * @param in the Reader
     * @throws XmlPullParserException parsing issue
     */
    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 and 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
     * @throws XmlPullParserException parsing issue
     */
    void setInput( InputStream inputStream, String inputEncoding )
        throws XmlPullParserException;

    /**
     * @return 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 supports 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;, ampersand 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!
     * @param entityName entity name
     * @param replacementText remplacement
     * @see #setInput
     * @see #FEATURE_PROCESS_DOCDECL
     * @see #FEATURE_VALIDATION
     * @throws XmlPullParserException parsing issue
     */
    void defineEntityReplacementText( String entityName, String replacementText )
        throws XmlPullParserException;

    /**
     * @return 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 &gt; nsEnd; i++) {
     *          String prefix = pp.getNamespacePrefix(i);
     *          String ns = pp.getNamespaceUri(i);
     *           // ...
     *      }
     * </pre>
     *
     * @see #getNamespacePrefix
     * @see #getNamespaceUri
     * @see #getNamespace()
     * @see #getNamespace(String)
     * @param depth depth
     * @throws XmlPullParserException parsing issue
     */
    int getNamespaceCount( int depth )
        throws XmlPullParserException;

    /**
     * @return Returns the namespace prefix 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.
     *
     * <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.
     *  namespace prefix
     * @param pos namespace stack position
     * @throws XmlPullParserException parsing issue
     */
    String getNamespacePrefix( int pos )
        throws XmlPullParserException;

    /**
     * @return Returns the namespace URI for the given position in the namespace stack If the position is out of range, an
     * exception is thrown.
     *
     * <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
     * @throws XmlPullParserException parsing issue
     * @param pos namespace stack position
     */
    String getNamespaceUri( int pos )
        throws XmlPullParserException;

    /**
     * @return 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 &gt;= 0; i-- )
     * {
     *     if ( getNamespacePrefix( i ).equals( prefix ) )
     *     {
     *         return getNamespaceUri( i );
     *     }
     * }
     * return null;
     * </pre>
     * <p>
     * <strong>Please note:</strong> parser implementations may provide more efficient 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>
     * @param prefix given prefix
     * @see #getNamespaceCount
     * @see #getNamespacePrefix
     * @see #getNamespaceUri
     */
    String getNamespace( String prefix );

    // --------------------------------------------------------------------------
    // miscellaneous reporting methods

    /**
     * @return 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&gt;                  1
     *   sometext                 1
     *     &lt;foobar&gt;         2
     *     &lt;/foobar&gt;        2
     * &lt;/root&gt;              1
     * &lt;!-- outside --&gt;     0
     * </pre>
     */
    int getDepth();

    /**
     * @return 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

    /**
     * @return 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.
     * @throws XmlPullParserException parsing issue
     */
    boolean isWhitespace()
        throws XmlPullParserException;

    /**
     * @return  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

    /**
     * @return the namespace URI of the current element. The default namespace is represented 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();

    /**
     * @return 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();

    /**
     * @return 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();

    /**
     * @return 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.
     * @throws XmlPullParserException parsing issue
     */
    boolean isEmptyElementTag()
        throws XmlPullParserException;

    // --------------------------------------------------------------------------
    // START_TAG Attributes retrieval methods

    /**
     * @return 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 index zero based index of attribute
     * @return attribute namespace, empty string ("") is returned if namespaces 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 index 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 index 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 index 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 index 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 index 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

    /**
     * @return the type of the current event (START_TAG, END_TAG, TEXT, etc.)
     *
     * @see #next()
     * @see #nextToken()
     * @throws XmlPullParserException parsing issue
     */
    int getEventType()
        throws XmlPullParserException;

    /**
     * @return 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 entity references must be expanded or
     * exception mus be thrown if entity reference can not be expanded). If element content is empty (content is "")
     * then no TEXT event will be reported.
     * <p>
     * <b>NOTE:</b> empty element (such as &lt;tag/&gt;) 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&gt;&lt;/tag&gt;. (see isEmptyElementTag ())
     *
     * @see #isEmptyElementTag
     * @see #START_TAG
     * @see #TEXT
     * @see #END_TAG
     * @see #END_DOCUMENT
     * @throws XmlPullParserException parsing issue
     * @throws IOException io issue
     */
    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 exactly 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()
     * @return
     * <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'&gt;
     * <dt>END_TAG
     * <dd>null unless FEATURE_XML_ROUNDTRIP id enabled and then returns XML tag, ex: &lt;/tag&gt;
     * <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 otherwise reporting is
     * optional. <br>
     * Note: that element content may be delivered 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]]&gt;)
     * <dt>PROCESSING_INSTRUCTION
     * <dd>if FEATURE_XML_ROUNDTRIP is true return exact PI content ex: 'pi foo' from &lt;?pi foo?&gt; otherwise it may be
     * exact PI content or concatenation of PI target, space and data so for example for &lt;?target data?&gt; 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--&gt;
     * <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"&gt;]&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"&gt;]&gt;
     * </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 guarantee 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).
     * @throws XmlPullParserException parsing issue
     * @throws IOException io issue
     * @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>
     * @param type type
     * @param name name
     * @param namespace namespace
     * @throws XmlPullParserException parsing issue
     * @throws IOException io issue
     */
    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></li></ol>
     * 
     * 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>
     * @return see description
     * @throws XmlPullParserException parsing issue
     * @throws IOException io issue
     */
    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>
     * @return see description
     * @throws XmlPullParserException parsing issue
     * @throws
     * IOException io issue
     */
    int nextTag()
        throws XmlPullParserException, IOException;

}
