286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 286N/A * The XMLStreamReader interface allows forward, read-only access to XML. 286N/A * It is designed to be the lowest level and most efficient way to 286N/A * <p> The XMLStreamReader is designed to iterate over XML using 286N/A * next() and hasNext(). The data can be accessed using methods such as getEventType(), 286N/A * getNamespaceURI(), getLocalName() and getText(); 286N/A * <p> The <a href="#next()">next()</a> method causes the reader to read the next parse event. 286N/A * The next() method returns an integer which identifies the type of event just read. 286N/A * <p> The event type can be determined using <a href="#getEventType()">getEventType()</a>. 286N/A * <p> Parsing events are defined as the XML Declaration, a DTD, 286N/A * start tag, character data, white space, end tag, comment, 286N/A * or processing instruction. An attribute or namespace event may be encountered 286N/A * at the root level of a document as the result of a query operation. 286N/A * <p>For XML 1.0 compliance an XML processor must pass the 286N/A * identifiers of declared unparsed entities, notation declarations and their 286N/A * associated identifiers to the application. This information is 286N/A * provided through the property API on this interface. 286N/A * The following two properties allow access to this information: 286N/A * When the current event is a DTD the following call will return a 286N/A * <code>List l = (List) getProperty("javax.xml.stream.notations");</code> 286N/A * The following call will return a list of entity declarations: 286N/A * <code>List l = (List) getProperty("javax.xml.stream.entities");</code> 286N/A * These properties can only be accessed during a DTD event and 286N/A * are defined to return null if the information is not available. 286N/A * <p>The following table describes which methods are valid in what state. 286N/A * If a method is called in an invalid state the method will throw a 286N/A * java.lang.IllegalStateException. 286N/A * <table border="2" rules="all" cellpadding="4"> 286N/A * <th align="center" colspan="2"> 286N/A * Valid methods for each state 286N/A * <th>Valid Methods</th> 286N/A * <td> All States </td> 286N/A * <td> getProperty(), hasNext(), require(), close(), 286N/A * getNamespaceURI(), isStartElement(), 286N/A * isEndElement(), isCharacters(), isWhiteSpace(), 286N/A * getNamespaceContext(), getEventType(),getLocation(), 286N/A * <td> START_ELEMENT </td> 286N/A * <td> next(), getName(), getLocalName(), hasName(), getPrefix(), 286N/A * getAttributeXXX(), isAttributeSpecified(), 286N/A * getElementText(), nextTag() 286N/A * <td> next(), nextTag() 286N/A * getAttributeXXX(), isAttributeSpecified(), 286N/A * <td> next(), nextTag() 286N/A * <td> END_ELEMENT </td> 286N/A * <td> next(), getName(), getLocalName(), hasName(), getPrefix(), 286N/A * getNamespaceXXX(), nextTag() 286N/A * <td> CHARACTERS </td> 286N/A * <td> next(), getTextXXX(), nextTag() </td> 286N/A * <td> next(), getTextXXX(), nextTag() </td> 286N/A * <td> next(), getTextXXX(), nextTag() </td> 286N/A * <td> next(), getTextXXX(), nextTag() </td> 286N/A * <td> START_DOCUMENT </td> 286N/A * <td> next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(), 286N/A * getCharacterEncodingScheme(), nextTag()</td> 286N/A * <td> END_DOCUMENT </td> 286N/A * <td> PROCESSING_INSTRUCTION </td> 286N/A * <td> next(), getPITarget(), getPIData(), nextTag() </td> 286N/A * <td> ENTITY_REFERENCE </td> 286N/A * <td> next(), getLocalName(), getText(), nextTag() </td> 286N/A * <td> next(), getText(), nextTag() </td> 286N/A * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 286N/A * @param name The name of the property, may not be null 286N/A * @return The value of the property 286N/A * @throws IllegalArgumentException if name is null 286N/A * Get next parsing event - a processor may return all contiguous 286N/A * character data in a single chunk, or it may split it into several chunks. 286N/A * element content must be coalesced and only one CHARACTERS event 286N/A * must be returned for contiguous element content or 286N/A * By default entity references must be 286N/A * expanded and reported transparently to the application. 286N/A * An exception will be thrown if an entity reference cannot be expanded. 286N/A * If element content is empty (i.e. content is "") then no CHARACTERS event will be reported. 286N/A * <p>Given the following XML:<br> 286N/A * <foo><!--description-->content text<![CDATA[<greeting>Hello</greeting>]]>other content</foo><br> 286N/A * The behavior of calling next() when being on foo will be:<br> 286N/A * 1- the comment (COMMENT)<br> 286N/A * 2- then the characters section (CHARACTERS)<br> 286N/A * 3- then the CDATA section (another CHARACTERS)<br> 286N/A * 4- then the next characters section (another CHARACTERS)<br> 286N/A * 5- then the END_ELEMENT<br> 286N/A * <p><b>NOTE:</b> empty element (such as <tag/>) will be reported 286N/A * with two separate events: START_ELEMENT, END_ELEMENT - This preserves 286N/A * parsing equivalency of empty element to <tag></tag>. 286N/A * This method will throw an IllegalStateException if it is called after hasNext() returns false. 286N/A * @return the integer code corresponding to the current parse event 286N/A * @throws NoSuchElementException if this is called when hasNext() returns false 286N/A * @throws XMLStreamException if there is an error processing the underlying XML source 286N/A * Test if the current event is of the given type and if the namespace and name match the current 286N/A * namespace and name of the current event. If the namespaceURI is null it is not checked for equality, 286N/A * if the localName is null it is not checked for equality. 286N/A * @param type the event type 286N/A * @param namespaceURI the uri of the event, may be null 286N/A * @param localName the localName of the event, may be null 286N/A * @throws XMLStreamException if the required values are not matched. 286N/A * Reads the content of a text-only element, an exception is thrown if this is 286N/A * not a text-only element. 286N/A * Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content. 286N/A * <br /> Precondition: the current event is START_ELEMENT. 286N/A * <br /> Postcondition: the current event is the corresponding END_ELEMENT. 286N/A * <br />The method does the following (implementations are free to optimized 286N/A * but must do equivalent processing): 286N/A * if(getEventType() != XMLStreamConstants.START_ELEMENT) { 286N/A * throw new XMLStreamException( 286N/A * "parser must be on START_ELEMENT to read next text", getLocation()); 286N/A * int eventType = next(); 286N/A * StringBuffer content = new StringBuffer(); 286N/A * while(eventType != XMLStreamConstants.END_ELEMENT ) { 286N/A * if(eventType == XMLStreamConstants.CHARACTERS 286N/A * || eventType == XMLStreamConstants.CDATA 286N/A * || eventType == XMLStreamConstants.SPACE 286N/A * || eventType == XMLStreamConstants.ENTITY_REFERENCE) { 286N/A * buf.append(getText()); 286N/A * } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION 286N/A * || eventType == XMLStreamConstants.COMMENT) { 286N/A * } else if(eventType == XMLStreamConstants.END_DOCUMENT) { 286N/A * throw new XMLStreamException( 286N/A * "unexpected end of document when reading element text content", this); 286N/A * } else if(eventType == XMLStreamConstants.START_ELEMENT) { 286N/A * throw new XMLStreamException( 286N/A * "element text content may not contain START_ELEMENT", getLocation()); 286N/A * throw new XMLStreamException( 286N/A * "Unexpected event type "+eventType, getLocation()); 286N/A * return buf.toString(); 286N/A * @throws XMLStreamException if the current event is not a START_ELEMENT 286N/A * or if a non text element is encountered 286N/A * Skips any white space (isWhiteSpace() returns true), COMMENT, 286N/A * or PROCESSING_INSTRUCTION, 286N/A * until a START_ELEMENT or END_ELEMENT is reached. 286N/A * If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT 286N/A * are encountered, an exception is thrown. This method should 286N/A * be used when processing element-only content seperated by white space. 286N/A * <br /> Precondition: none 286N/A * <br /> Postcondition: the current event is START_ELEMENT or END_ELEMENT 286N/A * and cursor may have moved over any whitespace event. 286N/A * <br />Essentially it does the following (implementations are free to optimized 286N/A * but must do equivalent processing): 286N/A * int eventType = next(); 286N/A * while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace 286N/A * || (eventType == XMLStreamConstants.CDATA && isWhiteSpace()) 286N/A * || eventType == XMLStreamConstants.SPACE 286N/A * || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION 286N/A * || eventType == XMLStreamConstants.COMMENT 286N/A * if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) { 286N/A * throw new String XMLStreamException("expected start or end tag", getLocation()); 286N/A * @return the event type of the element read (START_ELEMENT or END_ELEMENT) 286N/A * @throws XMLStreamException if the current event is not white space, PROCESSING_INSTRUCTION, 286N/A * START_ELEMENT or END_ELEMENT 286N/A * @throws NoSuchElementException if this is called when hasNext() returns false 286N/A * Returns true if there are more parsing events and false 286N/A * if there are no more events. This method will return 286N/A * false if the current state of the XMLStreamReader is 286N/A * @return true if there are more events, false otherwise 286N/A * @throws XMLStreamException if there is a fatal error detecting the next state 286N/A * Frees any resources associated with this Reader. This method does not close the 286N/A * underlying input source. 286N/A * @throws XMLStreamException if there are errors freeing associated resources 286N/A * Return the uri for the given prefix. 286N/A * The uri returned depends on the current state of the processor. 286N/A * <p><strong>NOTE:</strong>The 'xml' prefix is bound as defined in 286N/A * <p><strong>NOTE:</strong> The 'xmlns' prefix must be resolved to following namespace 286N/A * @param prefix The prefix to lookup, may not be null 286N/A * @return the uri bound to the given prefix or null if it is not bound 286N/A * @throws IllegalArgumentException if the prefix is null 286N/A * Returns true if the cursor points to a start tag (otherwise false) 286N/A * @return true if the cursor points to a start tag, false otherwise 286N/A * Returns true if the cursor points to an end tag (otherwise false) 286N/A * @return true if the cursor points to an end tag, false otherwise 286N/A * Returns true if the cursor points to a character data event 286N/A * @return true if the cursor points to character data, false otherwise 286N/A * Returns true if the cursor points to a character data event 286N/A * that consists of all whitespace 286N/A * @return true if the cursor points to all whitespace, false otherwise 286N/A * Returns the normalized attribute value of the 286N/A * attribute with the namespace and localName 286N/A * If the namespaceURI is null the namespace 286N/A * is not checked for equality 286N/A * @param namespaceURI the namespace of the attribute 286N/A * @param localName the local name of the attribute, cannot be null 286N/A * @return returns the value of the attribute , returns null if not found 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns the count of attributes on this START_ELEMENT, 286N/A * this method is only valid on a START_ELEMENT or ATTRIBUTE. This 286N/A * count excludes namespace definitions. Attribute indices are 286N/A * @return returns the number of attributes 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A /** Returns the qname of the attribute at the provided index 286N/A * @param index the position of the attribute 286N/A * @return the QName of the attribute 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns the namespace of the attribute at the provided 286N/A * @param index the position of the attribute 286N/A * @return the namespace URI (can be null) 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns the localName of the attribute at the provided 286N/A * @param index the position of the attribute 286N/A * @return the localName of the attribute 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns the prefix of this attribute at the 286N/A * @param index the position of the attribute 286N/A * @return the prefix of the attribute 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns the XML type of the attribute at the provided 286N/A * @param index the position of the attribute 286N/A * @return the XML type of the attribute 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns the value of the attribute at the 286N/A * @param index the position of the attribute 286N/A * @return the attribute value 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns a boolean which indicates if this 286N/A * attribute was created by default 286N/A * @param index the position of the attribute 286N/A * @return true if this is a default attribute 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or ATTRIBUTE 286N/A * Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT, 286N/A * this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE. On 286N/A * an END_ELEMENT the count is of the namespaces that are about to go 286N/A * out of scope. This is the equivalent of the information reported 286N/A * by SAX callback for an end element event. 286N/A * @return returns the number of namespace declarations on this specific element 286N/A * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE 286N/A * Returns the prefix for the namespace declared at the 286N/A * index. Returns null if this is the default namespace 286N/A * @param index the position of the namespace declaration 286N/A * @return returns the namespace prefix 286N/A * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE 286N/A * Returns the uri for the namespace declared at the 286N/A * @param index the position of the namespace declaration 286N/A * @return returns the namespace uri 286N/A * @throws IllegalStateException if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE 286N/A * Returns a read only namespace context for the current 286N/A * position. The context is transient and only valid until 286N/A * a call to next() changes the state of the reader. 286N/A * @return return a namespace context 286N/A * Returns a reader that points to the current start element 286N/A * and all of its contents. Throws an XMLStreamException if the 286N/A * cursor does not point to a START_ELEMENT.<p> 286N/A * The sub stream is read from it MUST be read before the parent stream is 286N/A * moved on, if not any call on the sub stream will cause an XMLStreamException to be 286N/A * thrown. The parent stream will always return the same result from next() 286N/A * whatever is done to the sub stream. 286N/A * @return an XMLStreamReader which points to the next element 286N/A // public XMLStreamReader subReader() throws XMLStreamException; 286N/A * Allows the implementation to reset and reuse any underlying tables 286N/A // public void recycle() throws XMLStreamException; 286N/A * Returns an integer code that indicates the type 286N/A * of the event the cursor is pointing to. 286N/A * Returns the current value of the parse event as a string, 286N/A * this returns the string value of a CHARACTERS event, 286N/A * returns the value of a COMMENT, the replacement value 286N/A * for an ENTITY_REFERENCE, the string value of a CDATA section, 286N/A * the string value for a SPACE event, 286N/A * or the String value of the internal subset of the DTD. 286N/A * If an ENTITY_REFERENCE has been resolved, any character data 286N/A * will be reported as CHARACTERS events. 286N/A * @return the current text or null 286N/A * @throws java.lang.IllegalStateException if this state is not 286N/A * Returns an array which contains the characters from this event. 286N/A * This array should be treated as read-only and transient. I.e. the array will 286N/A * contain the text characters until the XMLStreamReader moves on to the next event. 286N/A * Attempts to hold onto the character array beyond that time or modify the 286N/A * contents of the array are breaches of the contract for this interface. 286N/A * @return the current text or an empty array 286N/A * @throws java.lang.IllegalStateException if this state is not 286N/A * Gets the the text associated with a CHARACTERS, SPACE or CDATA event. 286N/A * Text starting a "sourceStart" is copied into "target" starting at "targetStart". 286N/A * Up to "length" characters are copied. The number of characters actually copied is returned. 286N/A * The "sourceStart" argument must be greater or equal to 0 and less than or equal to 286N/A * the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0. 286N/A * If the number of characters actually copied is less than the "length", then there is no more text. 286N/A * Otherwise, subsequent calls need to be made until all text has been retrieved. For example: 286N/A * char[] myBuffer = new char[ length ]; 286N/A * for ( int sourceStart = 0 ; ; sourceStart += length ) 286N/A * int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length ); 286N/A * if (nCopied < length) 286N/A * XMLStreamException may be thrown if there are any XML errors in the underlying source. 286N/A * The "targetStart" argument must be greater than or equal to 0 and less than the length of "target", 286N/A * Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target". 286N/A * @param sourceStart the index of the first character in the source array to copy 286N/A * @param target the destination array 286N/A * @param targetStart the start offset in the target array 286N/A * @param length the number of characters to copy 286N/A * @return the number of characters actually copied 286N/A * @throws XMLStreamException if the underlying XML source is not well-formed 286N/A * @throws IndexOutOfBoundsException if targetStart < 0 or > than the length of target 286N/A * @throws IndexOutOfBoundsException if length < 0 or targetStart + length > length of target 286N/A * @throws UnsupportedOperationException if this method is not supported 286N/A * @throws NullPointerException is if target is null 286N/A * Gets the text associated with a CHARACTERS, SPACE or CDATA event. Allows the underlying 286N/A * implementation to return the text as a stream of characters. The reference to the 286N/A * Reader returned by this method is only valid until next() is called. 286N/A * All characters must have been checked for well-formedness. 286N/A * <p> This method is optional and will throw UnsupportedOperationException if it is not supported. 286N/A * @throws UnsupportedOperationException if this method is not supported 286N/A * @throws IllegalStateException if this is not a valid text state 286N/A //public Reader getTextStream(); 286N/A * Returns the offset into the text character array where the first 286N/A * character (of this text event) is stored. 286N/A * @throws java.lang.IllegalStateException if this state is not 286N/A * Returns the length of the sequence of characters for this 286N/A * Text event within the text character array. 286N/A * @throws java.lang.IllegalStateException if this state is not 286N/A * Return input encoding if known or null if unknown. 286N/A * @return the encoding of this instance or null 286N/A * Return true if the current event has text, false otherwise 286N/A * The following events have text: 286N/A * CHARACTERS,DTD ,ENTITY_REFERENCE, COMMENT, SPACE 286N/A * Return the current location of the processor. 286N/A * If the Location is unknown the processor should return 286N/A * an implementation of Location that returns -1 for the 286N/A * location and null for the publicId and systemId. 286N/A * The location information is only valid until next() is 286N/A * Returns a QName for the current START_ELEMENT or END_ELEMENT event 286N/A * @return the QName for the current START_ELEMENT or END_ELEMENT event 286N/A * @throws IllegalStateException if this is not a START_ELEMENT or 286N/A * Returns the (local) name of the current event. 286N/A * For START_ELEMENT or END_ELEMENT returns the (local) name of the current element. 286N/A * For ENTITY_REFERENCE it returns entity name. 286N/A * The current event must be START_ELEMENT or END_ELEMENT, 286N/A * @return the localName 286N/A * @throws IllegalStateException if this not a START_ELEMENT, 286N/A * END_ELEMENT or ENTITY_REFERENCE 286N/A * returns true if the current event has a name (is a START_ELEMENT or END_ELEMENT) 286N/A * returns false otherwise 286N/A * If the current event is a START_ELEMENT or END_ELEMENT this method 286N/A * returns the URI of the prefix or the default namespace. 286N/A * Returns null if the event does not have a prefix. 286N/A * @return the URI bound to this elements prefix, the default namespace, or null 286N/A * Returns the prefix of the current event or null if the event does not have a prefix 286N/A * @return the prefix or null 286N/A * Get the xml version declared on the xml declaration 286N/A * Returns null if none was declared 286N/A * @return the XML version or null 286N/A * Get the standalone declaration from the xml declaration 286N/A * @return true if this is standalone, or false otherwise 286N/A * Checks if standalone was set in the document 286N/A * @return true if standalone was set in the document, or false otherwise 286N/A * Returns the character encoding declared on the xml declaration 286N/A * Returns null if none was declared 286N/A * @return the encoding declared in the document or null 286N/A * Get the target of a processing instruction 286N/A * @return the target or null 286N/A * Get the data section of a processing instruction 286N/A * @return the data or null