/*
* Portions Copyright 2000-2009 Sun Microsystems, Inc. All Rights
* Reserved. Use is subject to license terms.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program 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.
*
* This program 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 at /legal/license.txt).
*
* 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 Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
package javax.xml.stream;
/**
* 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 was
* provided through the property API on this interface.
* The following two properties allowed access to this information:
* "javax.xml.stream.notations" and "javax.xml.stream.entities".
* These properties are not supported in the JSR 280 subset of StAX;
* calls to <code>getProperty("javax.xml.stream.notations");</code>
* or <code>getProperty("javax.xml.stream.entities");</code> will
* always return <code>null</code>.
*
* <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" width=100%>
* <tr>
* <th align="center" colspan="2">
* Valid methods for each state
* </th>
* </tr>
* <tr>
* <th width=13%>Event Type</th>
* <th width=28%>Valid Methods</th>
* </tr>
* <tr>
* <td> All States </td>
* <td> getProperty(), hasNext(), require(), close(),
* getNamespaceURI(), isWhiteSpace(),
* getEventType(),getLocation()</td>
* </tr>
* <tr>
* <td> START_ELEMENT </td>
* <td> next(), getLocalName(), 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(), getLocalName(), 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>
* </table>
*
* @version 1.0
* @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
* @see XMLInputFactory
* @see XMLStreamWriter
*/
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 <code>null</code>
* @return The value of the property
* @throws IllegalArgumentException if name is <code>null</code>
*/
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 <code>true</code>
* 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>
* <foo><!--description-->content text<![CDATA[<greeting>Hello<
* /greeting>]]>other content</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 <tag/>) will be reported
* with two separate events: START_ELEMENT, END_ELEMENT - This preserves
* parsing equivalency of empty element to <tag></tag>.
*
* @return the integer code corresponding to the current parse event
* @throws NoSuchElementException if this is called when hasNext() returns
* <code>false</code>
* @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 <code>null</code> it is not checked for equality, if the
* localName is <code>null</code> it is not checked for equality.
* @param type the event type
* @param namespaceURI the uri of the event, may be <code>null</code>
* @param localName the localName of the event, may be <code>null</code>
* @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 optimize
* 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 <code>true</code>), 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 separated 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
* optimize but must do equivalent processing):
* <pre>
* int eventType = next();
* // skip whitespace
* while((eventType == XMLStreamConstants.CHARACTERS
* && isWhiteSpace())
* || (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,
* COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT or END_ELEMENT
* @throws NoSuchElementException if this is called when hasNext() returns
* <code>false</code>
*/
public int nextTag() throws XMLStreamException;
/**
* Returns <code>true</code> if there are more parsing events and
* <code>false</code> if there are no more events. This method will return
* <code>false</code> if the current state of the XMLStreamReader is
* END_DOCUMENT
* @return <code>true</code> if there are more events, <code>false</code>
* 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 <code>null</code>
* @return the uri bound to the given prefix or <code>null</code> if it is
* not bound
* @throws IllegalArgumentException if the prefix is <code>null</code>
*/
public String getNamespaceURI(String prefix);
/**
* Returns <code>true</code> if the cursor points to a character data event
* that consists of all whitespace
* @return <code>true</code> if the cursor points to all whitespace,
* <code>false</code> otherwise
*/
public boolean isWhiteSpace();
/**
* Returns the normalized attribute value of the attribute with the namespace
* and localName. If the namespaceURI is <code>null</code> it is not checked
* for equality, i.e. only the localName part of an attribute name will be
* compared. A value of <code>""</code> (empty String) is interpreted
* to mean 'no namespace', i.e. any matching attribute must have no
* namespace specified.
* @param namespaceURI the namespace of the attribute
* @param localName the local name of the attribute, cannot be
* <code>null</code>
* @return returns the value of the attribute , returns <code>null</code> 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 when <code>isNamespaceAware</code>
* is true; when <code>isNamespaceAware</code> is false, the attribute
* count includes <code>xmlns</code> and <code>xmlns.*</code> attributes.
* 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 namespace of the attribute at the provided
* index
* @param index the position of the attribute
* @return the namespace URI (can be <code>null</code>)
* @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE
* @throws IndexOutOfBoundsException if the index is invalid or if there is
* no attribute at the specified index.
*/
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
* @throws IndexOutOfBoundsException if the index is invalid or if there is
* no attribute at the specified index.
*/
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
* @throws IndexOutOfBoundsException if the index is invalid or if there is
* no attribute at the specified index.
*/
public String getAttributePrefix(int index);
/**
* Returns the XML type of the attribute at the provided
* index (see XML 1.0 Specification, section 3.3.1)
* @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
* @throws IndexOutOfBoundsException if the index is invalid or if there is
* no attribute at the specified index.
*/
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
* @throws IndexOutOfBoundsException if the index is invalid or if there is
* no attribute at the specified index.
*/
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 <code>true</code> 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
* <code>null</code> 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
* @throws IndexOutOfBoundsException if the index is invalid or if there is
* no namespace at the specified index
*/
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 or <code>null</code> if none exists
* @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT
* or NAMESPACE
*/
public String getNamespaceURI(int index);
/**
* 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 <code>null</code>
* @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.
* @return the current text or an empty array
* @throws java.lang.IllegalStateException if this state is not
* a valid text state.
*/
public char[] getTextCharacters();
/**
* Returns the offset into the text character array where the first character
* (of this text event) is stored.
* @throws java.lang.IllegalStateException if this state is not a valid text
* state.
*/
public int getTextStart();
/**
* Returns the length of the sequence of characters for this Text event within
* the text character array.
* @throws java.lang.IllegalStateException if this state is not a valid text
* state.
*/
public int getTextLength();
/**
* Return input encoding if known or <code>null</code> if unknown.
* @return the encoding of this instance or <code>null</code>.
* <i>Note: the source of the encoding is that that may have been provided by
* an application to the factory.</i>
*/
public String getEncoding();
/**
* Return the current location of the processor.
* If the Location is unknown the processor should return an implementation
* of Location that returns -1 for the location and <code>null</code> for the
* publicId and systemId. The location information is only valid until next()
* is called.
*/
public Location getLocation();
/**
* Returns the (local) name of the current event.
* For START_ELEMENT or END_ELEMENT returns the (local) name of the current
* element. For ENTITY_REFERENCE it returns entity name.
* The current event must be START_ELEMENT or END_ELEMENT,
* or ENTITY_REFERENCE
* @return the localName
* @throws IllegalStateException if this not a START_ELEMENT,
* END_ELEMENT or ENTITY_REFERENCE
*/
public String getLocalName();
/**
* If the current event is a START_ELEMENT or END_ELEMENT this method
* returns the URI of the prefix or the default namespace.
* Returns <code>null</code> if the event does not have a prefix.
* @return the URI bound to this elements prefix, the default namespace, or
* <code>null</code>
*/
public String getNamespaceURI();
/**
* Returns the prefix of the current event or <code>null</code> if the event
* does not have a prefix
* @return the prefix or <code>null</code>
*/
public String getPrefix();
/**
* Get the xml version declared on the xml declaration.
* Returns <code>null</code> if none was declared.
* @return the XML version or <code>null</code>
*/
public String getVersion();
/**
* Get the standalone declaration from the xml declaration
* @return <code>true</code> if this is standalone, or <code>false</code>
* otherwise
*/
public boolean isStandalone();
/**
* Checks if standalone was set in the document
* @return <code>true</code> if standalone was set in the document, or
* <code>false</code> otherwise
*/
public boolean standaloneSet();
/**
* Returns the character encoding declared on the xml declaration
* Returns <code>null</code> if none was declared
* @return the encoding declared in the document or <code>null</code>
*/
public String getCharacterEncodingScheme();
/**
* Get the target of a processing instruction
* @return the target or <code>null</code>
*/
public String getPITarget();
/**
* Get the data section of a processing instruction
* @return the data or <code>null</code>
*/
public String getPIData();
}