kXML on Android | About | JavaDoc | GitHub Project

Moving to GitHub

The new project location is: https://github.com/stefanhaustein/kxml2

kXML on Android

kXML2 (or a compatible XML pull parser) should be available on all Android devices. Obtain a parser using this code fragment:

XmlPullParserFactory factory = XmlPullParserFactory.newInstance();
XmlPullParser parser = factory.newPullParser();

About kXML

kXML is a small XML pull parser, specially designed for constrained environments such as Applets, Personal Java or MIDP devices. In contrast to kXML 1, kXML 2 is based on the common XML pull API.

Pull based XML parsing combines some of the advantages of SAX and DOM:

kXML History and Versions

XP XP was the predecessor of kXML, a simple wrapper that turned a given SAX parser into a pull parser. XP was originally implemented to simplify message (de)serialization in the Infolayer project, which is quite cumbersome with push parsers (SAX).
kXML1 To use the pull parser on embedded devices, it was necessary to get rid of the SAX dependency. kXML1 is a simple pull parser, based on event objects. kXML1 is now deprecated, please use kXML2 instead. kXML1 is archieved at kxml.objectweb.org.
kXML2 The current version of kXML. In contrast to kXML1, it features cursor API instead of event objects, leading to a reduced footprint and less object creation overhead. kXML 2 is released under the BSD license.

Special Features

kXML has two "special" features that are intended to simplify developers' life in constrained environments:

XML Conformance

In order to keep kXML as small as possible, no efforts are made to recognize certain well-formedness errors that would require additional detection code, such as

Thus, kXML will accept some XML documents that should actually be rejected. Of course, an XML parser should detect all syntax errors to discourage the creation of bogous documents that work with one parser and do not work with another. Thus, if you are not limited by memory constraints, please use MXP, which is also faster than kXML.

Recommended Calling Conventions

When handing an XMLpull parser to subroutines, it is recommended that the current position is on a start tag (allowing the subroutine to analyze the attributes). The post condition should usually be that the current position is the matching end tag.

Parsing Element-Only and Text-Only Content

General XML content can be parsed with the XML pull API using a loop advanving to the next event and a switch statement that depends on the event type. However, when using XML for data transfer (in contrast to text documents), most XML elements contain either only text or only other elements (possibly with further sub-elements). For those common cases, the parsing process can be simplified significantly by using the XmlPull API methods nextTag and nextText. Additionally, the method require() may optionally be used to assert a certain parser state. The following sample illustrates both situations and methods. The outer element elements has element-only content; the contained text-elements have text-only content:


Parsing Code

parser.require(XmlPullParser.START_TAG, null, "elements");

while(parser.nextTag() == XmlPullParser.START_TAG) {
  parser.require(XmlPullParser.START_TAG, null, "text");

   // handle element content
   System.out.println("text content: "+ parser.nextText());

  parser.require(XmlPullParser.END_TAG, null, "text");

parser.require(XmlPullParser.END_TAG, null, "elements");

nextTag() advances to the next start or end tag, skipping insignificant events such as white space, comments and PIs. nextText() requires that the current position is a start tag. It returns the text content of the corresponding element. The post condition is that the current position is an end tag. Please note that the calls require() are optional assertions, they may be left out completely.