XML Parsers

• XML parsers extract the contents of an XML document and make them available to applications through APIs
• Parsers can be validating or non-validating
  • Validating parsers check if the document conforms a document type
  • However, nonvalidating parsers are generally lighter-weight
• Use of standard APIs (such as SAX) allows developers to substitute one parser for one another

XML Parsers and Java

• Historically, most work on XML involves Java
• Support for other languages (e.g. C++, Perl, Python) is available, but more limited
• In the following we will only discuss the Java API
• See book for how to use XML from within Perl

Simple API for XML (SAX)

• Standard interface for event-based XML parsing
• SAX is suitable when you don't need to create a tree structure for the contents of the document
• For example, for very large documents, you want to process them "as you go"

Event-based Parsing

• Applications instantiate a parser object and instruct to parse a specified document
• As the parser processes the XML data, it detects significant items
  • element start tags
  • contents of an element
  • ...
• The SAX API defines how the parser returns this information through call-backs on user objects

Event-based Parsing

• The application defines methods that the parser must call when certain events occur
• Applications register with the parser only for the events that they are interested in
  • Document markup (element start and end tags, text content, comments, ...)
  • Errors and the location of those errors

Event Handlers

• Components of a SAX-based application

  

SAX Interfaces

• Parser calls event handlers when appropriate events occur
• Handlers must conform to the the following interfaces
  • DocumentHandler
  • ErrorHandler
  • EntityResolver
  • DTDHandler
• All of these are defined in package org.xml.sax

SAX Helpers

• The SAX API also provides some helper classes in xml.org.sax.helpers
  • ParserFactory
  • AttributeListImpl

Parser

• parse(String s)
• parse(InputSource s)
• setDocumentHandler(DocumentHandler h)
• setErrorHandler(ErrorHandler h)
• setDTDHandler(DTDHandler h)
• setEntityResolver(EntityResolver h)

Parser

• The "set..." methods are used by the application to register handlers
• After registering one or more handlers, the application will call a parse() method
• The parser begins to read the XML data, but stops as it encounters a meaningful object (e.g. a start tag)
• Sends the event by calling the appropriate handler back

ParserFactory

• This is an additional convenience class for Java XML application writers
• To create an instance of Sun's XML Parser use

  Parser parser = ParserFactory.makeParser(
      "com.sun.xml.parser.Parser");

• This parser is part of the Java API for XML Parsing (JAXP)
  • See References

Validating Parser

• The parser we just created was a non-validating parser
  • It did not check the document against its DTD
  • Tradeoff between risk of not validating the document vs. speed of parsing and size of parser
• Many implementations also provide a validating parser
  • To create a validating parser in JAXP use

  Parser parser = ParserFactory.makeParser(
      "com.sun.xml.parser.ValidatingParser");

• If the document specifies a document type, the parser will validate the document against it

DocumentHandler

• startDocument()
• endDocument()
• startElement(String name, AttributeList atts)
• endElement(String name)
• characters(char[] ch, int start, int length)

DocumentHandler

DocumentHandler

• Create a parser using the ParserFactory

  try {
      Parser parser = ParserFactory.makeParser(...);
  } catch (Exception e) { 
      System.out.println("Error: " + e);
  }

• Create and register the document handler

  MyDocumentHandler dh =
      new MyDocumentHandler();
  parser.setDocumentHandler(dh);

Callbacks from the Parser

• The first method called is startDocument()

  public void startDocument() {
      inChapter = false;
      inChapterTitle = false;
  }

• startElement() is called when a start tag is encountered in the input stream

  public void startElement(String name,
      AttributeList atts) {
      if (name.equals("chapter") { 
          inChapter = true; 
      } else if (name.equals("title") && inChapter) {
          inChapterTitle = true;
      }
  }

Callbacks from the Parser

• endElement() is called on reading an end tag

  public void endElement(String name) {
      if (name.equals("chapter") { 
          inChapter = false; 
      } else (name.equals("title") {
          inChapterTitle = false;
      }
  }

• characters() is called when a string of text is encountered

  public void characters(char ch[], int start, int length) {
      String s = new String(ch, start, length);
      if (inChapterTitle == true) {
          chapterTitle[nextTitle++] = s;
      }
  }

AttributeList

• int getLength()
• String getName(int i)
• String getType(int i)
• String getType(String name)
• String getValue(int i)
• String getValue(String name)

AttributeList

• Print out elements and their attributes

  public void startElement(String name,
      AttributeList atts) {
      System.out.print("<" + name + " ");
      for (int i=0; i<atts.getLength(); i++) {
          System.out.print(atts.getName(i) + " = " +
          atts.getValue(i));
      }
      System.out.println(">");
  }

HandlerBase

• HandlerBase provides default implementations for each event, which you can override

  import org.xml.sax.*;
  import org.xml.sax.helpers.*;
  
  public class CountHandler extends HandlerBase {
      protected int numberOfElements = 0;
      
      public void endElement(String name) {
          numberElements++;
      }
      
      public int getNumberOfElements() {
          return numberOfElements;
      }
  }

Putting It All Together

• Application that counts number of elements in a document

  import org.xml.sax.*;
  import org.xml.sax.helpers.*;
  
  public class Count {
  
      public static void main(String args[]) {
              try {
          Parser parser = ParserFactory.makeParser(
              "com.sun.xml.parser.Parser");
          CountHandler ch = new CountHandler();
          parser.setDocumentHandler(ch);
          parser.parse("http://www.scs.carleton.ca/" +
              "~weiss/courses/205/examples/xml/order.xml");
          System.out.println("Number of elements: " + 
              ch.getNumberOfElements());
              } catch (Exception e) {
          e.printStackTrace();
              }
      }
  
  }

Purchase Order Example

• We conclude with a more extensive example
• Purchase orders encapsulate
  • Customer id
  • List of items ordered
• The following document and Java classes represent a purchase order
• Encoded in such manner, purchase orders can be exchanged with other applications

Purchase Order - Document

<purchase>
    <customerId>cu12345</customerId>
    <items>
        <item>
            <name>Sony CD Player</name>
            <id>cd00100</id>
            <quantity>1</quantity>
        </item>
        <item>
            <name>XML and Java</name>
            <id>bk10500</id>
            <quantity>2</quantity>
        </item>
    </items>
</purchase>

Purchase Order - Java Classes

public class Purchase {
  	protected String customerId;
  	protected Vector items;
  	
  	// constuctors
  	// getters and setters
}

public class Item {
  	protected String name;
  	protected String id;
  	protected int quantity;

  	// constuctors
  	// getters and setters
}

PurchaseHandler

• We can now implement a subclass of HandlerBase that
  • parses documents of the above form and
  • produces Java objects
• Important elements
  • Purchase object and getPurchase()
  • Represent the context (e.g. in name tag inside an item element) using flags
  • Context flags set in startElement(), unset in endElement()

PurchaseHandler - Declarations

import org.xml.sax.*;
import org.xml.sax.helpers.*;

public class PurchaseHandler extends HandlerBase {  
    protected boolean inCustomerId = false;
    protected boolean inItems = false;
    protected boolean inItem = false;
    protected boolean inItemName = false;
    protected boolean inItemId = false;
    protected boolean inItemQuantity = false;
  	
    protected Purchase purchase = null;
    protected Item item = null;
  
    public Purchase getPurchase() { 
        return purchase; 
    }

PurchaseHandler - startElement()

    public void startElement(String name,
        AttributeList atts) {
      	if (name.equals("purchase")) {
            purchase = new Purchase();
      	} else if (name.equals("customerId")) {
            inCustomerId = true;
      	} else if (name.equals("items")) {	  
            inItems = true;
        } else if (name.equals("item") && inItems) {
            inItem = true;
            item = new Item();	
        } else if (name.equals("name") && inItem) { 			
            inItemName = true;
        } else if (name.equals("id") && inItem) {
            inItemId = true;
      	} else if (name.equals("quantity") && inItem) {
            inItemQuantity = true;
      	}
    }

PurchaseHandler - characters()

    public void characters(char ch[], int start, 
        int length) {
        String s = new String(ch, start, length);
      	if (inCustomerId) {
            purchase.setCustomerId(s);
      	} else if (inItemName) {
            item.setName(s);
      	} else if (inItemId) {
            item.setId(s);
      	} else if (inItemQuantity) {
            item.setQuantity(Integer.parseInt(s));
      	}
    }

PurchaseHandler - endElement()

    public void endElement(String name) {
        if (name.equals("purchase")) {
            // optionally validate purchase
      	} else if (name.equals("customerId")) {
            inCustomerId = false;
      	} else if (name.equals("items")) {
            inItems = false;
      	} else if (name.equals("item") && inItems) {
            inItem = false;
            purchase.addItem(item);	
        } else if (name.equals("name") && inItem) {
            inItemName = false;
      	} else if (name.equals("id") && inItem) {
            inItemId = false;
        } else if (name.equals("quantity")) {
            inItemQuantity = false;
        }
    }
}

PuchaseTest

import org.xml.sax.*;
import org.xml.sax.helpers.*;

public class PuchaseTest {
    public static void main(String args[]) {
        Parser parser;
        try {
            parser = ParserFactory.makeParser(
            	"com.sun.xml.parser.Parser");
        } catch (ClassNotFoundException e) {
            System.err.println("Parser not found: " + e);
        } catch (Exception e) {
            System.err.println("Error: " + e);
        }
        PurchaseHandler handler = 
            new PurchaseHandler();
        parser.setDocumentHandler(handler);
        
        try {         	
            parser.parse("http://www.scs.carleton.ca/" +
            	"~weiss/examples/xml/order.xml");
  		} catch (SAXParseException e) {
            System.err.println("Parse error: " + e);
  		} catch (SAXException e) {
            System.err.println("Error: " + e);
  		} catch (IOException e) {
            System.err.println("Input Error: " + e);
        }
    }
}

References

• Java API for XML Parsing (Tutorial)
  • http://java.sun.com/xml/jaxp-docs-1.0.1/docs/tutorial/index.html
• SAX: Simple API for XML
  • http://www.megginson.com/SAX/index.html
• Installation instructions for JSWDK
  • installation.html