XmlPull API Addons

What is it?

Addons are reusable components that built on top of XmlPull API.

All addons can be compiled by build target addons (use: ant addons)

Following addons are available:

 

Wrapper: Extended Pull Parser and Serializer Interfaces

This package provides extended XmlPullParser and XmlSerializer interfaces called XmlPullParserWrapper and XmlSerializerWrapper that has additional methods that make it more convenient and more concise to write parsing and serialzing code by providing seemlesly integrated additional methods.

Wrappers can be uesd exactly the same as XmlPullParser and XmlSerialzier as those interface extend them.

Here is example usage:

import org.xmlpull.v1.wrapper.*;

XmlPullWrapperFactory wf = XmlPullWrapperFactory.newInstance();

XmlPullParserWrapper pw = wf.newPullParserWrapper();
pw.setInput( ... );
pw.require(XmlPullParser.START_TAG, ..., ...);
pw.skipSubTree();

XmlSerializerWrapper ser = wf.newSerializerWrapper();
ser.setOutput(out);
ser.setCurrentNamespaceForElements("http://www.w3.org/1999/xhtml");
ser.startTag("p").attribute("class", "abstract").text("Hello");
ser.endTag("p");
ser.fragment("<p class=\"hint\">write blog title below</p>");

Another example is how to quickly copy XML input to output:

while (pp.nextToken() != XmlPullParser.END_DOCUMENT) {
  ser.event(pp);
}

It can be compiled by build target wrapper

Source code is available in addons/java/wrapper  (view CVS).

TODO: add link to JavaDoc

 

Util Addon

This class provides set of static utility methods for XmlPull parser and serializer.

Here is example usage:

import org.xmlpull.v1.util.XmlPullUtil;

XmlPullParser parser = ...
parser.require(XmlPullParser.START_TAG, ..., ...);
XmlPullUtil.skipSubTree(pp);

It can be compiled by build target util

Source code is available in addons/java/util (view CVS).

TODO: add link to JavaDoc

 

DOM2 builder

This is very simple class to build DOM2 tree using XmlPull parser.

Here is example usage:

import org.xmlpull.v1.dom2_builder.DOM2XmlPullBuilder;

Reader reader = ...
DOM2XmlPullBuilder builder = new DOM2XmlPullBuilder();
dom2builder.parse(reader);

It can be compiled by build target dom2_builder

Source code is available in addons/java/dom2_builder.

NOTE: this is very simple class and builds DOM2 tree that contains only elements and text content (collated).

Source code is available in addons/java/dom2_builder (view CVS).

 

Parser pool

This class provides simple parser pool to facilitate parser reuse.

Example usage:

import org.xmlpull.v1.parser_pool.XmlPullParserPool;

XmlPullParserPool pool = new XmlPullParserPool();
XmlPullParser parser = pool.getPullParserFromPool();
// use parser ...
pool.returnPullParserToPool(p1);

It can be compiled by build target parser_pool

Source code is available in addons/java/parser_pool.

NOTE: parser pool is safe to share between multiple threads but  parser instances are not safe to share.

Source code is available in addons/java/parser_pool (view CVS).

 

SAX2 driver

This addon allows to use SAX2 API with XmlPull parser. This driver implements SAX2

To use simply set system property -Dorg.xml.sax.driver=org.xmlpull.v1.sax2.Driver and then SAX2 standard API:

XMLReader parser = XMLReaderFactory.createXMLReader ();

or manually create driver:

XMLReader parser = new org.xmlpull.v1.sax2.Driver();

This addon can be compiled by build target sax2

Source code is available in addons/java/sax2_driver.

NOTE: this driver is not going to work in MIDP environments. To port it to J2ME MIDP it is required to change also SAX2 API and to modify Driver not to use URL class that is not available in MIDP (check Driver.parse() method).

Source code is available in addons/java/sax2 (view CVS).

 

XML RPC parser

It can be compiled by build target xmlrpc

Source code is available in addons/java/dom2_builder (view CVS).

 

Additional notes

How to extend SAX2 driver to provide Attributes that are safe to keep after startElement?

If you want to extend SAX2 Driver to provides a separate Attributes object for each startElement call (so it is safe to keep the reference to Attributes) then create class AttributesCachingDriver that extends current SAX2 driver (need to do it was requested by Holger Krug), for example:

import org.xml.sax.SAXException;
import org.xml.sax.helpers.AttributesImpl;

import org.xmlpull.v1.XmlPullParser;
import org.xmlpull.v1.XmlPullParserException;

import org.xmlpull.v1.sax2.Driver;

public class AttributesCachingDriver extends Driver
{
    public AttributesCachingDriver() throws XmlPullParserException {
        super();
    }

    public AttributesCachingDriver(XmlPullParser pp) throws XmlPullParserException {
        super(pp);
    }

    /**
     * Calls startElement(String, String, String, Attributes) startElement} on the
     * ContentHandlerwith copied attribute values. The Attributes object may
     * be stored as each call gets a new copy of Attributes.
     */
    protected void startElement(String namespace, String localName, String qName) throws SAXException {
        contentHandler.startElement(namespace, localName, qName, new AttributesImpl(this));
    }

}
Aleksander Slominski and Stefan Haustein

Last modified $Id: addons.html,v 1.9 2005/08/29 17:30:49 aslom Exp $