# kXML 2

kXML 2 implements the XmlPull API. Please find general information about XmlPull parsers including the interface documentation at xmlpull.org.

kXML 2 is licensed under the BSD license.

Naveen Balani has written a nice introduction to kxml 2 for IBM Developer Works.

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

    <elements>
      <text>text1</text>
      <text>text2</text>
    </elements>

Parsing Code

    parser.nextTag();
    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.