A pull parser works in streaming mode like SAX. However, the client specifically requests the next chunk of data from the parser when it’s ready for it, rather than taking it whenever the parser is ready to provide it. Furthermore, the client has a limited ability to filter out some normally insignificant pieces such as comments and processing instructions. This can be as fast and as memory efficient as SAX parsing while perhaps being more familiar to many programmers.

The developing standard API for pull parsing is known as XMLPULL. This is currently implemented by two parsers, Enhydra’s kXML2 and Aleksander Slominski’s MXP1. The client application loads a parser-specific instance of the XmlPullParser interface. It sets the InputStream or Reader from which the parser will read the document. However, the parser does not actually read the document until the client calls the next() method. Then the parser reads just enough to report the next start-tag, text string, or end-tag from the document. (Actually, the parser may well read quite a bit more and buffer the result, but that’s an implementation detail that’s invisible to the client.) When the client has processed that unit of data, it asks the parser for the next unit. This continues until next() indicates that it’s at the end of the document. Example 5.10 demonstrates with an XMLPULL client for the Fibonacci XML-RPC server.

import org.xmlpull.v1.*;
import java.io.*;
import java.net.*;


public class FibonacciPullClient {

  public final static String DEFAULT_SERVER 
   = "http://www.elharo.com/fibonacci/XML-RPC";  
  
  public static void main(String[] args) {
      
    if (args.length <= 0) {
      System.out.println(
       "Usage: java FibonacciPullClient number url"
      );
      return;
    }
    
    String server = DEFAULT_SERVER;
    if (args.length >= 2) server = args[1];
      
    try {
      // Connect to the server
      URL u = new URL(server);
      URLConnection uc = u.openConnection();
      HttpURLConnection connection = (HttpURLConnection) uc;
      connection.setDoOutput(true);
      connection.setDoInput(true); 
      connection.setRequestMethod("POST");
      OutputStream out = connection.getOutputStream();
      Writer wout = new OutputStreamWriter(out);
      
      // Transmit the request XML document
      wout.write("<?xml version=\"1.0\"?>\r\n");  
      wout.write("<methodCall>\r\n"); 
      wout.write(
       "  <methodName>calculateFibonacci</methodName>\r\n");
      wout.write("  <params>\r\n"); 
      wout.write("    <param>\r\n"); 
      wout.write("      <value><int>" + args[0] 
       + "</int></value>\r\n"); 
      wout.write("    </param>\r\n"); 
      wout.write("  </params>\r\n"); 
      wout.write("</methodCall>\r\n"); 
      
      wout.flush();
      wout.close();      

      // Load the parser
      XmlPullParserFactory factory 
       = XmlPullParserFactory.newInstance();
      XmlPullParser parser = factory.newPullParser();
      
      // Read the response XML document
      InputStream in = connection.getInputStream();
      parser.setInput(in, null);
      //                  ^^^^
      // Encoding is not known; the parser should guess it based
      // on the content of the stream.
      
      int event;
      while ( 
       (event = parser.next()) != XmlPullParser.END_DOCUMENT) {
        if( event ==  XmlPullParser.START_TAG) {
          if ( "double".equals(parser.getName()) ) {
            String value = parser.nextText();
            System.out.println(value);
          } // end if
        } // end if 
      } // end while
      
      in.close();
      connection.disconnect();

    }
    catch (Exception e) {
      System.err.println(e); 
    }
  
  } 

}

Like SAX, XMLPULL is a read-only API. Thus this program begins by sending the request to the server by writing strings onto an OutputStream, just as in the SAX client. The style for reading the response is quite new, however. The pull parser’’s next() method is repeatedly invoked. Each time it returns an int type code, XmlPullParser.START_TAG, XmlPullParser.TEXT, XmlPullParser.END_TAG, and so forth. The loop exits when the next() method returns XmlPullParser.END_DOCUMENT. Until that happens, we look at each start-tag returned to see if its name is double. If it is, then the program invokes nextText() to return the complete text content of that element as a String. This is printed on System.out.