XMLPULL is the newest and perhaps the simplest of the APIs discussed in this book. It includes only one package which contains one factory class, one interface representing the parser, and one exception. A pull-parser works in streaming mode like a SAX parser. However, it waits for the client program to request the next event rather than pushing it to it. This section is based on version 1.0.8 of XMLPULL.


The org.xmlpull.v1 package includes all three parts of the XMLPULL API: XmlPullParser, XmlPullParserFactory, and XmlPullParserException.


The XmlPullParser interface represents the parser. It contains constant fields that represent type codes and features. It declares methods to get and set features and properties, to retrieve the next token from the parser, and to extract the data from that token.

package org.xmlpull.v1;

public interface XmlPullParser  {

  public static final String   NO_NAMESPACE;
  public static final int      START_DOCUMENT;
  public static final int      END_DOCUMENT;
  public static final int      START_TAG;
  public static final int      END_TAG;
  public static final int      TEXT;
  public static final byte     CDSECT;
  public static final byte     ENTITY_REF;
  public static final byte     IGNORABLE_WHITESPACE;
  public static final byte     PROCESSING_INSTRUCTION;
  public static final int      COMMENT;
  public static final int      DOCDECL;
  public static final String[] TYPES;
  public static final String FEATURE_PROCESS_NAMESPACES;
  public static final String FEATURE_PROCESS_DOCDECL;
  public static final String FEATURE_VALIDATION;

  public void    setFeature(String name, boolean state) 
   throws XmlPullParserException;
  public boolean getFeature(String name);
  public void    setProperty(String name, Object value) 
   throws XmlPullParserException;
  public Object  getProperty(String name);
  public void    setInput(Reader in) throws XmlPullParserException;
  public void    setInput(InputStream in, String encoding) 
   throws XmlPullParserException;
  public String  getInputEncoding();
  public void    defineEntityReplacementText(String entityName, 
   String replacementText) throws XmlPullParserException;

  public int     getNamespaceCount(int depth) 
   throws XmlPullParserException;
  public String  getNamespacePrefix(int position) 
   throws XmlPullParserException;
  public String  getNamespaceUri(int position) 
   throws XmlPullParserException;
  public String  getNamespace(String prefix);
  public int     getDepth();
  public String  getPositionDescription();
  public int     getLineNumber();
  public int     getColumnNumber();
  public boolean isWhitespace() throws XmlPullParserException;
  public String  getText();
  public char[]  getTextCharacters(int holderForStartAndLength);
  public String  getNamespace();
  public String  getName();
  public String  getPrefix();
  public boolean isEmptyElementTag() 
   throws XmlPullParserException;
  public int     getAttributeCount();
  public String  getAttributeNamespace(int index);
  public String  getAttributeName(int index);
  public String  getAttributePrefix(int index);
  public String  getAttributeType(int index);
  public boolean isAttributeDefault(int index);
  public String  getAttributeValue(int index);
  public String  getAttributeValue(String namespace, 
   String name);
  public int     getEventType() 
   throws XmlPullParserException;
  public int     next() 
   throws XmlPullParserException, IOException;
  public int     nextToken() 
   throws XmlPullParserException, IOException;
  public void    require(int type, String namespace, String name) 
   throws XmlPullParserException, IOException;
  public String  nextText() 
   throws XmlPullParserException, IOException;
  public int     nextTag() 
   throws XmlPullParserException, IOException;



The XmlPullParserFactory class creates and configures new XmlPullParser objects in an implementation independent fashion.

package org.xmlpull.v1;

public class XmlPullParserFactory  {

  public static final String PROPERTY_NAME;
  protected Vector    parserClasses;
  protected String    parserClassesLocation;
  protected Hashtable features;

  protected XmlPullParserFactory();

  public void    setFeature(String name, boolean state) 
   throws XmlPullParserException;
  public boolean getFeature(String name);
  public void    setNamespaceAware(boolean awareness);
  public boolean isNamespaceAware();
  public void    setValidating(boolean validating);
  public boolean isValidating();
  public XmlPullParser newPullParser() 
   throws XmlPullParserException;
  public static XmlPullParserFactory newInstance() 
   throws XmlPullParserException;
  public static XmlPullParserFactory newInstance(
   String classNames, Class context) 
   throws XmlPullParserException;


Exceptions and Errors

XMLPULL includes a single exception class, XmlPullParserException, that represents the various things that can go wrong while parsing an XML document. In addition, a few methods that perform I/O can also throw an IOException.


An XmlPullParserException indicates that something has gone wrong during a parse. This may be a well-formedness error in the document such as an unclosed element or a programming error in the code.

package org.xmlpull.v1;

public class XmlPullParserException extends Exception {

  protected Throwable detail;
  protected int       row;
  protected int       column;

  public XmlPullParserException(String message);
  public XmlPullParserException(String message, 
   XmlPullParser parser, Throwable detail);

  public Throwable getDetail();
  public int       getLineNumber();
  public int       getColumnNumber();
  public void      printStackTrace();


Copyright 2001, 2002 Elliotte Rusty Haroldelharo@metalab.unc.eduLast Modified June 03, 2002
Up To Cafe con Leche