/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.

 */

package javax.xml.stream;

import java.io.Reader;

import javax.xml.namespace.NamespaceContext;

import javax.xml.namespace.QName;

/**

 *  The XMLStreamReader interface allows forward, read-only access to XML.

 *  It is designed to be the lowest level and most efficient way to

 *  read XML data.

 *

 * <p> The XMLStreamReader is designed to iterate over XML using

 * next() and hasNext().  The data can be accessed using methods such as getEventType(),

 * getNamespaceURI(), getLocalName() and getText();

 *

 * <p> The <a href="#next()">next()</a> method causes the reader to read the next parse event.

 * The next() method returns an integer which identifies the type of event just read.

 * <p> The event type can be determined using <a href="#getEventType()">getEventType()</a>.

 * <p> Parsing events are defined as the XML Declaration, a DTD,

 * start tag, character data, white space, end tag, comment,

 * or processing instruction.  An attribute or namespace event may be encountered

 * at the root level of a document as the result of a query operation.

 *

 * <p>For XML 1.0 compliance an XML processor must pass the

 * identifiers of declared unparsed entities, notation declarations and their

 * associated identifiers to the application.  This information is

 * provided through the property API on this interface.

 * The following two properties allow access to this information:

 * javax.xml.stream.notations and javax.xml.stream.entities.

 * When the current event is a DTD the following call will return a

 * list of Notations

 *  <code>List l = (List) getProperty("javax.xml.stream.notations");</code>

 * The following call will return a list of entity declarations:

 * <code>List l = (List) getProperty("javax.xml.stream.entities");</code>

 * These properties can only be accessed during a DTD event and

 * are defined to return null if the information is not available.

 *

 * <p>The following table describes which methods are valid in what state.

 * If a method is called in an invalid state the method will throw a

 * java.lang.IllegalStateException.

 *

 * <table border="2" rules="all" cellpadding="4">

 *   <thead>

 *     <tr>

 *       <th align="center" colspan="2">

 *         Valid methods for each state

 *       </th>

 *     </tr>

 *   </thead>

 *   <tbody>

 *     <tr>

 *       <th>Event Type</th>

 *       <th>Valid Methods</th>

 *     </tr>

 *     <tr>

 *       <td> All States  </td>

 *       <td> getProperty(), hasNext(), require(), close(),

 *            getNamespaceURI(), isStartElement(),

 *            isEndElement(), isCharacters(), isWhiteSpace(),

 *            getNamespaceContext(), getEventType(),getLocation(),

 *            hasText(), hasName()

 *       </td>

 *     </tr>

 *     <tr>

 *       <td> START_ELEMENT  </td>

 *       <td> next(), getName(), getLocalName(), hasName(), getPrefix(),

 *            getAttributeXXX(), isAttributeSpecified(),

 *            getNamespaceXXX(),

 *            getElementText(), nextTag()

 *       </td>

 *     </tr>

 *       <td> ATTRIBUTE  </td>

 *       <td> next(), nextTag()

 *            getAttributeXXX(), isAttributeSpecified(),

 *       </td>

 *     </tr>

 *     </tr>

 *       <td> NAMESPACE  </td>

 *       <td> next(), nextTag()

 *            getNamespaceXXX()

 *       </td>

 *     </tr>

 *     <tr>

 *       <td> END_ELEMENT  </td>

 *       <td> next(), getName(), getLocalName(), hasName(), getPrefix(),

 *            getNamespaceXXX(), nextTag()

 *      </td>

 *     </tr>

 *     <tr>

 *       <td> CHARACTERS  </td>

 *       <td> next(), getTextXXX(), nextTag() </td>

 *     </tr>

 *     <tr>

 *       <td> CDATA  </td>

 *       <td> next(), getTextXXX(), nextTag() </td>

 *     </tr>

 *     <tr>

 *       <td> COMMENT  </td>

 *       <td> next(), getTextXXX(), nextTag() </td>

 *     </tr>

 *     <tr>

 *       <td> SPACE  </td>

 *       <td> next(), getTextXXX(), nextTag() </td>

 *     </tr>

 *     <tr>

 *       <td> START_DOCUMENT  </td>

 *       <td> next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(),

 *            getCharacterEncodingScheme(), nextTag()</td>

 *     </tr>

 *     <tr>

 *       <td> END_DOCUMENT  </td>

 *       <td> close()</td>

 *     </tr>

 *     <tr>

 *       <td> PROCESSING_INSTRUCTION  </td>

 *       <td> next(), getPITarget(), getPIData(), nextTag() </td>

 *     </tr>

 *     <tr>

 *       <td> ENTITY_REFERENCE  </td>

 *       <td> next(), getLocalName(), getText(), nextTag() </td>

 *     </tr>

 *     <tr>

 *       <td> DTD  </td>

 *       <td> next(), getText(), nextTag() </td>

 *     </tr>

 *   </tbody>

 *  </table>

 *

 * @version 1.0

 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.

 * @see javax.xml.stream.events.XMLEvent

 * @see XMLInputFactory

 * @see XMLStreamWriter

 * @since 1.6

 */

public interface XMLStreamReader extends XMLStreamConstants {

  /**

   * Get the value of a feature/property from the underlying implementation

   * @param name The name of the property, may not be null

   * @return The value of the property

   * @throws IllegalArgumentException if name is null

   */

  public Object getProperty(java.lang.String name) throws java.lang.IllegalArgumentException;

  /**

   * Get next parsing event - a processor may return all contiguous

   * character data in a single chunk, or it may split it into several chunks.

   * If the property javax.xml.stream.isCoalescing is set to true

   * element content must be coalesced and only one CHARACTERS event

   * must be returned for contiguous element content or

   * CDATA Sections.

   *

   * By default entity references must be

   * expanded and reported transparently to the application.

   * An exception will be thrown if an entity reference cannot be expanded.

   * If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.

   *

   * <p>Given the following XML:<br>

   * &lt;foo>&lt;!--description-->content text&lt;![CDATA[&lt;greeting>Hello&lt;/greeting>]]>other content&lt;/foo><br>

   * The behavior of calling next() when being on foo will be:<br>

   * 1- the comment (COMMENT)<br>

   * 2- then the characters section (CHARACTERS)<br>

   * 3- then the CDATA section (another CHARACTERS)<br>

   * 4- then the next characters section (another CHARACTERS)<br>

   * 5- then the END_ELEMENT<br>

   *

   * <p><b>NOTE:</b> empty element (such as &lt;tag/>) will be reported

   *  with  two separate events: START_ELEMENT, END_ELEMENT - This preserves

   *   parsing equivalency of empty element to <tag></tag>.

   *

   * This method will throw an IllegalStateException if it is called after hasNext() returns false.

   * @see javax.xml.stream.events.XMLEvent

   * @return the integer code corresponding to the current parse event

   * @throws NoSuchElementException if this is called when hasNext() returns false

   * @throws XMLStreamException  if there is an error processing the underlying XML source

   */

  public int next() throws XMLStreamException;

  /**

   * Test if the current event is of the given type and if the namespace and name match the current

   * namespace and name of the current event.  If the namespaceURI is null it is not checked for equality,

   * if the localName is null it is not checked for equality.

   * @param type the event type

   * @param namespaceURI the uri of the event, may be null

   * @param localName the localName of the event, may be null

   * @throws XMLStreamException if the required values are not matched.

   */

  public void require(int type, String namespaceURI, String localName) throws XMLStreamException;

  /**

   * Reads the content of a text-only element, an exception is thrown if this is

   * not a text-only element.

   * Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.

   * <br /> Precondition: the current event is START_ELEMENT.

   * <br /> Postcondition: the current event is the corresponding END_ELEMENT.

   *

   * <br />The method does the following (implementations are free to optimized

   * but must do equivalent processing):

   * <pre>

   * if(getEventType() != XMLStreamConstants.START_ELEMENT) {

   * throw new XMLStreamException(

   * "parser must be on START_ELEMENT to read next text", getLocation());

   * }

   * int eventType = next();

   * StringBuffer content = new StringBuffer();

   * while(eventType != XMLStreamConstants.END_ELEMENT ) {

   * if(eventType == XMLStreamConstants.CHARACTERS

   * || eventType == XMLStreamConstants.CDATA

   * || eventType == XMLStreamConstants.SPACE

   * || eventType == XMLStreamConstants.ENTITY_REFERENCE) {

   * buf.append(getText());

   * } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION

   * || eventType == XMLStreamConstants.COMMENT) {

   * // skipping

   * } else if(eventType == XMLStreamConstants.END_DOCUMENT) {

   * throw new XMLStreamException(

   * "unexpected end of document when reading element text content", this);

   * } else if(eventType == XMLStreamConstants.START_ELEMENT) {

   * throw new XMLStreamException(

   * "element text content may not contain START_ELEMENT", getLocation());

   * } else {

   * throw new XMLStreamException(

   * "Unexpected event type "+eventType, getLocation());

   * }

   * eventType = next();

   * }

   * return buf.toString();

   * </pre>

   *

   * @throws XMLStreamException if the current event is not a START_ELEMENT

   * or if a non text element is encountered

   */

  public String getElementText() throws XMLStreamException;

  /**

   * Skips any white space (isWhiteSpace() returns true), COMMENT,

   * or PROCESSING_INSTRUCTION,

   * until a START_ELEMENT or END_ELEMENT is reached.

   * If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT

   * are encountered, an exception is thrown. This method should

   * be used when processing element-only content seperated by white space.

   *

   * <br /> Precondition: none

   * <br /> Postcondition: the current event is START_ELEMENT or END_ELEMENT

   * and cursor may have moved over any whitespace event.

   *

   * <br />Essentially it does the following (implementations are free to optimized

   * but must do equivalent processing):

   * <pre>

   * int eventType = next();

   * while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace

   * || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())

   * // skip whitespace

   * || eventType == XMLStreamConstants.SPACE

   * || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION

   * || eventType == XMLStreamConstants.COMMENT

   * ) {

   * eventType = next();

   * }

   * if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {

   * throw new String XMLStreamException("expected start or end tag", getLocation());

   * }

   * return eventType;

   * </pre>

   *

   * @return the event type of the element read (START_ELEMENT or END_ELEMENT)

   * @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION,

   * START_ELEMENT or END_ELEMENT

   * @throws NoSuchElementException if this is called when hasNext() returns false

   */

  public int nextTag() throws XMLStreamException;

  /**

   * Returns true if there are more parsing events and false

   * if there are no more events.  This method will return

   * false if the current state of the XMLStreamReader is

   * END_DOCUMENT

   * @return true if there are more events, false otherwise

   * @throws XMLStreamException if there is a fatal error detecting the next state

   */

  public boolean hasNext() throws XMLStreamException;

  /**

   * Frees any resources associated with this Reader.  This method does not close the

   * underlying input source.

   * @throws XMLStreamException if there are errors freeing associated resources

   */

  public void close() throws XMLStreamException;

  /**

   * Return the uri for the given prefix.

   * The uri returned depends on the current state of the processor.

   *

   * <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".

   *

   * <p><strong>NOTE:</strong> The 'xmlns' prefix must be resolved to following namespace

   * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>

   * @param prefix The prefix to lookup, may not be null

   * @return the uri bound to the given prefix or null if it is not bound

   * @throws IllegalArgumentException if the prefix is null

   */

  public String getNamespaceURI(String prefix);

  /**

   * Returns true if the cursor points to a start tag (otherwise false)

   * @return true if the cursor points to a start tag, false otherwise

   */

  public boolean isStartElement();

  /**

   * Returns true if the cursor points to an end tag (otherwise false)

   * @return true if the cursor points to an end tag, false otherwise

   */

  public boolean isEndElement();

  /**

   * Returns true if the cursor points to a character data event

   * @return true if the cursor points to character data, false otherwise

   */

  public boolean isCharacters();

  /**

   * Returns true if the cursor points to a character data event

   * that consists of all whitespace

   * @return true if the cursor points to all whitespace, false otherwise

   */

  public boolean isWhiteSpace();

  /**

   * Returns the normalized attribute value of the

   * attribute with the namespace and localName

   * If the namespaceURI is null the namespace

   * is not checked for equality

   * @param namespaceURI the namespace of the attribute

   * @param localName the local name of the attribute, cannot be null

   * @return returns the value of the attribute , returns null if not found

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public String getAttributeValue(String namespaceURI,

                                  String localName);

  /**

   * Returns the count of attributes on this START_ELEMENT,

   * this method is only valid on a START_ELEMENT or ATTRIBUTE.  This

   * count excludes namespace definitions.  Attribute indices are

   * zero-based.

   * @return returns the number of attributes

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public int getAttributeCount();

  /** Returns the qname of the attribute at the provided index

   *

   * @param index the position of the attribute

   * @return the QName of the attribute

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public QName getAttributeName(int index);

  /**

   * Returns the namespace of the attribute at the provided

   * index

   * @param index the position of the attribute

   * @return the namespace URI (can be null)

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public String getAttributeNamespace(int index);

  /**

   * Returns the localName of the attribute at the provided

   * index

   * @param index the position of the attribute

   * @return the localName of the attribute

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public String getAttributeLocalName(int index);

  /**

   * Returns the prefix of this attribute at the

   * provided index

   * @param index the position of the attribute

   * @return the prefix of the attribute

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public String getAttributePrefix(int index);

  /**

   * Returns the XML type of the attribute at the provided

   * index

   * @param index the position of the attribute

   * @return the XML type of the attribute

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public String getAttributeType(int index);

  /**

   * Returns the value of the attribute at the

   * index

   * @param index the position of the attribute

   * @return the attribute value

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public String getAttributeValue(int index);

  /**

   * Returns a boolean which indicates if this

   * attribute was created by default

   * @param index the position of the attribute

   * @return true if this is a default attribute

   * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE

   */

  public boolean isAttributeSpecified(int index);

  /**

   * Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT,

   * this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE. On

   * an END_ELEMENT the count is of the namespaces that are about to go

   * out of scope.  This is the equivalent of the information reported

   * by SAX callback for an end element event.

   * @return returns the number of namespace declarations on this specific element

   * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE

   */

  public int getNamespaceCount();

  /**

   * Returns the prefix for the namespace declared at the

   * index.  Returns null if this is the default namespace

   * declaration

   *

   * @param index the position of the namespace declaration

   * @return returns the namespace prefix

   * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE

   */

  public String getNamespacePrefix(int index);

  /**

   * Returns the uri for the namespace declared at the

   * index.

   *

   * @param index the position of the namespace declaration

   * @return returns the namespace uri

   * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE

   */

  public String getNamespaceURI(int index);

  /**

   * Returns a read only namespace context for the current

   * position.  The context is transient and only valid until

   * a call to next() changes the state of the reader.

   * @return return a namespace context

   */

  public NamespaceContext getNamespaceContext();

  /**

   * Returns a reader that points to the current start element

   * and all of its contents.  Throws an XMLStreamException if the

   * cursor does not point to a START_ELEMENT.<p>

   * The sub stream is read from it MUST be read before the parent stream is

   * moved on, if not any call on the sub stream will cause an XMLStreamException to be

   * thrown.   The parent stream will always return the same result from next()

   * whatever is done to the sub stream.

   * @return an XMLStreamReader which points to the next element

   */

  //  public XMLStreamReader subReader() throws XMLStreamException;

  /**

   * Allows the implementation to reset and reuse any underlying tables

   */

  //  public void recycle() throws XMLStreamException;

  /**

   * Returns an integer code that indicates the type

   * of the event the cursor is pointing to.

   */

  public int getEventType();

  /**

   * Returns the current value of the parse event as a string,

   * this returns the string value of a CHARACTERS event,

   * returns the value of a COMMENT, the replacement value

   * for an ENTITY_REFERENCE, the string value of a CDATA section,

   * the string value for a SPACE event,

   * or the String value of the internal subset of the DTD.

   * If an ENTITY_REFERENCE has been resolved, any character data

   * will be reported as CHARACTERS events.

   * @return the current text or null

   * @throws java.lang.IllegalStateException if this state is not

   * a valid text state.

   */

  public String getText();

  /**

   * Returns an array which contains the characters from this event.

   * This array should be treated as read-only and transient. I.e. the array will

   * contain the text characters until the XMLStreamReader moves on to the next event.

   * Attempts to hold onto the character array beyond that time or modify the

   * contents of the array are breaches of the contract for this interface.