Author: Aleksander Slominski

# 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:

- simple interface - parser consists of one interface, one exception and one factory to create parser
- implementation independent - factory class is modeled after JAXP and allows easily to switch to different XmlPull V1 API implementation without even modifying source code
- ease of use - there is only one key method next() that is used to retrieve next event and there are only five events:
  START DOCUMENT
    document start - parser has not yet read any input
  START_TAG
    parser is on start tag
  TEXT
    parser is on element content
  END_TAG
    parser is on end tag
  END_DOCUMENT
    document finished and no more parsing is allowed
- versatility - it is generic interface for XML parser and allows for multiple implementations and extensibility through features and properties
- performance - the interface is designed to allow implementing very fast XML parsers
- minimal requirements - designed to be compatible with J2ME (Java 2 Micro Edition) to work and on small devices and to allow create XmlPull compliant parsers of very small memory footprint.

## 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:

- get instance of XmlPull factory
- (optional step) by default factory will produce parsers that are not namespace aware; to change setNamespaceAware() function must be called
- create an instance of the parser

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