# 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: set of extensions for parser and serializer interfaces and their implementation that seemlesly add functionality to exisitng APIs
- Utility Methods: set of static methods that can be easily used (good source for few lines of code to solve typical problems)
- DOM2 Builder: simple class to convert XML event streaminto DOM element tree
- Parser pool: simple to use class to make pooling parser instances easy.
- SAX2 Driver: class that impements SAX2 XMLReader and allowsto convert stream of XML pull events into SAX2 events
- XML RPC parser: exmpale of use of XmlPull API to do non-trivial databinding

## 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));
        }

    }

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