1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* -*- c-basic-offset: 4; indent-tabs-mode: nil; -*- //------100-columns-wide------>|*/ 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project// for license please see accompanying LICENSE.txt file (available also at http://www.xmlpull.org/) 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 4adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage org.xmlpull.v1; 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.InputStream; 7adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.IOException; 8adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.Reader; 9adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 10adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 1187806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * XML Pull Parser is an interface that defines parsing functionality provided 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * in <a href="http://www.xmlpull.org/">XMLPULL V1 API</a> (visit this website to 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * learn more about API and its implementations). 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>There are following different 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * kinds of parser depending on which features are set:<ul> 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li><b>non-validating</b> parser as defined in XML 1.0 spec when 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * FEATURE_PROCESS_DOCDECL is set to true 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li><b>validating parser</b> as defined in XML 1.0 spec when 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * FEATURE_VALIDATION is true (and that implies that FEATURE_PROCESS_DOCDECL is true) 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li>when FEATURE_PROCESS_DOCDECL is false (this is default and 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if different value is required necessary must be changed before parsing is started) 23adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * then parser behaves like XML 1.0 compliant non-validating parser under condition that 24adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <em>no DOCDECL is present</em> in XML documents 25adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (internal entites can still be defined with defineEntityReplacementText()). 2687806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * This mode of operation is intended <b>for operation in constrained environments</b> such as J2ME. 27adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </ul> 28adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 29adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 30adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>There are two key methods: next() and nextToken(). While next() provides 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * access to high level parsing events, nextToken() allows access to lower 32adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * level tokens. 33adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 34adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The current event state of the parser 35adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * can be determined by calling the 36adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="#getEventType()">getEventType()</a> method. 37adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Initially, the parser is in the <a href="#START_DOCUMENT">START_DOCUMENT</a> 38adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * state. 39adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The method <a href="#next()">next()</a> advances the parser to the 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * next event. The int value returned from next determines the current parser 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * state and is identical to the value returned from following calls to 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * getEventType (). 44adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 45adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>Th following event types are seen by next()<dl> 46adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt><a href="#START_TAG">START_TAG</a><dd> An XML start tag was read. 47adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt><a href="#TEXT">TEXT</a><dd> Text content was read; 4887806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * the text content can be retrieved using the getText() method. 4987806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * (when in validating mode next() will not report ignorable whitespace, use nextToken() instead) 50adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt><a href="#END_TAG">END_TAG</a><dd> An end tag was read 51adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt><a href="#END_DOCUMENT">END_DOCUMENT</a><dd> No more events are available 52adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </dl> 53adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 54adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>after first next() or nextToken() (or any other next*() method) 55adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is called user application can obtain 56adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * XML version, standalone and encoding from XML declaration 57adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * in following ways:<ul> 58adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li><b>version</b>: 59adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * getProperty("<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-version">http://xmlpull.org/v1/doc/properties.html#xmldecl-version</a>") 60adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * returns String ("1.0") or null if XMLDecl was not read or if property is not supported 61adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li><b>standalone</b>: 62fda724de28fe86804e6ef6a0afd7ae5be1529083Jesse Wilson * getProperty("<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone">http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone</a>") 63adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * returns Boolean: null if there was no standalone declaration 64adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or if property is not supported 6587806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * otherwise returns Boolean(true) if standalone="yes" and Boolean(false) when standalone="no" 66adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li><b>encoding</b>: obtained from getInputEncoding() 67adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * null if stream had unknown encoding (not set in setInputStream) 68adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and it was not declared in XMLDecl 69adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </ul> 70adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 71adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * A minimal example for using this API may look as follows: 72adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 73adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * import java.io.IOException; 74adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * import java.io.StringReader; 75adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 76adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * import org.xmlpull.v1.XmlPullParser; 77786a6ea948f312a9fc1962659150319cb0ce9e71Jesse Wilson * import org.xmlpull.v1.<a href="XmlPullParserException.html">XmlPullParserException</a>; 78adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * import org.xmlpull.v1.<a href="XmlPullParserFactory.html">XmlPullParserFactory</a>; 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 80adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * public class SimpleXmlPullApp 81adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * { 82adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 83adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * public static void main (String args[]) 84adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * throws XmlPullParserException, IOException 85adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * { 86adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * XmlPullParserFactory factory = XmlPullParserFactory.newInstance(); 87adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * factory.setNamespaceAware(true); 88adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * XmlPullParser xpp = factory.newPullParser(); 89adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 90adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * xpp.<a href="#setInput">setInput</a>( new StringReader ( "<foo>Hello World!</foo>" ) ); 91adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * int eventType = xpp.getEventType(); 92adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * while (eventType != XmlPullParser.END_DOCUMENT) { 93adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if(eventType == XmlPullParser.START_DOCUMENT) { 94adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * System.out.println("Start document"); 95adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } else if(eventType == XmlPullParser.START_TAG) { 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * System.out.println("Start tag "+xpp.<a href="#getName()">getName()</a>); 97adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } else if(eventType == XmlPullParser.END_TAG) { 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * System.out.println("End tag "+xpp.getName()); 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } else if(eventType == XmlPullParser.TEXT) { 100adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * System.out.println("Text "+xpp.<a href="#getText()">getText()</a>); 101adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 102adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * eventType = xpp.next(); 103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 104ccd79e2bb784cdbd89e90a0e4301a707091d446dJesse Wilson * System.out.println("End document"); 105adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 106adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 108adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The above example will generate the following output: 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Start document 112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Start tag foo 113adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Text Hello World! 114adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * End tag foo 11559aa66320912bdb09c740d2f515bc8da5c5d27b1Elliott Hughes * End document 116adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 117adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 118adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>For more details on API usage, please refer to the 119adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * quick Introduction available at <a href="http://www.xmlpull.org">http://www.xmlpull.org</a> 120adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 121adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see XmlPullParserFactory 122adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #defineEntityReplacementText 123adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getName 124adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespace 125adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 126adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 127adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 128adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #setInput 129adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #FEATURE_PROCESS_DOCDECL 130adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #FEATURE_VALIDATION 131adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #START_DOCUMENT 132adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #START_TAG 133adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #TEXT 134adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #END_TAG 135adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #END_DOCUMENT 136adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 137adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @author <a href="http://www-ai.cs.uni-dortmund.de/PERSONAL/haustein.html">Stefan Haustein</a> 138adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @author <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a> 139adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 140adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 141adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic interface XmlPullParser { 142adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 143adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** This constant represents the default namespace (empty string "") */ 144adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String NO_NAMESPACE = ""; 145adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 146adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // ---------------------------------------------------------------------------- 147adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // EVENT TYPES as reported by next() 148adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 149adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 150adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Signalize that parser is at the very beginning of the document 151adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and nothing was read yet. 152adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This event type can only be observed by calling getEvent() 153adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * before the first call to next(), nextToken, or nextTag()</a>). 154adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 155adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 156adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 157adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 158adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int START_DOCUMENT = 0; 159adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 160adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 161adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Logical end of the xml document. Returned from getEventType, next() 162adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and nextToken() 163adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * when the end of the input document has been reached. 164f1a7fc1453676af318ce11fed9616cbb090b83aeJesse Wilson * <p><strong>NOTE:</strong> subsequent calls to 165adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="#next()">next()</a> or <a href="#nextToken()">nextToken()</a> 166f1a7fc1453676af318ce11fed9616cbb090b83aeJesse Wilson * may result in exception being thrown. 167adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 168adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 169adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 170adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 171adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int END_DOCUMENT = 1; 172adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 173adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 174adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returned from getEventType(), 175adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="#next()">next()</a>, <a href="#nextToken()">nextToken()</a> when 176adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a start tag was read. 177adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The name of start tag is available from getName(), its namespace and prefix are 178adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * available from getNamespace() and getPrefix() 179adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if <a href='#FEATURE_PROCESS_NAMESPACES'>namespaces are enabled</a>. 180adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See getAttribute* methods to retrieve element attributes. 181adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See getNamespace* methods to retrieve newly declared namespaces. 182adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 183adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 184adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 185adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getName 186adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getPrefix 187adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespace 188adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getAttributeCount 189adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getDepth 190adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespaceCount 191adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespace 192adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #FEATURE_PROCESS_NAMESPACES 193adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 194adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int START_TAG = 2; 195adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 196adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 197adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returned from getEventType(), <a href="#next()">next()</a>, or 198adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="#nextToken()">nextToken()</a> when an end tag was read. 199adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The name of start tag is available from getName(), its 200adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * namespace and prefix are 201adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * available from getNamespace() and getPrefix(). 202adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 203adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 204adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 205adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getName 206adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getPrefix 207adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespace 208adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #FEATURE_PROCESS_NAMESPACES 209adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 210adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int END_TAG = 3; 211adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 212adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 213adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 214adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Character data was read and will is available by calling getText(). 215adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>Please note:</strong> <a href="#next()">next()</a> will 216adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * accumulate multiple 217adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * events into one TEXT event, skipping IGNORABLE_WHITESPACE, 218adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * PROCESSING_INSTRUCTION and COMMENT events, 219adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * In contrast, <a href="#nextToken()">nextToken()</a> will stop reading 220adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * text when any other event is observed. 221adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Also, when the state was reached by calling next(), the text value will 222adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * be normalized, whereas getText() will 223adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return unnormalized content in the case of nextToken(). This allows 22487806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * an exact roundtrip without changing line ends when examining low 225adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * level events, whereas for high level applications the text is 22687806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * normalized appropriately. 227adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 228adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 229adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 230adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 231adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 232adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int TEXT = 4; 233adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 234adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // ---------------------------------------------------------------------------- 235adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // additional events exposed by lower level nextToken() 236adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 237adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 238adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * A CDATA sections was just read; 239adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this token is available only from calls to <a href="#nextToken()">nextToken()</a>. 240adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * A call to next() will accumulate various text events into a single event 241adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of type TEXT. The text contained in the CDATA section is available 24287806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * by calling getText(). 243adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 244adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 245adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 246adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 247adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int CDSECT = 5; 248adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 249adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 250adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * An entity reference was just read; 251adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this token is available from <a href="#nextToken()">nextToken()</a> 252adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * only. The entity name is available by calling getName(). If available, 25387806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * the replacement text can be obtained by calling getText(); otherwise, 25487806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * the user is responsible for resolving the entity reference. 255adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This event type is never returned from next(); next() will 256adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * accumulate the replacement text and other text 257adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * events to a single TEXT event. 258adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 259adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 260adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 261adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 262adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int ENTITY_REF = 6; 263adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 264adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 265adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Ignorable whitespace was just read. 266adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This token is available only from <a href="#nextToken()">nextToken()</a>). 267adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * For non-validating 268adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * parsers, this event is only reported by nextToken() when outside 269adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the root element. 270adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Validating parsers may be able to detect ignorable whitespace at 271adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * other locations. 272adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The ignorable whitespace string is available by calling getText() 273adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 274adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> this is different from calling the 275adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * isWhitespace() method, since text content 276adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * may be whitespace but not ignorable. 277adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 278adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Ignorable whitespace is skipped by next() automatically; this event 279adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * type is never returned from next(). 280adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 281adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 282adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 283adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 284adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int IGNORABLE_WHITESPACE = 7; 285adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 286adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 287adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * An XML processing instruction declaration was just read. This 288adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * event type is available only via <a href="#nextToken()">nextToken()</a>. 289adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * getText() will return text that is inside the processing instruction. 290adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Calls to next() will skip processing instructions automatically. 291adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 292adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 293adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 294adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int PROCESSING_INSTRUCTION = 8; 295adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 296adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 297adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * An XML comment was just read. This event type is this token is 298adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * available via <a href="#nextToken()">nextToken()</a> only; 299adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * calls to next() will skip comments automatically. 300adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The content of the comment can be accessed using the getText() 301adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * method. 302adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 303adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 304adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 305adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 306adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int COMMENT = 9; 307adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 308adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 309adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * An XML document type declaration was just read. This token is 310adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * available from <a href="#nextToken()">nextToken()</a> only. 311adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The unparsed text inside the doctype is available via 312adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the getText() method. 313adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 314adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 315adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 316adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 317adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int DOCDECL = 10; 318adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 319adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 320adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This array can be used to convert the event type integer constants 321adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * such as START_TAG or TEXT to 322adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * to a string. For example, the value of TYPES[START_TAG] is 323adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the string "START_TAG". 324adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 325adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This array is intended for diagnostic output only. Relying 32687806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * on the contents of the array may be dangerous since malicious 327adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * applications may alter the array, although it is final, due 328adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * to limitations of the Java language. 329adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 330adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String [] TYPES = { 331adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "START_DOCUMENT", 332adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "END_DOCUMENT", 333adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "START_TAG", 334adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "END_TAG", 335adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "TEXT", 336adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "CDSECT", 337adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "ENTITY_REF", 338adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "IGNORABLE_WHITESPACE", 339adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "PROCESSING_INSTRUCTION", 340adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "COMMENT", 341adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "DOCDECL" 342adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project }; 343adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 344adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 345adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // ---------------------------------------------------------------------------- 346adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // namespace related features 347adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 348adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 349adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This feature determines whether the parser processes 350adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * namespaces. As for all features, the default value is false. 351adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> The value can not be changed during 352adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * parsing an must be set before parsing. 353adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 354adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getFeature 355adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #setFeature 356adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 357adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String FEATURE_PROCESS_NAMESPACES = 358adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "http://xmlpull.org/v1/doc/features.html#process-namespaces"; 359adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 360adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 361adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This feature determines whether namespace attributes are 362adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * exposed via the attribute access methods. Like all features, 363adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the default value is false. This feature cannot be changed 364adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * during parsing. 365adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 366adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getFeature 367adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #setFeature 368adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 369adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String FEATURE_REPORT_NAMESPACE_ATTRIBUTES = 370adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes"; 371adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 372adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 373adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This feature determines whether the document declaration 374adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is processed. If set to false, 375adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the DOCDECL event type is reported by nextToken() 376adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and ignored by next(). 377adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 37887806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * If this feature is activated, then the document declaration 379adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * must be processed by the parser. 380adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 381adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>Please note:</strong> If the document type declaration 382adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * was ignored, entity references may cause exceptions 383adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * later in the parsing process. 384adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The default value of this feature is false. It cannot be changed 385adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * during parsing. 386adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 387adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getFeature 388adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #setFeature 389adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 390adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String FEATURE_PROCESS_DOCDECL = 391adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "http://xmlpull.org/v1/doc/features.html#process-docdecl"; 392adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 393adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 394adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If this feature is activated, all validation errors as 39587806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * defined in the XML 1.0 specification are reported. 396adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This implies that FEATURE_PROCESS_DOCDECL is true and both, the 397adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * internal and external document type declaration will be processed. 398adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>Please Note:</strong> This feature can not be changed 399adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * during parsing. The default value is false. 400adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 401adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getFeature 402adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #setFeature 403adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 404adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String FEATURE_VALIDATION = 405adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project "http://xmlpull.org/v1/doc/features.html#validation"; 406adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 407adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 408adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Use this call to change the general behaviour of the parser, 409adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * such as namespace processing or doctype declaration handling. 410adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This method must be called before the first call to next or 411adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * nextToken. Otherwise, an exception is thrown. 412adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>Example: call setFeature(FEATURE_PROCESS_NAMESPACES, true) in order 413adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * to switch on namespace processing. The initial settings correspond 414adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * to the properties requested from the XML Pull Parser factory. 41587806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * If none were requested, all features are deactivated by default. 416adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 417adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception XmlPullParserException If the feature is not supported or can not be set 418adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception IllegalArgumentException If string with the feature name is null 419adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 420adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void setFeature(String name, 421adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean state) throws XmlPullParserException; 422adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 423adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 424adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the current value of the given feature. 425adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>Please note:</strong> unknown features are 426adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <strong>always</strong> returned as false. 427adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 428adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param name The name of feature to be retrieved. 429adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return The value of the feature. 430adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception IllegalArgumentException if string the feature name is null 431adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 432adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 433adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean getFeature(String name); 434adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 435adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 436adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Set the value of a property. 437adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 438adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The property name is any fully-qualified URI. 439adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 440adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception XmlPullParserException If the property is not supported or can not be set 441adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception IllegalArgumentException If string with the property name is null 442adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 443adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void setProperty(String name, 444adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project Object value) throws XmlPullParserException; 445adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 446adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 447adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Look up the value of a property. 448adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 449adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The property name is any fully-qualified URI. 450adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> unknown properties are <strong>always</strong> 451adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * returned as null. 452adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 453adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param name The name of property to be retrieved. 454adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return The value of named property. 455adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 456adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project Object getProperty(String name); 457adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 458adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 459adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 460adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Set the input source for parser to the given reader and 461adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * resets the parser. The event type is set to the initial value 462adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * START_DOCUMENT. 463adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Setting the reader to null will just stop parsing and 464adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * reset parser state, 465adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * allowing the parser to free internal resources 466adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * such as parsing buffers. 467adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 468adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void setInput(Reader in) throws XmlPullParserException; 469adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 470adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 471adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 472adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Sets the input stream the parser is going to process. 473adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This call resets the parser state and sets the event type 474adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * to the initial value START_DOCUMENT. 475adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 476adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> If an input encoding string is passed, 477adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * it MUST be used. Otherwise, 478adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if inputEncoding is null, the parser SHOULD try to determine 479adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * input encoding following XML 1.0 specification (see below). 480adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If encoding detection is supported then following feature 481adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://xmlpull.org/v1/doc/features.html#detect-encoding">http://xmlpull.org/v1/doc/features.html#detect-encoding</a> 482adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * MUST be true amd otherwise it must be false 483adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 484adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param inputStream contains a raw byte input stream of possibly 485adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * unknown encoding (when inputEncoding is null). 486adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 487adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param inputEncoding if not null it MUST be used as encoding for inputStream 488adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 489adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void setInput(InputStream inputStream, String inputEncoding) 490adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws XmlPullParserException; 491adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 492adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 493adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the input encoding if known, null otherwise. 494adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If setInput(InputStream, inputEncoding) was called with an inputEncoding 495adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * value other than null, this value must be returned 496adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * from this method. Otherwise, if inputEncoding is null and 49787806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * the parser supports the encoding detection feature 498adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (http://xmlpull.org/v1/doc/features.html#detect-encoding), 499adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * it must return the detected encoding. 500adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If setInput(Reader) was called, null is returned. 501adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * After first call to next if XML declaration was present this method 502adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * will return encoding declared. 503adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 504adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getInputEncoding(); 505adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 506adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 507adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Set new value for entity replacement text as defined in 508adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/TR/REC-xml#intern-replacement">XML 1.0 Section 4.5 509adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Construction of Internal Entity Replacement Text</a>. 510adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If FEATURE_PROCESS_DOCDECL or FEATURE_VALIDATION are set, calling this 511adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * function will result in an exception -- when processing of DOCDECL is 512adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * enabled, there is no need to the entity replacement text manually. 513adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 514adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The motivation for this function is to allow very small 515adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * implementations of XMLPULL that will work in J2ME environments. 516adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Though these implementations may not be able to process the document type 517adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * declaration, they still can work with known DTDs by using this function. 518adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 519adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>Please notes:</b> The given value is used literally as replacement text 520adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and it corresponds to declaring entity in DTD that has all special characters 52187806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * escaped: left angle bracket is replaced with &lt;, ampersand with &amp; 522adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and so on. 523adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 524adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>Note:</b> The given value is the literal replacement text and must not 525adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * contain any other entity reference (if it contains any entity reference 526adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * there will be no further replacement). 527adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 528adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>Note:</b> The list of pre-defined entity names will 529adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * always contain standard XML entities such as 530adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * amp (&amp;), lt (&lt;), gt (&gt;), quot (&quot;), and apos (&apos;). 531adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Those cannot be redefined by this method! 532adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 533adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #setInput 534adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #FEATURE_PROCESS_DOCDECL 535adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #FEATURE_VALIDATION 536adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 537adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void defineEntityReplacementText( String entityName, 538adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String replacementText ) throws XmlPullParserException; 539adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 540adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 541adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the numbers of elements in the namespace stack for the given 542adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * depth. 543adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If namespaces are not enabled, 0 is returned. 544adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 545adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>NOTE:</b> when parser is on END_TAG then it is allowed to call 546adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this function with getDepth()+1 argument to retrieve position of namespace 547adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * prefixes and URIs that were declared on corresponding START_TAG. 54887806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * <p><b>NOTE:</b> to retrieve list of namespaces declared in current element:<pre> 549adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * XmlPullParser pp = ... 550adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * int nsStart = pp.getNamespaceCount(pp.getDepth()-1); 551adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * int nsEnd = pp.getNamespaceCount(pp.getDepth()); 552adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for (int i = nsStart; i < nsEnd; i++) { 553adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * String prefix = pp.getNamespacePrefix(i); 554adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * String ns = pp.getNamespaceUri(i); 555adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * // ... 556adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 557adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 558adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 559adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespacePrefix 560adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespaceUri 561adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespace() 562adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespace(String) 563adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 564adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int getNamespaceCount(int depth) throws XmlPullParserException; 565adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 566adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 56787806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * Returns the namespace prefix for the given position 568adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * in the namespace stack. 569adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Default namespace declaration (xmlns='...') will have null as prefix. 570adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If the given index is out of range, an exception is thrown. 571adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>Please note:</b> when the parser is on an END_TAG, 572adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * namespace prefixes that were declared 573adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * in the corresponding START_TAG are still accessible 574adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * although they are no longer in scope. 575adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 576adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getNamespacePrefix(int pos) throws XmlPullParserException; 577adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 578adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 579adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the namespace URI for the given position in the 580adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * namespace stack 581adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If the position is out of range, an exception is thrown. 582adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>NOTE:</b> when parser is on END_TAG then namespace prefixes that were declared 583adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * in corresponding START_TAG are still accessible even though they are not in scope 584adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 585adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getNamespaceUri(int pos) throws XmlPullParserException; 586adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 587adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 588adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the URI corresponding to the given prefix, 589adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * depending on current state of the parser. 590adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 591adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>If the prefix was not declared in the current scope, 592adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * null is returned. The default namespace is included 593adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * in the namespace table and is available via 594adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * getNamespace (null). 595adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 596adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>This method is a convenience method for 597adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 598adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 599adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for (int i = getNamespaceCount(getDepth ())-1; i >= 0; i--) { 600adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if (getNamespacePrefix(i).equals( prefix )) { 601adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return getNamespaceUri(i); 602adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 603adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 604adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return null; 605adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 606adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 607adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>Please note:</strong> parser implementations 60887806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * may provide more efficient lookup, e.g. using a Hashtable. 609adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The 'xml' prefix is bound to "http://www.w3.org/XML/1998/namespace", as 610adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * defined in the 611adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a> 612adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * specification. Analogous, the 'xmlns' prefix is resolved to 613adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a> 614adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 615adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespaceCount 616adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespacePrefix 617adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getNamespaceUri 618adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 619adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getNamespace (String prefix); 620adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 621adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 622adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // -------------------------------------------------------------------------- 623adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // miscellaneous reporting methods 624adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 625adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 626adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the current depth of the element. 627adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Outside the root element, the depth is 0. The 628adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * depth is incremented by 1 when a start tag is reached. 629adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The depth is decremented AFTER the end tag 630adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * event was observed. 631adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 632adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 633adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <!-- outside --> 0 634adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <root> 1 635adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * sometext 1 636adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <foobar> 2 637adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </foobar> 2 638adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </root> 1 639adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <!-- outside --> 0 640adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 641adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 642adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int getDepth(); 643adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 644adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 645adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns a short text describing the current parser state, including 646adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the position, a 647adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * description of the current event and the data source if known. 648adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This method is especially useful to provide meaningful 649adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * error messages and for debugging purposes. 650adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 651adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getPositionDescription (); 652adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 653adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 654adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 655adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the current line number, starting from 1. 656adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * When the parser does not know the current line number 657adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or can not determine it, -1 is returned (e.g. for WBXML). 658adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 659adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return current line number or -1 if unknown. 660adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 661adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int getLineNumber(); 662adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 663adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 664adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the current column number, starting from 0. 665adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * When the parser does not know the current column number 666adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or can not determine it, -1 is returned (e.g. for WBXML). 667adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 668adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return current column number or -1 if unknown. 669adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 670adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int getColumnNumber(); 671adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 672adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 673adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // -------------------------------------------------------------------------- 674adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // TEXT related methods 675adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 676adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 677adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Checks whether the current TEXT event contains only whitespace 678adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * characters. 679adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * For IGNORABLE_WHITESPACE, this is always true. 680adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * For TEXT and CDSECT, false is returned when the current event text 681adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * contains at least one non-white space character. For any other 682adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * event type an exception is thrown. 683adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 684adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>Please note:</b> non-validating parsers are not 685adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * able to distinguish whitespace and ignorable whitespace, 686adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * except from whitespace outside the root element. Ignorable 687adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * whitespace is reported as separate event, which is exposed 688adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * via nextToken only. 689adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 690adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 691adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean isWhitespace() throws XmlPullParserException; 692adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 693adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 694adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the text content of the current event as String. 695adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The value returned depends on current event type, 696adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for example for TEXT event it is element content 697adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (this is typical case when next() is used). 698adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 699adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See description of nextToken() for detailed description of 700adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * possible returned values for different types of events. 701adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 702adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> in case of ENTITY_REF, this method returns 703adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the entity replacement text (or null if not available). This is 704adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the only case where 705adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * getText() and getTextCharacters() return different values. 706adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 707adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getEventType 708adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 709adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 710adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 711adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getText (); 712adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 713adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 714adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 715adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the buffer that contains the text of the current event, 716adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * as well as the start offset and length relevant for the current 717adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * event. See getText(), next() and nextToken() for description of possible returned values. 718adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 719adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>Please note:</strong> this buffer must not 720adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * be modified and its content MAY change after a call to 721adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * next() or nextToken(). This method will always return the 722adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * same value as getText(), except for ENTITY_REF. In the case 723adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of ENTITY ref, getText() returns the replacement text and 724adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this method returns the actual input buffer containing the 725adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * entity name. 726adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If getText() returns null, this method returns null as well and 727adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the values returned in the holder array MUST be -1 (both start 728adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and length). 729adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 730adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getText 731adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 732adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken 733adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 734adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param holderForStartAndLength Must hold an 2-element int array 735adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * into which the start offset and length values will be written. 736adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return char buffer that contains the text of the current event 737adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (null if the current event has no text associated). 738adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 739adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project char[] getTextCharacters(int [] holderForStartAndLength); 740adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 741adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // -------------------------------------------------------------------------- 742adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // START_TAG / END_TAG shared methods 743adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 744adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 745adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the namespace URI of the current element. 746adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The default namespace is represented 747adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * as empty string. 748adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If namespaces are not enabled, an empty String ("") is always returned. 749adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The current event must be START_TAG or END_TAG; otherwise, 750adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * null is returned. 751adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 752adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getNamespace (); 753adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 754adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 755adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * For START_TAG or END_TAG events, the (local) name of the current 756adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * element is returned when namespaces are enabled. When namespace 757adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * processing is disabled, the raw name is returned. 758adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * For ENTITY_REF events, the entity name is returned. 759adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If the current event is not START_TAG, END_TAG, or ENTITY_REF, 760adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * null is returned. 761adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>Please note:</b> To reconstruct the raw element name 762adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * when namespaces are enabled and the prefix is not null, 763adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * you will need to add the prefix and a colon to localName.. 764adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 765adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 766adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getName(); 767adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 768adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 769adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the prefix of the current element. 770adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If the element is in the default namespace (has no prefix), 771adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * null is returned. 772adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If namespaces are not enabled, or the current event 773adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is not START_TAG or END_TAG, null is returned. 774adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 775adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getPrefix(); 776adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 777adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 778adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns true if the current event is START_TAG and the tag 779adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is degenerated 780adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (e.g. <foobar/>). 781adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>NOTE:</b> if the parser is not on START_TAG, an exception 782adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * will be thrown. 783adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 784adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean isEmptyElementTag() throws XmlPullParserException; 785adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 786adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // -------------------------------------------------------------------------- 787adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // START_TAG Attributes retrieval methods 788adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 789adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 790adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the number of attributes of the current start tag, or 791adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * -1 if the current event type is not START_TAG 792adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 793adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getAttributeNamespace 794adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getAttributeName 795adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getAttributePrefix 796adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #getAttributeValue 797adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 798adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int getAttributeCount(); 799adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 800adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 801adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the namespace URI of the attribute 802adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * with the given index (starts from 0). 803adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns an empty string ("") if namespaces are not enabled 804adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or the attribute has no namespace. 805adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Throws an IndexOutOfBoundsException if the index is out of range 806adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or the current event type is not START_TAG. 807adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 808adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> if FEATURE_REPORT_NAMESPACE_ATTRIBUTES is set 809adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * then namespace attributes (xmlns:ns='...') must be reported 810adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * with namespace 811adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a> 812adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (visit this URL for description!). 813adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The default namespace attribute (xmlns="...") will be reported with empty namespace. 814adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong>The xml prefix is bound as defined in 815adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a> 816adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * specification to "http://www.w3.org/XML/1998/namespace". 817adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 818adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param index zero-based index of attribute 819adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return attribute namespace, 82087806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * empty string ("") is returned if namespaces processing is not enabled or 821adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * namespaces processing is enabled but attribute has no namespace (it has no prefix). 822adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 823adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getAttributeNamespace (int index); 824adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 825adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 826adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the local name of the specified attribute 827adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if namespaces are enabled or just attribute name if namespaces are disabled. 828adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Throws an IndexOutOfBoundsException if the index is out of range 829adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or current event type is not START_TAG. 830adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 831adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param index zero-based index of attribute 832adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return attribute name (null is never returned) 833adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 834adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getAttributeName (int index); 835adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 836adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 837adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the prefix of the specified attribute 838adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns null if the element has no prefix. 839adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If namespaces are disabled it will always return null. 840adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Throws an IndexOutOfBoundsException if the index is out of range 841adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or current event type is not START_TAG. 842adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 843adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param index zero-based index of attribute 844adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return attribute prefix or null if namespaces processing is not enabled. 845adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 846adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getAttributePrefix(int index); 847adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 848adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 849adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the type of the specified attribute 850adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If parser is non-validating it MUST return CDATA. 851adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 852adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param index zero-based index of attribute 853adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return attribute type (null is never returned) 854adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 855adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getAttributeType(int index); 856adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 857adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 858adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns if the specified attribute was not in input was declared in XML. 859adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If parser is non-validating it MUST always return false. 860adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This information is part of XML infoset: 861adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 862adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param index zero-based index of attribute 863adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return false if attribute was in input 864adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 865adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project boolean isAttributeDefault(int index); 866adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 867adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 868adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the given attributes value. 869adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Throws an IndexOutOfBoundsException if the index is out of range 870adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or current event type is not START_TAG. 871adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 872adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> attribute value must be normalized 873adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (including entity replacement text if PROCESS_DOCDECL is false) as described in 874adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/TR/REC-xml#AVNormalize">XML 1.0 section 875adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 3.3.3 Attribute-Value Normalization</a> 876adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 877adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #defineEntityReplacementText 878adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 879adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param index zero-based index of attribute 880adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return value of attribute (null is never returned) 881adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 882adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getAttributeValue(int index); 883adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 884adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 885adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the attributes value identified by namespace URI and namespace localName. 886adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If namespaces are disabled namespace must be null. 887adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If current event type is not START_TAG then IndexOutOfBoundsException will be thrown. 888adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 889adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> attribute value must be normalized 890adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (including entity replacement text if PROCESS_DOCDECL is false) as described in 891adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/TR/REC-xml#AVNormalize">XML 1.0 section 892adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 3.3.3 Attribute-Value Normalization</a> 893adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 894adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #defineEntityReplacementText 895adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 896adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param namespace Namespace of the attribute if namespaces are enabled otherwise must be null 897adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param name If namespaces enabled local name of attribute otherwise just attribute name 898adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return value of attribute or null if attribute with given name does not exist 899adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 900adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String getAttributeValue(String namespace, 901adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String name); 902adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 903adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // -------------------------------------------------------------------------- 904adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // actual parsing methods 905adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 906adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 907adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns the type of the current event (START_TAG, END_TAG, TEXT, etc.) 908adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 909adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next() 910adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #nextToken() 911adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 912adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int getEventType() 913adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws XmlPullParserException; 914adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 915adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 916c9b4e40b19fdf79c22d4774600f704b473f47067Elliott Hughes * Get next parsing event - element content will be coalesced and only one 917adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * TEXT event must be returned for whole element content 91887806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * (comments and processing instructions will be ignored and entity references 919de7e8c4314e6954f4f5996f9929dc9db81d500a9Narayan Kamath * must be expanded or exception must be thrown if entity reference can not be expanded). 920adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If element content is empty (content is "") then no TEXT event will be reported. 921adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 922adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><b>NOTE:</b> empty element (such as <tag/>) will be reported 923adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * with two separate events: START_TAG, END_TAG - it must be so to preserve 924adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * parsing equivalency of empty element to <tag></tag>. 925adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (see isEmptyElementTag ()) 926adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 927adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #isEmptyElementTag 928adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #START_TAG 929adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #TEXT 930adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #END_TAG 931adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #END_DOCUMENT 932adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 933adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 934adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int next() 935adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws XmlPullParserException, IOException; 936adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 937adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 938adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 939adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This method works similarly to next() but will expose 940adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * additional event types (COMMENT, CDSECT, DOCDECL, ENTITY_REF, PROCESSING_INSTRUCTION, or 941adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * IGNORABLE_WHITESPACE) if they are available in input. 942adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 943adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>If special feature 944adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">FEATURE_XML_ROUNDTRIP</a> 945adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (identified by URI: http://xmlpull.org/v1/doc/features.html#xml-roundtrip) 946adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is enabled it is possible to do XML document round trip ie. reproduce 947adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * exectly on output the XML input using getText(): 948adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * returned content is always unnormalized (exactly as in input). 949adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Otherwise returned content is end-of-line normalized as described 950adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line Handling</a> 951adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and. Also when this feature is enabled exact content of START_TAG, END_TAG, 952adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * DOCDECL and PROCESSING_INSTRUCTION is available. 953adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 954adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>Here is the list of tokens that can be returned from nextToken() 955adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and what getText() and getTextCharacters() returns:<dl> 956adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>START_DOCUMENT<dd>null 957adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>END_DOCUMENT<dd>null 958adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>START_TAG<dd>null unless FEATURE_XML_ROUNDTRIP 959adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * enabled and then returns XML tag, ex: <tag attr='val'> 960adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>END_TAG<dd>null unless FEATURE_XML_ROUNDTRIP 961adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * id enabled and then returns XML tag, ex: </tag> 962adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>TEXT<dd>return element content. 963adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <br>Note: that element content may be delivered in multiple consecutive TEXT events. 964adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>IGNORABLE_WHITESPACE<dd>return characters that are determined to be ignorable white 965adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * space. If the FEATURE_XML_ROUNDTRIP is enabled all whitespace content outside root 96687806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * element will always reported as IGNORABLE_WHITESPACE otherwise reporting is optional. 96787806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * <br>Note: that element content may be delivered in multiple consecutive IGNORABLE_WHITESPACE events. 968adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>CDSECT<dd> 969adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return text <em>inside</em> CDATA 970adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (ex. 'fo<o' from <!CDATA[fo<o]]>) 971adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>PROCESSING_INSTRUCTION<dd> 972adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if FEATURE_XML_ROUNDTRIP is true 973adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return exact PI content ex: 'pi foo' from <?pi foo?> 974adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * otherwise it may be exact PI content or concatenation of PI target, 975adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * space and data so for example for 976adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <?target data?> string "target data" may 977adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * be returned if FEATURE_XML_ROUNDTRIP is false. 978adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>COMMENT<dd>return comment content ex. 'foo bar' from <!--foo bar--> 979adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>ENTITY_REF<dd>getText() MUST return entity replacement text if PROCESS_DOCDECL is false 980adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * otherwise getText() MAY return null, 981adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * additionally getTextCharacters() MUST return entity name 982adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (for example 'entity_name' for &entity_name;). 983adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <br><b>NOTE:</b> this is the only place where value returned from getText() and 984adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * getTextCharacters() <b>are different</b> 985adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <br><b>NOTE:</b> it is user responsibility to resolve entity reference 986adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if PROCESS_DOCDECL is false and there is no entity replacement text set in 987adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * defineEntityReplacementText() method (getText() will be null) 988adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <br><b>NOTE:</b> character entities (ex. &#32;) and standard entities such as 989adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * &amp; &lt; &gt; &quot; &apos; are reported as well 990adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and are <b>not</b> reported as TEXT tokens but as ENTITY_REF tokens! 991adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This requirement is added to allow to do roundtrip of XML documents! 992adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <dt>DOCDECL<dd> 993adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if FEATURE_XML_ROUNDTRIP is true or PROCESS_DOCDECL is false 994adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * then return what is inside of DOCDECL for example it returns:<pre> 995adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * " titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd" 996adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * [<!ENTITY % active.links "INCLUDE">]"</pre> 997adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>for input document that contained:<pre> 998adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <!DOCTYPE titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd" 999adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * [<!ENTITY % active.links "INCLUDE">]></pre> 1000adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * otherwise if FEATURE_XML_ROUNDTRIP is false and PROCESS_DOCDECL is true 1001adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * then what is returned is undefined (it may be even null) 1002adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </dd> 1003adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </dl> 1004adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 100587806e1dba84c281567b6d1bb9bb61f3e95ab744Elliott Hughes * <p><strong>NOTE:</strong> there is no guarantee that there will only one TEXT or 1006adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * IGNORABLE_WHITESPACE event from nextToken() as parser may chose to deliver element content in 1007adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * multiple tokens (dividing element content into chunks) 1008adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 1009adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> whether returned text of token is end-of-line normalized 1010adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is depending on FEATURE_XML_ROUNDTRIP. 1011adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 1012adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>NOTE:</strong> XMLDecl (<?xml ...?>) is not reported but its content 1013adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is available through optional properties (see class description above). 1014adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 1015adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #next 1016adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #START_TAG 1017adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #TEXT 1018adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #END_TAG 1019adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #END_DOCUMENT 1020adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #COMMENT 1021adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #DOCDECL 1022adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #PROCESSING_INSTRUCTION 1023adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #ENTITY_REF 1024adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see #IGNORABLE_WHITESPACE 1025adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 1026adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int nextToken() 1027adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws XmlPullParserException, IOException; 1028adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 1029adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project //----------------------------------------------------------------------------- 1030adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // utility methods to mak XML parsing easier ... 1031adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 1032adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 1033adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Test if the current event is of the given type and if the 1034adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * namespace and name do match. null will match any namespace 1035adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * and any name. If the test is not passed, an exception is 1036adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * thrown. The exception text indicates the parser position, 1037adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the expected event and the current event that is not meeting the 1038adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * requirement. 1039adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 1040adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>Essentially it does this 1041adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 1042adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if (type != getEventType() 1043adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * || (namespace != null && !namespace.equals( getNamespace () ) ) 1044adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * || (name != null && !name.equals( getName() ) ) ) 1045adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * throw new XmlPullParserException( "expected "+ TYPES[ type ]+getPositionDescription()); 1046adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 1047adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 1048adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void require(int type, String namespace, String name) 1049adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws XmlPullParserException, IOException; 1050adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 1051adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 1052adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If current event is START_TAG then if next element is TEXT then element content is returned 1053adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * or if next event is END_TAG then empty string is returned, otherwise exception is thrown. 1054adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * After calling this function successfully parser will be positioned on END_TAG. 1055c9b4e40b19fdf79c22d4774600f704b473f47067Elliott Hughes * 1056adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The motivation for this function is to allow to parse consistently both 1057adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * empty elements and elements that has non empty content, for example for input: <ol> 1058adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li><tag>foo</tag> 1059adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <li><tag></tag> (which is equivalent to <tag/> 1060adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * both input can be parsed with the same code: 1061adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 1062adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * p.nextTag() 1063adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * p.requireEvent(p.START_TAG, "", "tag"); 1064adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * String content = p.nextText(); 1065adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * p.requireEvent(p.END_TAG, "", "tag"); 1066adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 1067adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * This function together with nextTag make it very easy to parse XML that has 1068adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * no mixed content. 1069adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 1070adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 1071adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>Essentially it does this 1072adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 1073adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if(getEventType() != START_TAG) { 1074adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * throw new XmlPullParserException( 1075adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * "parser must be on START_TAG to read next text", this, null); 1076adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 1077adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * int eventType = next(); 1078adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if(eventType == TEXT) { 1079adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * String result = getText(); 1080adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * eventType = next(); 1081adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if(eventType != END_TAG) { 1082adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * throw new XmlPullParserException( 1083adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * "event TEXT it must be immediately followed by END_TAG", this, null); 1084adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 1085adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return result; 1086adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } else if(eventType == END_TAG) { 1087adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return ""; 1088adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } else { 1089adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * throw new XmlPullParserException( 1090adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * "parser must be on START_TAG or TEXT to read text", this, null); 1091adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 1092adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 109348d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * 109448d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * <p><strong>Warning:</strong> Prior to API level 14, the pull parser returned by {@code 109548d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * android.util.Xml} did not always advance to the END_TAG event when this method was called. 109648d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * Work around by using manually advancing after calls to nextText(): <pre> 109748d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * String text = xpp.nextText(); 109848d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * if (xpp.getEventType() != XmlPullParser.END_TAG) { 109948d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * xpp.next(); 110048d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * } 110148d7dbad8dd83395667d9846e49c5ba38f0a5258Jesse Wilson * </pre> 1102adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 1103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project String nextText() throws XmlPullParserException, IOException; 1104adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 1105adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 1106adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Call next() and return event if it is START_TAG or END_TAG 1107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * otherwise throw an exception. 1108adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * It will skip whitespace TEXT before actual tag if any. 1109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 1110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>essentially it does this 1111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 1112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * int eventType = next(); 1113adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if(eventType == TEXT && isWhitespace()) { // skip whitespace 1114adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * eventType = next(); 1115adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 1116adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if (eventType != START_TAG && eventType != END_TAG) { 1117adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * throw new XmlPullParserException("expected start or end tag", this, null); 1118adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 1119adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * return eventType; 1120adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 1121adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 1122adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int nextTag() throws XmlPullParserException, IOException; 1123adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 1124adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 1125