Xml Pull Parser (XPP) provides a very simple, high performance "pull model" to parse Reader or String input.

Following steps are required to use XPP:

  1. create an instance of {@link xpp.XmlPullParser}
  2. set options (if they are different than defaults)
  3. set input by calling either {@link xpp.XmlPullParser#setInput(Reader)} or {@link xpp.XmlPullParser#setInput(char[])}
  4. start parsing by calling {@link xpp.XmlPullParser#next} - this method returns event type and parsing is finished when it returns {@link xpp.XmlPullParser#END_DOCUMENT} event type.

Typically parsing is done in while loop that will work until {@link xpp.XmlPullParser#next} returns {@link xpp.XmlPullParser#END_DOCUMENT}. All possible types of events that {@link xpp.XmlPullParser#next} can return:

If there is parsing error {@link xpp.XmlPullParser#next} will throw {@link xpp.XmlPullParserException}.

An example Java program may look like this: (for more detailed example please see src/{cpp,java}/samples/pullparser)

  // 1. creating instance of parser
  XmlPullParser xpp = new XmlPullParser();

  // 2. setting options
  // ex. disabling mixed content for elements 
  // (element can not have elements mixed with non-whitespace string content)
  xpp.setMixedContent(false);

  // 3. setting input
  String data = "<hello>World!</hello>";
  // input will be taken from java.io.Reader
  xpp.setInput(new StringReader(data));

  // input could be also taken from String directly:
  //xpp.setInput(data.toCharArray());
  
  // 4. parsing
  
  //declare variables used during parsing
  byte type;  // received event type
  StartTag stag = new StartTag();
  EndTag etag = new EndTag();

  // start parsing loop
  while((type = xpp.next()) != XmlPullParser.END_DOCUMENT) {
    if(type == XmlPullParser.CONTENT) {
      String s = xpp.readContent();
      System.out.println("CONTENT={'"+s+"'}");
    } else if(type == XmlPullParser.END_TAG) {
      xpp.readEndTag(etag);
      System.out.println(""+etag);
    } else if(type == XmlPullParser.START_TAG) {
      xpp.readStartTag(stag);
      System.out.println(""+stag);
    }
  }

After parsing is finished, parser instance may be reused by calling again {@link xpp.XmlPullParser#setInput(Reader)}.

Example Java code that will read string for SOAP encoding

  public String readString(XmlPullParser pp, StartTag stag)
    throws DeserializeException, XmlPullParserException, IOException
  {
    String xs = stag.getValue(Soap.XSI_NS, "null");
    if( "1".equals(xs) ) {
      if(pp.next() != XmlPullParser.END_TAG)
        throw new DeserializeException("expected end tag");
      return null;
    }
    if(pp.next() != XmlPullParser.CONTENT)
      throw new DeserializeException("expected content");
    String content = pp.readContent();
    if(pp.next() != XmlPullParser.END_TAG)
      throw new DeserializeException("expected end tag");
    return content;
  }

C++ version

C++ has almost identical API to Java version. However there are some differences:

The same example code but in C++

  public string* readString(XmlPullParser& pp, StartTag& stag)
    throw( DeserializeException, XmlPullParserException )
  {
    string xs = stag.getValue(Soap.XSI_NS, "null");
    if(xs == "1") ) {
      if(pp.next() != XmlPullParser::END_TAG)
        throw DeserializeException("expected end tag");
      return NULL;
    }
    if(pp.next() != XmlPullParser::CONTENT)
      throw DeserializeException("expected content");
    string content = pp.readContent();
    if(pp.next() != XmlPullParser::END_TAG)
      throw DeserializeException("expected end tag");
    return new string(content);
  }
For more details please look into C++ source code in src/cpp/xpp and Java source code in src/java/xpp.


Aleksander Slominski

Last modified: Tue Jan 30 13:35:20 EST 2001