XmlPullParser

public interface XmlPullParser

XML Pull Parser is an interface that defines parsing functionality provided in XMLPULL V1 API (visit this website to learn more about API and its implementations).

There are following different kinds of parser depending on which features are set:

  • non-validating parser as defined in XML 1.0 spec when FEATURE_PROCESS_DOCDECL is set to true
  • validating parser as defined in XML 1.0 spec when FEATURE_VALIDATION is true (and that implies that FEATURE_PROCESS_DOCDECL is true)
  • when FEATURE_PROCESS_DOCDECL is false (this is default and if different value is required necessary must be changed before parsing is started) then parser behaves like XML 1.0 compliant non-validating parser under condition that no DOCDECL is present in XML documents (internal entites can still be defined with defineEntityReplacementText()). This mode of operation is intended for operation in constrained environments such as J2ME.

There are two key methods: next() and nextToken(). While next() provides access to high level parsing events, nextToken() allows access to lower level tokens.

The current event state of the parser can be determined by calling the getEventType() method. Initially, the parser is in the START_DOCUMENT state.

The method next() advances the parser to the next event. The int value returned from next determines the current parser state and is identical to the value returned from following calls to getEventType ().

Th following event types are seen by next()

START_TAG
An XML start tag was read.
TEXT
Text content was read; the text content can be retrieved using the getText() method. (when in validating mode next() will not report ignorable whitespace, use nextToken() instead)
END_TAG
An end tag was read
END_DOCUMENT
No more events are available

after first next() or nextToken() (or any other next*() method) is called user application can obtain XML version, standalone and encoding from XML declaration in following ways:

  • version: getProperty("http://xmlpull.org/v1/doc/properties.html#xmldecl-version") returns String ("1.0") or null if XMLDecl was not read or if property is not supported
  • standalone: getProperty("http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone") returns Boolean: null if there was no standalone declaration or if property is not supported otherwise returns Boolean(true) if standalone="yes" and Boolean(false) when standalone="no"
  • encoding: obtained from getInputEncoding() null if stream had unknown encoding (not set in setInputStream) and it was not declared in XMLDecl
A minimal example for using this API may look as follows:
 import java.io.IOException;
 import java.io.StringReader;

 import org.xmlpull.v1.XmlPullParser;
 import org.xmlpull.v1.XmlPullParserException;
 import org.xmlpull.v1.XmlPullParserFactory;

 public class SimpleXmlPullApp
 {

     public static void main (String args[])
         throws XmlPullParserException, IOException
     {
         XmlPullParserFactory factory = XmlPullParserFactory.newInstance();
         factory.setNamespaceAware(true);
         XmlPullParser xpp = factory.newPullParser();

         xpp.setInput( new StringReader ( "<foo>Hello World!</foo>" ) );
         int eventType = xpp.getEventType();
         while (eventType != XmlPullParser.END_DOCUMENT) {
          if(eventType == XmlPullParser.START_DOCUMENT) {
              System.out.println("Start document");
          } else if(eventType == XmlPullParser.START_TAG) {
              System.out.println("Start tag "+xpp.getName());
          } else if(eventType == XmlPullParser.END_TAG) {
              System.out.println("End tag "+xpp.getName());
          } else if(eventType == XmlPullParser.TEXT) {
              System.out.println("Text "+xpp.getText());
          }
          eventType = xpp.next();
         }
         System.out.println("End document");
     }
 }
 

The above example will generate the following output:

 Start document
 Start tag foo
 Text Hello World!
 End tag foo
 End document
 

For more details on API usage, please refer to the quick Introduction available at http://www.xmlpull.org

Constant Summary

int CDSECT A CDATA sections was just read; this token is available only from calls to nextToken().
int COMMENT An XML comment was just read.
int DOCDECL An XML document type declaration was just read.
int END_DOCUMENT Logical end of the xml document.
int END_TAG Returned from getEventType(), next(), or nextToken() when an end tag was read.
int ENTITY_REF An entity reference was just read; this token is available from nextToken() only.
String FEATURE_PROCESS_DOCDECL This feature determines whether the document declaration is processed.
String FEATURE_PROCESS_NAMESPACES This feature determines whether the parser processes namespaces.
String FEATURE_REPORT_NAMESPACE_ATTRIBUTES This feature determines whether namespace attributes are exposed via the attribute access methods.
String FEATURE_VALIDATION If this feature is activated, all validation errors as defined in the XML 1.0 specification are reported.
int IGNORABLE_WHITESPACE Ignorable whitespace was just read.
String NO_NAMESPACE This constant represents the default namespace (empty string "")
int PROCESSING_INSTRUCTION An XML processing instruction declaration was just read.
int START_DOCUMENT Signalize that parser is at the very beginning of the document and nothing was read yet.
int START_TAG Returned from getEventType(), next(), nextToken() when a start tag was read.
int TEXT Character data was read and will is available by calling getText().

Field Summary

public static final String[] TYPES This array can be used to convert the event type integer constants such as START_TAG or TEXT to to a string.

Public Method Summary

abstract void
defineEntityReplacementText(String entityName, String replacementText)
Set new value for entity replacement text as defined in XML 1.0 Section 4.5 Construction of Internal Entity Replacement Text.
abstract int
getAttributeCount()
Returns the number of attributes of the current start tag, or -1 if the current event type is not START_TAG
abstract String
getAttributeName(int index)
Returns the local name of the specified attribute if namespaces are enabled or just attribute name if namespaces are disabled.
abstract String
getAttributeNamespace(int index)
Returns the namespace URI of the attribute with the given index (starts from 0).
abstract String
getAttributePrefix(int index)
Returns the prefix of the specified attribute Returns null if the element has no prefix.
abstract String
getAttributeType(int index)
Returns the type of the specified attribute If parser is non-validating it MUST return CDATA.
abstract String
getAttributeValue(String namespace, String name)
Returns the attributes value identified by namespace URI and namespace localName.
abstract String
getAttributeValue(int index)
Returns the given attributes value.
abstract int
getColumnNumber()
Returns the current column number, starting from 0.
abstract int
getDepth()
Returns the current depth of the element.
abstract int
getEventType()
Returns the type of the current event (START_TAG, END_TAG, TEXT, etc.)
abstract boolean
getFeature(String name)
Returns the current value of the given feature.
abstract String
getInputEncoding()
Returns the input encoding if known, null otherwise.
abstract int
getLineNumber()
Returns the current line number, starting from 1.
abstract String
getName()
For START_TAG or END_TAG events, the (local) name of the current element is returned when namespaces are enabled.
abstract String
getNamespace()
Returns the namespace URI of the current element.
abstract String
getNamespace(String prefix)
Returns the URI corresponding to the given prefix, depending on current state of the parser.
abstract int
getNamespaceCount(int depth)
Returns the numbers of elements in the namespace stack for the given depth.
abstract String
getNamespacePrefix(int pos)
Returns the namespace prefix for the given position in the namespace stack.
abstract String
getNamespaceUri(int pos)
Returns the namespace URI for the given position in the namespace stack If the position is out of range, an exception is thrown.
abstract String
getPositionDescription()
Returns a short text describing the current parser state, including the position, a description of the current event and the data source if known.
abstract String
getPrefix()
Returns the prefix of the current element.
abstract Object
getProperty(String name)
Look up the value of a property.