Quick Introduction to XMLPULL V1 API

XMLPULL V1 API is ...

Main features

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.0.*) 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 facotry
(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

and the code to do this may look similar ot this:

        XmlPullParserFactory factory = XmlPullParserFactory.newInstance();
        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 event is END_DOCUMENT:

    public void processDocument(XmlPullParser xpp)
        throws XmlPullParserException, IOException
    {
        int eventType = xpp.getType();
        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:

    public void processText (XmlPullParser xpp) throws XmlPullParserException
    {
        char ch[] = xpp.getTextCharacters();
        int start = xpp.getTextCharactersStart();
        int length = xpp.getTextCharactersLength();
        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 MyXmlPull.java file in src/java/samples directory.

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