Quick Introduction to XmlPull v1 API

XmlPull v1 API is a simple to use XML pull parsing API that was designed for simplicity and very good performance both in constrained environment such as defined by J2ME and on server side when used in J2EE application servers. XML pull parsing allows incremental (sometimes called streaming) parsing of XML where application is in control - the parsing can be interrupted at any given moment and resumed when application is ready to consume more input.

This document will show step by step how to create a simple  application that is using XmlPull API to parse XML. If you need to write XML output check a companion document Quick Introduction to writing XML with XmlSerializer.  For more comprehensive introduction to XmlPull v1 API and XML pull parsing in general read JavaWorld.com article "XML documents on the run, Part 3" by Dennis M. Sosnoski.

Main features of API

Java version of XmlPull v1 API provides:

Requirements

XmlPull is API and it requires implementation to run. See list of implementations on XmlPull website. After downloading one of implementations of XmlPull API v1 (version 1.1 or newer) add jar file to your CLASSPATH. As XmlPull uses factory there is no need to explicitly state what is class with parser implementation: it will be picked up automatically from implementation jar file.

Code step-by-step

First we need to create an instance of parser. To do this three steps are required:

Before doing anything make sure to import XmlPull v1 API classes:
import org.xmlpull.v1.XmlPullParser;
import org.xmlpull.v1.XmlPullParserException;
import org.xmlpull.v1.XmlPullParserFactory;
and the code to do this may look similar to this:
        XmlPullParserFactory factory = XmlPullParserFactory.newInstance(
           System.getProperty(XmlPullParserFactory.PROPERTY_NAME), null);
        factory.setNamespaceAware(true);
        XmlPullParser xpp = factory.newPullParser();
Next step is to set parser input:
        xpp.setInput ( new FileReader ( args [i] ) );
and now we can start parsing!

Typical XmlPull applicaition will repeatedly call next() function to retrieve next event, process event until the even is END_DOCUMENT:

    public void processDocument(XmlPullParser xpp)
        throws XmlPullParserException, IOException
    {
        int eventType = xpp.getEventType();
        do {
            if(eventType == xpp.START_DOCUMENT) {
                System.out.println("Start document");
            } else if(eventType == xpp.END_DOCUMENT) {
                System.out.println("End document");
            } else if(eventType == xpp.START_TAG) {
                processStartElement(xpp);
            } else if(eventType == xpp.END_TAG) {
                processEndElement(xpp);
            } else if(eventType == xpp.TEXT) {
                processText(xpp);
            }
            eventType = xpp.next();
        } while (eventType != xpp.END_DOCUMENT);
    }

Let see how to process start tag. Processing end tag is very similar - main difference is that the end tag has no attributes.

    public void processStartElement (XmlPullParser xpp)
    {
        String name = xpp.getName();
        String uri = xpp.getNamespace();
        if ("".equals (uri)) {
            System.out.println("Start element: " + name);
        } else {
            System.out.println("Start element: {" + uri + "}" + name);
        }
    }

And now let see how element content is retrieved and printed:

    int holderForStartAndLength[] = new int[2];
    public void processText (XmlPullParser xpp) throws XmlPullParserException
    {
        char ch[] = xpp.getTextCharacters(holderForStartAndLength);
        int start = holderForStartAndLength[0];
        int length = holderForStartAndLength[1];
        System.out.print("Characters:    \"");
        for (int i = start; i < start + length; i++) {
            switch (ch[i]) {
                case '\\':
                    System.out.print("\\\\");
                    break;
                case '"':
                    System.out.print("\\\"");
                    break;
                case '\n':
                    System.out.print("\\n");
                    break;
                case '\r':
                    System.out.print("\\r");
                    break;
                case '\t':
                    System.out.print("\\t");
                    break;
                default:
                    System.out.print(ch[i]);
                    break;
            }
        }
        System.out.print("\"\n");
    }

Complete sample

The finished working sample created that was described is in MyXmlPullApp.java file in src/java/samples directory.

For more information please visit http://www.xmlpull.org/.

Output

java MyXmlPullApp
parser implementation class is class org.xmlpull.xpp3.PullParser
Parsing simple sample XML
Start document
Start element: {http://www.megginson.com/ns/exp/poetry}poem
Characters:    "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}title
Characters:    "Roses are Red"
End element:   {http://www.megginson.com/ns/exp/poetry}title
Characters:    "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters:    "Roses are red,"
End element:   {http://www.megginson.com/ns/exp/poetry}l
Characters:    "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters:    "Violets are blue;"
End element:   {http://www.megginson.com/ns/exp/poetry}l
Characters:    "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters:    "Sugar is sweet,"
End element:   {http://www.megginson.com/ns/exp/poetry}l
Characters:    "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters:    "And I love you."
End element:   {http://www.megginson.com/ns/exp/poetry}l
Characters:    "\n"
End element:   {http://www.megginson.com/ns/exp/poetry}poem

Aleksander Slominski