Chapter 11

Event-Driven Programming

WHAT YOU WILL LEARN IN THIS CHAPTER:

• Necessity of XML data access methods: SAX and .NET’s XMLReader
• Why SAX and XMLReader are considered event-driven methods
• How to use SAX and XMLReader
• The right time to choose one of these methods to process your XML

There are many ways to extract information from an XML document. You’ve already seen how to use the document object model and XPath; both of these methods can be used to find any relevant item of data. Additionally, in Chapter 12 you’ll meet LINQ to XML, Microsoft’s latest attempt to incorporate XML data retrieval in its universal data access strategy.

Given the wide variety of methods already available, you may be wondering why you need more, and why in particular do you need event-driven methods? The main answer is because of memory limitations. Other XML processing methods require that the whole XML document be loaded into memory (that is, RAM) before any processing can take place. Because XML documents typically use up to four times more RAM than the size of the file containing the document, some documents can take up more RAM than is available on a computer; it is therefore necessary to find an alternative method to extract data. This is where event-driven paradigms come into play. Instead of loading the complete file into memory, the file is processed in sequence. There are two ways to do this: SAX and .NET’s XMLReader. Both are covered in this chapter.

UNDERSTANDING SEQUENTIAL PROCESSING

There are two main ways of processing a file sequentially. The first relies on events being fired whenever specific items are found; whether you respond to these events is up to you. For example, say an event is fired when the opening tag of the root element is encountered, and the name of this element is passed to the event handler. Any time any textual content is found after this, another event is fired. In this scenario there would also be events that capture the closing of any elements with the final event being fired when the closing tag of the root element is encountered.

The second method is slightly different in that you tell the processor what sort of content you are interested in. For example, you may want to read an attribute on the first child under the root element. To do so, you instruct the XML reader to move to the root element and then to its first child. You would then begin to read the attributes until you get to the one you need. Both of these methods are similar conceptually, and both cope admirably with the problem of larger memory usage posed by using the DOM that requires the whole XML document to be loaded into memory before being processed.

Processing files in a sequential fashion includes one or two downsides, however. The first is that you can’t revisit content. If you read an element and then move on to one of its siblings or children, you can’t then go back and examine one of its attributes without starting from the beginning again. You need to plan carefully what information you’ll need. The second problem is validation. Imagine you receive the document shown here:

<document>
  <data>Here is some data.</data>
  <data>Here is some more data.</data>
</document>

This document is well-formed, but what if its schema states that after all <data> elements there should be a <summary> element? The processor will report the elements and text content that it encounters, but won’t complain that the document is not valid until it reaches the relevant point. You may not care about the extra element, in which case you can just extract whatever you need, but if you want to validate before processing begins, this usually involves reading the document twice. This is the price you pay for not needing to load the full document into memory.

In the following sections you’ll examine the two methods in more detail. The pure event-driven method is called SAX and is commonly used with Java, although it can be used from any language that supports events. The second is specific to .NET and uses the System.Xml.XmlReader class.

USING SAX IN SEQUENTIAL PROCESSING

SAX stands for the Simple API for XML, and arose out of discussions on the XML-DEV list in the late 1990s.

---

NOTE The archives for the XML-DEV list are available at http://lists.xml.org/archives/xml-dev/. The list is still very active and any XML-related problems are usually responded to within hours, if not minutes.

---

Back then people were having problems because different parsers were incompatible. David Megginson took on the job of coordinating the process of specifying a new API with the group. On May 11, 1998, the SAX 1.0 specification was completed. A whole series of SAX 1.0–compliant parsers then began to emerge, both from large corporations, such as IBM and Sun, and from enterprising individuals, such as James Clark. All of these parsers were freely available for public download.

Eventually, a number of shortcomings in the specification became apparent, and David Megginson and his colleagues got back to work, finally producing the SAX 2.0 specification on May 5, 2000. The improvements centered on added support for namespaces and tighter adherence to the XML specification. Several other enhancements were made to expose additional information in the XML document, but the core of SAX was very stable. On April 27, 2004, these changes were finalized and released as version 2.0.2.

SAX is specified as a set of Java interfaces, which initially meant that if you were going to do any serious work with it, you were looking at doing some Java programming using Java Development Kit (JDK) 1.1 or later. Now, however, a wide variety of languages have their own version of SAX, some of which you learn about later in the chapter. In deference to the SAX tradition, however, the examples in this chapter are written in Java.

All the latest information about SAX is at www.saxproject.org. It remains a public domain, open source project hosted by SourceForge. To download SAX, go to the homepage and browse for the latest version, or go directly to the SourceForge project page at http://sourceforge.net/projects/sax.

This is one of the extraordinary things about SAX — it isn’t owned by anyone. It doesn’t belong to any consortium, standards body, company, or individual. In other words, it doesn’t survive because some organization or government says that you must use it to comply with their standards, or because a specific company supporting it is dominant in the marketplace. It survives because it’s simple and it works.

Preparing to Run the Examples

The SAX specification does not limit which XML parser you use with your document. It simply sits on top of it and reports what content it finds. A number of different parsers are available out in the wild, but these examples use the one that comes with the JDK.

If you don’t have the JDK already installed, perform the following steps to do so:

java -version

java version “1.6.0_25”
Java(TM) SE Runtime Environment (build 1.6.0_25-b06)
Java HotSpot(TM) 64-Bit Server VM (build 20.0-b11, mixed mode)

Once you have the correct output showing, you are all set to try the examples in this chapter.

Receiving SAX Events

SAX works by firing an event each time it comes across any content. An abbreviated list of events is shown in Table 11-1.

TABLE 11.1: SAX Events

When SAX was originally developed, it was quite a chore to create a class that handled all these events. Even if you didn’t care about any comments or processing instructions, you still had to write a method to cope with them being fired from the SAX processor. The situation has improved since then and you can base your class on what is known as the DefaultHandler. This handles all the events for you, and you have to write methods only for those in which you are interested. For example, the startDocument, startElement, and characters events are the most commonly handled ones.

The following Try It Out puts the previous theory into practice. You’ll use SAX to read a simple XML file and report back on some of the events that are received.

<People>
  <Person bornDate=”1874-11-30” diedDate=”1965-01-24”>
    <Name>Winston Churchill</Name>
    <Description>
      Winston Churchill was a mid-20th century British politician who
      became famous as Prime Minister during the Second World War.
    </Description>
  </Person>
  <Person bornDate=”1917-11-19” diedDate=”1984-10-31”>
    <Name>Indira Gandhi</Name>
    <Description>
      Indira Gandhi was India's first female prime minister and was
      assassinated in 1984.
    </Description>
  </Person>
  <Person bornDate=”1917-05-29” diedDate=”1963-11-22”>
    <Name>John F. Kennedy</Name>
    <Description>
      JFK, as he was affectionately known, was a United States president
      who was assassinated in Dallas, Texas.
    </Description>
  </Person>
</People>

import org.xml.sax.*;
import org.xml.sax.helpers.*;
import java.io.*;
 
public class SaxParser1 extends DefaultHandler {
 
  public void startDocument( ) throws SAXException {
    System.out.println( “SAX Event: START DOCUMENT” );
   }
 
  public void endDocument( ) throws SAXException {
    System.out.println( “SAX Event: END DOCUMENT” );
   }
 
  public void startElement(String namespaceURI,
                           String localName,
                           String qName,
                           Attributes attr ) throws SAXException {
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]”);
   }
 
  public void endElement(String namespaceURI,
                         String localName,
                         String qName ) throws SAXException {
    System.out.println( “SAX Event: END ELEMENT[ “ + localName + “ ]” );
   }
 
  public void characters(char[] ch,
                         int start,
                         int length ) throws SAXException {
    System.out.print( “SAX Event: CHARACTERS[ “ );
 
    try {
      OutputStreamWriter output = new OutputStreamWriter(System.out);
      output.write( ch, start,length );
      output.flush();
    } catch ( Exception e ) {
     e.printStackTrace();
    }
 
    System.out.println( “ ]” );
   }
 
  public static void main( String[] argv ){
    String inputFile = argv[0];
    System.out.println( “Processing '” + inputFile + “'.” );
    System.out.println( “SAX Events:” );
    try {
      XMLReader reader = XMLReaderFactory.createXMLReader();
      reader.setContentHandler( new SaxParser1() );
      reader.parse( new InputSource(
                 new FileReader( inputFile )));
    } catch ( Exception e ) {
       e.printStackTrace();
    }
  }
}

javac SaxParser1.java

java SaxParser1 People.xml

SAX Events:
SAX Event: START DOCUMENT
SAX Event: START ELEMENT[ People ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Person ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Name ]
SAX Event: CHARACTERS[ Winston Churchill ]
SAX Event: END ELEMENT[ Name ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Description ]
SAX Event: CHARACTERS[
      Winston Churchill was a mid-20th century British politician who
      became famous as Prime Minister during the Second World War. ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Description ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Person ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Person ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Name ]
SAX Event: CHARACTERS[ Indira Gandhi ]
SAX Event: END ELEMENT[ Name ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Description ]
SAX Event: CHARACTERS[
      Indira Gandhi was India's first female prime minister and was
      assassinated in 1984. ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Description ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Person ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Person ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Name ]
SAX Event: CHARACTERS[ John F. Kennedy ]
SAX Event: END ELEMENT[ Name ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Description ]
SAX Event: CHARACTERS[
      JFK, as he was affectionately known, was a United States president
      who was assassinated in Dallas, Texas. ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Description ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Person ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ People ]
SAX Event: END DOCUMENT

  public void startDocument( ) throws SAXException {
    System.out.println( “SAX Event: START DOCUMENT” );
  }

  public void endDocument( ) throws SAXException {
    System.out.println( “SAX Event: END DOCUMENT” );
  }

  public void startElement(String namespaceURI,
                           String localName,
                           String qName,
                           Attributes attr ) throws SAXException {
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]” );
  }

  public void endElement(String namespaceURI,
                         String localName,
                         String qName ) throws SAXException {
    System.out.println( “SAX Event: END ELEMENT[ “ + localName + “ ]” );
  }

  public void characters(char[] ch,
                         int start,
                         int length ) throws SAXException {
    System.out.print( “SAX Event: CHARACTERS[ “ );
 
    try {
      OutputStreamWriter output = new OutputStreamWriter(System.out);
      output.write( ch, start,length );
      output.flush();
    } catch (Exception e) {
     e.printStackTrace();
    }
 
    System.out.println( “ ]” );
  }

  public static void main( String[] argv ){
    String inputFile = argv[0];
    System.out.println( “Processing '” + inputFile + “'.” );
    System.out.println( “SAX Events:” );
    try {
      XMLReader reader = XMLReaderFactory.createXMLReader();
      reader.setContentHandler( new SaxParser1() );
      reader.parse( new InputSource(
                 new FileReader( inputFile )));
    }catch ( Exception e ) {
       e.printStackTrace();
    }
  }

Now that you’ve seen the basics in action, in the following activity you see how you can deal with attributes within an XML document.

                           public void startElement
                          (String namespaceURI,
                           String localName,
                           String qName,
                           Attributes attr ) throws SAXException {
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]” );
    for ( int i = 0; i < attr.getLength(); i++ ){
    System.out.println( “ ATTRIBUTE: “ + attr.getLocalName(i) +  “ VALUE: “
    + attr.getValue(i) );
    }
  }

   javac SaxParser2.java

   java SaxParser2 People.xml

SAX Event: START ELEMENT[ Person ]
 ATTRIBUTE: bornDate VALUE: 1917-05-29
 ATTRIBUTE: diedDate VALUE: 1963-11-22
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Name ]
SAX Event: CHARACTERS[ John F. Kennedy ]
SAX Event: END ELEMENT[ Name ]
SAX Event: CHARACTERS[
     ]
SAX Event: START ELEMENT[ Description ]
SAX Event: CHARACTERS[
      JFK, as he was affectionately known, was a United States president
      who was assassinated in Dallas, Texas. ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Description ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ Person ]
SAX Event: CHARACTERS[
     ]
SAX Event: END ELEMENT[ People ]

    for ( int i = 0; i < attr.getLength(); i++ ){
    System.out.println( “ ATTRIBUTE: “ + attr.getLocalName(i) +  “ VALUE: “
     + attr.getValue(i) );
    }

The two previous Try It Outs have both used the characters event to directly display any text nodes in the XML document reported by the SAX parser. There are two problems with this approach. First is the fact that you simply wrote any content directly to the output stream, in this case the console window. Usually you will want to store the text in a variable for processing. The second problem with the characters event is that it is not guaranteed to return all of an element’s content in one call. Many times you’ll find that a long block of text is broken down into one or more characters events. The next section shows a more sophisticated way to handle one or more characters events.

Handling the characters Event

A better way to handle the characters event is to build up the entire text content from the multiple firings of the event using the startElement and endElement events to indicate which characters belong to each element. To do so, follow these steps:

public class SaxParser3 extends DefaultHandler {
 
  private StringBuffer buffer = new StringBuffer();

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes attr ) throws SAXException {
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]” );
    for ( int i = 0; i < attr.getLength(); i++ ){
    System.out.println( “ ATTRIBUTE: “
    + attr.getLocalName(i) +  “ VALUE: “ + attr.getValue(i) );
    }
    
    buffer.setLength(0);
  } 

  public void characters(char[] ch,
                         int start,
                         int length ) throws SAXException {
    try {
      buffer.append(ch, start, length); 
    } catch (Exception e) {
     e.printStackTrace();
    }
  }

  public void endElement(String namespaceURI,
                         String localName,
                         String qName ) throws SAXException {
    System.out.print( “SAX Event: CHARACTERS[ “ );
    System.out.println(buffer.toString());
    System.out.println( “ ]” );     
    System.out.println( “SAX Event: END ELEMENT[ “ + localName + “ ]” );
  }

The entire code is shown in Listing 11-3.

LISTING 11-3: SaxParser3.java

import org.xml.sax.*;
import org.xml.sax.helpers.*;
import java.io.*;
 
public class SaxParser3 extends DefaultHandler {
 
  private StringBuffer buffer = new StringBuffer();
 
  public void startDocument( ) throws SAXException {
    System.out.println( “SAX Event: START DOCUMENT” );
  }
 
  public void endDocument( ) throws SAXException {
    System.out.println( “SAX Event: END DOCUMENT” );
  }
 
  public void startElement(String namespaceURI,
                           String localName,
                           String qName,
                           Attributes attr ) throws SAXException {
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]”);
    for ( int i = 0; i < attr.getLength(); i++ ){
    System.out.println( “ ATTRIBUTE: “
    + attr.getLocalName(i) +  “ VALUE: “ + attr.getValue(i) );
    }
    
    buffer.setLength(0);
  }
 
  public void endElement(String namespaceURI,
                         String localName,
                         String qName ) throws SAXException {
    System.out.print( “SAX Event: CHARACTERS[ “ );
    System.out.println(buffer.toString());
    System.out.println( “ ]” );     
    System.out.println( “SAX Event: END ELEMENT[ “ + localName + “ ]” );
  }
 
  public void characters(char[] ch,
                         int start,
                         int length ) throws SAXException {
    try {
      buffer.append(ch, start, length); 
    } catch (Exception e) {
     e.printStackTrace();
    }
  }  
 
  public static void main( String[] argv ){
    String inputFile = argv[0];
    System.out.println( “Processing '” + inputFile + “'.” );
    System.out.println( “SAX Events:” );
    try {
      XMLReader reader = XMLReaderFactory.createXMLReader();
      reader.setContentHandler( new SaxParser3() );
      reader.parse( new InputSource(
                 new FileReader( inputFile )));
    }catch ( Exception e ) {
       e.printStackTrace();
    }
  }
}

The results from running this are the same as the earlier version, but now you have a much more flexible way of coping with textual data. This technique does not work, however, if you have mixed content. In that case you would need to have separate buffers for each element’s content and keep track of which one was needed via flags set in startElement and endElement.

So far you’ve treated all character data as significant, even the whitespace that comes between elements such as <Name> and <Description>, which is only there to make the XML more human-readable. The next section shows how you can use the ignorableWhitespace event to treat significant and insignificant whitespace differently.

Using the ignorableWhitespace Event

The ignorableWhitespace event is very similar to the characters event. It has the same signature:

public void ignorableWhitespace(char[ ] ch, int start, int len)
   throws SAXException

As with the characters event, it can be called multiple times for a block of contiguous whitespace. The reason that the event was not called at all when parsing the People.xml file is that the parser can tell if whitespace is significant or not only by referring to a document type definition (DTD). If there were a DTD associated with your document that said that each <Person> element contained only parsed character data (PCDATA), the linefeeds between elements would be taken as insignificant whitespace and reported accordingly.

Another event that is thrown by the SAX parser is when an external entity is encountered, but for some reason not retrieved or expanded.

Understanding the skippedEntity Event

The skippedEntity event, much like the ignorableWhitespace event, alerts the application that the SAX parser has encountered information it believes the application can or must skip. In the case of the skippedEntity event, the SAX parser has not expanded an entity reference it encountered in the XML document. An entity might be skipped for several reasons:

• The entity is a reference to an external resource that cannot be parsed or cannot be found
• The entity is an external general entity and the http://xml.org/sax/features/external-general-entities feature is set to false
• The entity is an external parameter entity and the http://xml.org/sax/features/external-parameter-entities feature is set to false

You learn more about the external-general-entities and external-parameter-entities features later in this chapter. The skippedEntity event is declared as follows:

public void skippedEntity(String name)
  throws SAXException

The name parameter is the name of the entity that was skipped. It begins with % in the case of a parameter entity. SAX considers the external DTD subset an entity, so if the name parameter is [dtd], it means the external DTD subset was not processed. For more information on DTDs, refer to Chapter 4.

Applications can make use of processing instructions within an XML document, although they are not that common. The most common one is xml-stylesheet, which is recognized by browsers as an instruction to transform the current XML using the specified XSLT.

Handling the processingInstruction Event

The signature of the processingInstruction event is as follows:

public void processingInstruction(String target, String data)
   throws SAXException

If you were writing an application that needed to process the common xml-stylesheet instruction and it encountered the following:

<?xml-stylesheet type=”text/xsl” href=”myTransform.xsl”?>

The target parameter would be set to xml-stylesheet and the data parameter would contain type=”text/xsl” href=”myTransform.xsl”. Notice how the data is not broken into separate attributes; this is because processing instructions don’t have them. The fact that two pieces of data are referred to as type and href is really just coincidental — these two items are usually called pseudo-attributes.

You probably don’t need to be reminded at this point that the XML declaration at the start of an XML document is not really a processing instruction, and as such it shouldn’t result in a processingInstruction event. If it does, you should switch to another parser quickly.

Handling Invalid Content

What happens if, while you are parsing a document, you come across some data that is invalid? Hopefully this would have already been caught by an earlier validation process, either via a DTD, XML Schema, or one of the other methods discussed in previous chapters. However, sometimes business rules exist that cannot be expressed easily in the chosen validation language. For example, in DTDs and version 1.0 of XML Schema, it’s not possible to say: if attribute x equals y then the next element should be <a>, otherwise it should be <b>. If you come across this sort of situation or a similar one where you want to report a fatal error, the standard way to do so is to throw a SAXException. You may have noticed that all the standard parser events throw this. The SAXException has three constructors. The simplest takes a string as its parameter; this can be used to specify the reason for the error and any other information such as the location. The second constructor takes an Exception as its sole argument. This is for when you have already trapped an Exception and want to wrap it. The third constructor takes both a string and an Exception. This means you can trap an Exception and then add your own message to add details about where the error occurred, and so on. One way to do this is to use another event handler, setDocumentLocator.

Using the setDocumentLocator Event

The setDocumentLocator event has only one argument, an instance of the Locator class. The methods for this class are shown in Table 11-2:

TABLE 11.2: Locator Methods

Although it is often used for increasing the helpfulness of error messages, it can be used elsewhere, as the following activity shows.

public class SaxParser4 extends DefaultHandler {
 
  private Locator docLocator = null;
  private StringBuffer buffer = new StringBuffer();

  public void setDocumentLocator(Locator locator)
  {
    docLocator = locator;
  }

  public void startElement(String namespaceURI,
                           String localName,
                           String qName,
                           Attributes attr ) throws SAXException {
    int lineNumber = 0;
    if (docLocator != null)
    {
      lineNumber = docLocator.getLineNumber();      
    }    
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]”);
    if (lineNumber != 0)
    {
      System.out.println(	”(Found at line number: “ + lineNumber + “.)”);
    }
    for ( int i = 0; i < attr.getLength(); i++ ){
    System.out.println( “ ATTRIBUTE: “ + attr.getLocalName(i) +
    “ VALUE: “ + attr.getValue(i) );
    }

   try {
      XMLReader reader = XMLReaderFactory.createXMLReader();
      reader.setContentHandler(new SaxParser4());
      reader.parse( new InputSource(
                 new FileReader( inputFile )));
    }

java SaxParser4 People.xml

Processing 'people.xml'.
SAX Events:
SAX Event: START DOCUMENT
SAX Event: START ELEMENT[ People ]
(Found at line number: 1.)
SAX Event: START ELEMENT[ Person ]
(Found at line number: 2.)
 ATTRIBUTE: bornDate VALUE: 1874-11-30
 ATTRIBUTE: diedDate VALUE: 1965-01-24
SAX Event: START ELEMENT[ Name ]
(Found at line number: 3.)
SAX Event: CHARACTERS[ Winston Churchill
 ]
SAX Event: END ELEMENT[ Name ]
SAX Event: START ELEMENT[ Description ]
(Found at line number: 4.)
SAX Event: CHARACTERS[
      Winston Churchill was a mid 20th century British politician who
      became famous as Prime Minister during the Second World War.
 ]
SAX Event: END ELEMENT[ Description ]
SAX Event: CHARACTERS[
      Winston Churchill was a mid 20th century British politician who
      became famous as Prime Minister during the Second World War.
 
 ]
SAX Event: END ELEMENT[ Person ]

  public void setDocumentLocator(Locator locator)
  {
    docLocator = locator;
  }

    int lineNumber = 0;
    if (docLocator != null)
    {
      lineNumber = docLocator.getLineNumber();      
    }    
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]” );
    if (lineNumber != 0)
    {
      System.out.println(“	(Found at line number: “ + lineNumber + “.)”);
    }

import org.xml.sax.*;
import org.xml.sax.helpers.*;
import java.io.*;
 
public class SaxParser4 extends DefaultHandler {
 
  private Locator docLocator = null;
  private StringBuffer buffer = new StringBuffer();
  
  public void setDocumentLocator(Locator locator)
  {
    docLocator = locator;
  }
 
  public void startDocument( ) throws SAXException {
    System.out.println( “SAX Event: START DOCUMENT” );
  }
 
  public void endDocument( ) throws SAXException {
    System.out.println( “SAX Event: END DOCUMENT” );
  }
 
  public void startElement(String namespaceURI,
                           String localName,
                           String qName,
                           Attributes attr ) throws SAXException {
    int lineNumber = 0;
    if (docLocator != null)
    {
      lineNumber = docLocator.getLineNumber();      
    }    
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]”);
    if (lineNumber != 0)
    {
      System.out.println(“	(Found at line number: “ + lineNumber + “.)”);
    }
    for ( int i = 0; i < attr.getLength(); i++ ){
    System.out.println( “ ATTRIBUTE: “ + attr.getLocalName(i) +  “ VALUE: “
                        + attr.getValue(i) );
    }
    
    buffer.setLength(0);
  }
 
  public void endElement(String namespaceURI,
                         String localName,
                         String qName ) throws SAXException {
    System.out.print( “SAX Event: CHARACTERS[ “ );
    System.out.println(buffer.toString());
    System.out.println( “ ]” );     
    System.out.println( “SAX Event: END ELEMENT[ “ + localName + “ ]” );
  }
 
  public void characters(char[] ch,
                         int start,
                         int length ) throws SAXException {
    try {
      buffer.append(ch, start, length); 
    } catch (Exception e) {
     e.printStackTrace();
    }
  }  
 
  public static void main( String[] argv ){
    String inputFile = argv[0];
    System.out.println (“Processing '” + inputFile + “'.” );
    System.out.println( “SAX Events:” );
    try {
      XMLReader reader = XMLReaderFactory.createXMLReader();
      reader.setContentHandler(new SaxParser4());
      reader.parse( new InputSource(
                 new FileReader( inputFile )));
    }catch ( Exception e ) {
       e.printStackTrace();
    }
  }
}

It’s easy to see how using setDocumentLocator and storing the reference to the input document could be used to improve the information produced by an error handler. Instead of just the reason for the error, the location of the offending item could also be given.

Using the ErrorHandler Interface

So far all the information about the XML has been passed via the ContentHandler interface. Error information, however, comes from ErrorHandler. Fortunately, the DefaultHandler class also provides stubs for the three events this interface fires. The three events are shown in the Table 11-3.

TABLE 11.3: Events Fired By ErrorHandler

The default implementation within DefaultHandler simply throws a SAXException when these events are fired. If you want to do anything other than that, such as include the line number of the offending code, you need to do two things:

      XMLReader reader = XMLReaderFactory.createXMLReader();
      SaxParser5 parser = new SaxParser5();
      reader.setContentHandler(parser);
      reader.setErrorHandler(parser);

If you want to trap specific errors, such as those generated when document validation fails, you will also need to use feature activation to enable this. Feature activation is covered later in the chapter.

The following Try It Out shows how to make use of the events of ErrorHandler. It demonstrates the preliminary steps you need to take to turn on full error handling and then deliberately gives the parser a flawed document to see the events in action.

  public static void main( String[] argv ){
    String inputFile = argv[0];
    System.out.println(“Processing '” + inputFile + “'.”);
    System.out.println( “SAX Events:” );
    try {
      XMLReader reader = XMLReaderFactory.createXMLReader();
      SaxParser5 parser = new SaxParser5();
      reader.setContentHandler(parser);
      reader.setErrorHandler(parser);
      reader.parse( new InputSource(
                 new FileReader( inputFile )));
    }catch ( Exception e ) {
       e.printStackTrace();
    }
  }

            reader.setErrorHandler(parser);
      try
      {
        reader.setFeature(“http://xml.org/sax/features/validation”, true);
      } catch (SAXException e) {
      System.err.println(“Cannot activate validation”);
      }
 
      reader.parse( new InputSource(
                 new FileReader( inputFile )));

<!DOCTYPE People [
  <!ELEMENT People (Person*)>
  <!ELEMENT Person (Name, Description)>
  <!ATTLIST Person bornDate CDATA #REQUIRED>
  <!ATTLIST Person diedDate CDATA #REQUIRED>
  <!ELEMENT Name (#PCDATA)>
  <!ELEMENT Description (#PCDATA)>
]>
<People>
<!-- rest of people.xml -->
</People>

  public void warning (SAXParseException exception)
    throws SAXException {
    System.err.println(“[Warning] “ +
      exception.getMessage() + “ at line “ +
      exception.getLineNumber() + “, column “ +
      exception.getColumnNumber() );
  }
 
  public void error (SAXParseException exception)
    throws SAXException {
    System.err.println(“[Error] “ +
      exception.getMessage() + “ at line “ +
      exception.getLineNumber() + “, column “ +
      exception.getColumnNumber() );
  }
 
  public void fatalError (SAXParseException exception)
    throws SAXException {
    System.err.println(“[Fatal Error] “ +
      exception.getMessage() + “ at line “ +
      exception.getLineNumber() + “, column “ +
      exception.getColumnNumber() );
    throw exception;
  }

[Error] Attribute “diedDate” is required and must be specified for element type
“Person” at line 17, column 33
SAX Event: START ELEMENT[ Person ]
        (Found at line number: 17.)
 ATTRIBUTE: bornDate VALUE: 1917-11-19

import org.xml.sax.*;
import org.xml.sax.helpers.*;
import java.io.*;
 
public class SaxParser5 extends DefaultHandler {
 
  private Locator docLocator = null;
  private StringBuffer buffer = new StringBuffer();
  
  public void setDocumentLocator(Locator locator)
  {
    docLocator = locator;
  }
 
  public void startDocument( ) throws SAXException {
    System.out.println( “SAX Event: START DOCUMENT” );
  }
 
  public void endDocument( ) throws SAXException {
    System.out.println( “SAX Event: END DOCUMENT” );
  }
 
  public void startElement(String namespaceURI,
                           String localName,
                           String qName,
                           Attributes attr ) throws SAXException {
    int lineNumber = 0;
    if (docLocator != null)
    {
      lineNumber = docLocator.getLineNumber();      
    }    
    System.out.println( “SAX Event: START ELEMENT[ “ + localName + “ ]” );
    if (lineNumber != 0)
    {
      System.out.println(“	(Found at line number: “ + lineNumber + “.)”);
    }
    for ( int i = 0; i < attr.getLength(); i++ ){
    System.out.println( “ ATTRIBUTE: “ + attr.getLocalName(i) + 
 “ VALUE: “ + attr.getValue(i) );
    }
    
    buffer.setLength(0);
  }
 
  public void endElement(String namespaceURI,
                         String localName,
                         String qName ) throws SAXException {
    System.out.print( “SAX Event: CHARACTERS[ “ );
    System.out.println(buffer.toString());
    System.out.println( “ ]” );     
    System.out.println( “SAX Event: END ELEMENT[ “ + localName + “ ]” );
  }
 
  public void characters(char[] ch,
                         int start,
                         int length ) throws SAXException {
    try {
      buffer.append(ch, start, length); 
    } catch (Exception e) {
     e.printStackTrace();
    }
  }
 
  public void warning (SAXParseException exception)
    throws SAXException {
    System.err.println(“[Warning] “ +
      exception.getMessage() + “ at line “ +
      exception.getLineNumber() + “, column “ +
      exception.getColumnNumber() );
  }
 
  public void error (SAXParseException exception)
    throws SAXException {
    System.err.println(“[Error] “ +
      exception.getMessage() + “ at line “ +
      exception.getLineNumber() + “, column “ +
      exception.getColumnNumber() );
  }
 
  public void fatalError (SAXParseException exception)
    throws SAXException {
    System.err.println(“[Fatal Error] “ +
      exception.getMessage() + “ at line “ +
      exception.getLineNumber() + “, column “ +
      exception.getColumnNumber() );
    throw exception;
  }
  
 
  public static void main( String[] argv ){
    String inputFile = argv[0];
    System.out.println( “Processing '” + inputFile + “'.” );
    System.out.println( “SAX Events:” );
    try {
      XMLReader reader = XMLReaderFactory.createXMLReader();
      SaxParser5 parser = new SaxParser5();
      reader.setContentHandler(parser);
      reader.setErrorHandler(parser);
      try
      {
        reader.setFeature(“http://xml.org/sax/features/validation”, true);
      } catch (SAXException e) {
      System.err.println(“Cannot activate validation”);
      }
 
      reader.parse( new InputSource(
                 new FileReader( inputFile )));
    }catch ( Exception e ) {
       e.printStackTrace();
    }
  }
}

You may want to use two other interfaces to receive notifications when the document is parsed. These are covered in the next two sections.

Using the DTDHandler Interface

Now that you have added a DTD to your document, you may want to receive some events about the declarations. The logical place to turn is the DTDHandler interface. Unfortunately, the DTDHandler interface provides you with very little information about the DTD itself. In fact, it allows you to see the declarations only for notations and unparsed entities. Table 11-4 shows the two events produced by the DTDHandler interface and their use.

TABLE 11.4: DTDHandler Events

When parsing documents that make use of notations and unparsed entities to refer to external files — such as image references in XHTML or embedded references to non-XML documents — the application must have access to the declarations of these items in the DTD. This is why the creators of SAX made them available through the DTDHandler, one of the default interfaces associated with an XMLReader.

The declarations of elements, attributes, and internal entities, however, are not required for general XML processing. These declarations are more useful for XML editors and validators. Therefore, the events for these declarations were made available in one of the extension interfaces, DeclHandler. You look at the extension interfaces in more detail later in the chapter.

Using the DTDHandler interface is very similar to using the ContentHandler and ErrorHandler interfaces. The DefaultHandler class you used as the base class of the TrainReader also implements the DTDHandler interface, so working with the events is simply a matter of overriding the default behavior, just as you did with the ErrorHandler and ContentHandler events. To tell the XMLReader to send the DTDHandler events to your application, you can simply call the setDTDHandler function, as shown in the following code:

reader.setDTDHandler(SaxParser5);

---

WARNING You may be wondering if there is an interface for receiving XML Schema events. Surprisingly, there isn’t. In fact, no events are fired for XML Schema declarations either. The creators of SAX wanted to ensure that all the information outlined in the XML Recommendation was available through the interfaces. Remember that DTDs are part of the XML Recommendation, but XML Schemas are defined in their own, separate recommendation.

---

The second interface is EntityResolver, used for providing information and control when an external entity reference is encountered.

EntityResolver Interface

The EntityResolver interface enables you to control how a SAX parser behaves when it attempts to resolve external entity references within the DTD, so much like the DTDHandler, it is frequently not used. However, when an XML document utilizes external entity references, it is highly recommended that you provide an EntityResolver.

The EntityResolver interface defines only one function, resolveEntity, which enables the application to handle the resolution of entity lookups for the parser.

As shown with the other default interfaces, the EntityResolver interface is implemented by the DefaultHandler class. Therefore, to handle the event callback, you simply override the resolveEntity function in the TrainReader class and make a call to the setEntityResolver function like so:

reader.setEntityResolver(SaxParser5);

Consider the following entity declaration:

<!ENTITY People PUBLIC “-//People//people xml 1.0//EN”
    “http://wrox.com/people.xml”>

In this case, the resolveEntity function would be passed — //People//people xml 1.0//EN as the public identifier, and http://wrox.com/people.xml as the system identifier. The DefaultHandler class’s implementation of the resolveEntity function returns a null InputSource by default. When handling the resolveEntity event, however, your application can take any number of actions. It could create an InputSource based on the system identifier, or it could create an InputSource based on a stream returned from a database, hash table, or catalog lookup that used the public identifier as the key. It could also simply return null. These options and many more enable an application to control how the processor opens and connects to external resources.

Earlier you saw how validation was turned on by setting a feature; in the next section you’ll look at this in more detail.

Understanding Features and Properties

As shown earlier in this chapter, some of the behavior of SAX parsers is controlled through setting features and properties. For example, to activate validation, you needed to set the http://xml.org/sax/features/validation feature to true. In fact, all features in SAX are controlled this way, by setting a flag to true or false. The feature and property names in SAX are full URIs so that they can have unique names — much like namespace names.

Working with Features

To change a feature’s value in SAX, you simply call the setFeature function of the XMLReader like so:

public void setFeature(String name, boolean value)
  throws SAXNotRecognizedException, SAXNotSupportedException

When doing this, however, it is important to remember that parsers may not support, or even recognize, every feature. If a SAX parser does not recognize the name of the feature, the setFeature function raises a SAXNotRecognizedException. If it recognizes the feature name but does not support a feature (or does not support changing the value of a feature at a certain time), the setFeature function raises a SAXNotSupportedException. For example, if a SAX parser does not support validation, it raises a SAXNotSupportedException when you attempt to change the value to true.

The getFeature function enables you to check the value of any feature like so:

public boolean getFeature(String name)
  throws SAXNotRecognizedException, SAXNotSupportedException

Like the setFeature function, the getFeature function may raise exceptions if it does not recognize the name of the feature or does not support checking the value at certain times (such as before, during, or after the parse function has been called). Therefore, place all of your calls to the setFeature and getFeature functions within a try/catch block to handle any exceptions.

All SAX parsers should recognize, but may not support, the following features in Table 11-5:

TABLE 11.5: Configurable SAX Features

Working with Properties

Working with properties is very similar to working with features. Instead of boolean flags, however, properties may be any kind of object. The property mechanism is most often used to connect helper objects to an XMLReader. For example, SAX comes with an extension set of interfaces called DeclHandler and LexicalHandler that enable you to receive additional events about the XML document. Because these interfaces are considered extensions, the only way to register these event handlers with the XMLReader is through the setProperty function:

public void setProperty(String name, Object value)
  throws SAXNotRecognizedException, SAXNotSupportedException
 
public Object getProperty(String name)
  throws SAXNotRecognizedException, SAXNotSupportedException

As you saw with the setFeature and getFeature functions, all calls to setProperty and getProperty should be safely placed in try/catch blocks, because they may raise exceptions. Some of the default property names are listed in Table 11-6:

TABLE 11.6: Configurable SAX Properties

Using the Extension Interfaces

The two primary extension interfaces are DeclHandler and LexicalHandler. Using these interfaces, you can receive events for each DTD declaration and specific items such as comments, CDATA sections, and entity references as they are expanded. It is not required by the XML specification that these items be passed to the application by an XML processor. All the same, the information can be very useful at times, so the creators of SAX wanted to ensure that they could be accessed.

The DeclHandler interface declares the following events in Table 11-7:

TABLE 11.7: DeclHandler Interface Definition

The LexicalHandler interface declares the following events in Table 11-8:

TABLE 11.8: LexicalHandler Interface Definition

Because these are extension interfaces, they must be registered with the XMLReader using the property mechanism, as you just learned. For example, to register a class as a handler or LexicalHandler events, you might do the following:

reader.setProperty(“http://xml.org/sax/properties/lexical-handler”, lexHandler);

---

NOTE The DefaultHandler class, which you used as the basis of the SaxParser classes, does not implement any of the extension interfaces. In the newer versions of SAX, however, an extension class was added called DefaultHandler2. This class not only implements the core interfaces, but the extension interfaces as well. Therefore, if you want to receive the LexicalHandler and DeclHandler events, it is probably a good idea to descend from DefaultHandler2 instead of the DefaultHandler class.

---

The great thing about SAX is that it’s not just limited to Java. Implementations exist for C++, PHP, and Microsoft’s COM as well as many other languages. People have accepted the fact that a good way to handle large documents is to use an event-based method.

Now that you’ve seen how SAX copes with documents using events, in the next section you look at .NET’s answer to the problems posed by large documents, System.Xml.XmlReader.

USING XMLREADER

Whereas with SAX you handle events thrown by the parser, XmlReader takes a different approach, albeit one that needs a similar mindset to work with. Again you are working through the document in a serial fashion, but whereas with SAX the process is somewhat akin to watching a conveyor belt loaded with goods go by, with you plucking items from it as it passes, with XmlReader the process is more like the XML being laid out like a long buffet, where you need to move along picking up whatever items you want.

XmlReader has similar advantages and disadvantages to SAX, too. It is very efficient from a memory point of view because the whole document is not loaded into RAM. This also means that once you’ve passed a particular spot, you can’t go back; you have to begin the process anew. You also can’t validate a complete document. You can only know that the XML is valid or invalid up to the furthest point you’ve reached. If you want full validation before you start processing, you’ll need two passes.

In the following activity you see how to get started with XmlReader. You’ll start out with the basics: how to load an XML document and how to use basic navigation to read its content.

---

TRY IT OUT: Loading a Document with XmlReader

This Try It Out walks you through creating an XmlReader, loading a document, and reading the name of the document’s root element. If you just want to follow along, the code is available in the download for this chapter. The solution is named XmlReaderDemo.

1. If you are using the full version of Visual Studio then open it and create a blank solution named XmlReaderDemo as shown in Figure 11-1. If you are using Visual Studio Express open the C# version and move on to step 2.

FIGURE 11-1

2. Add a new Windows Console project named XmlReaderBasics.

3. Right-click the project and choose Add Existing Item. Choose the People.xml file shown earlier in the chapter in Listing 11-1.

4. Go to the properties of People.xml and make sure that Copy to Output Directory is set to Copy If Newer as shown in the bottom right corner of Figure 11-2. This makes it easier to locate because it will be in the same folder as the application.

FIGURE 11-2

5. Replace the code in Program.cs with the code in Listing 11-6.

LISTING 11-6: Program.cs (in project XmlReaderBasics)

using System;
using System.Xml;
 
namespace XmlReaderBasics
{
  internal class Program
  {
    private static void Main(string[] args)
    {
      var xmlUri = “People.xml”;
      var reader = DisplayRootElement(xmlUri);
      Console.ReadLine();
    }
 
    private static XmlReader DisplayRootElement(string uri)
    {
      var reader = XmlReader.Create(uri);
      reader.MoveToContent();
      var rootElementName = reader.Name;
      Console.WriteLine(“Root element name is: {0}”, rootElementName);
      return reader;
    }
  }
}

6. Save all files (Ctrl+Shift+S) and then build (Ctrl+Shift+B).

7. Assuming there are no build errors, run the program using F5.

8. You should see the following output in the console window. Press Enter to close the window.

Root element name is: People

How It Works

The DisplayRootElement() method first creates an XmlReader using a static factory method on the XmlReader class as shown in the following code. XmlReader is actually an abstract class and it therefore can’t have an instance:

var reader = XmlReader.Create(uri);

What is actually returned in this example is an XmlTextReader, the simplest implementation of the abstract class. It’s also possible to create other versions such as an XmlValidatingReader if you want document validation; you learn how to do this later in the chapter in the “Using XMLReaderSettings” section.

The Create() method takes the path to the file. In this case, this is a relative path because the file is in the same folder as the executable, but you can also pass in a full path or a URL. The Create() method can take other parameters, some of which you see later.

If there is a problem loading the XML — for example, the file cannot be found or there is a permissions problem — a suitable exception will be thrown such as FileNotFoundException or SecurityException.

Once the XmlReader has loaded the XML, the most common action is to use the MoveToContent() method to position the reader’s cursor on the root element:

reader.MoveToContent();

The MoveToContent() method checks to see if the cursor is currently located at content; if not, it moves to the first content it can find. Content is defined as non-whitespace text, an element, or entity reference. Comments, processing instructions, document types, and whitespace are skipped over. This means that everything between the start of the document and the actual root element will be ignored and the cursor will be pointing to the first element in the document. Microsoft terms this the current node in the XmlReader documentation.

Once the reader has a current node, properties of this node are available. In this case you used the Name property as shown here but you could use dozens of others such as Attributes, Value, and NamespaceURI:

var rootElementName = reader.Name;

Finally, the name of the element is displayed and the reader is returned so that it can be used to extract more information:

Console.WriteLine(“Root element name is: {0}”, rootElementName);
return reader;

---

So far you’ve seen the basics in action — loading a document and moving to the document element. The next step is to read some useful information from the document, which you do in the following activity.

    private static XmlReader DisplayPeopleWithDates(XmlReader reader)
    {
      while (reader.Read())
      {
        if (reader.NodeType == XmlNodeType.Element
            && reader.Name == “Person”)
        {
          DateTime bornDate = new DateTime();
          DateTime diedDate = new DateTime();
          var personName = string.Empty;
          while (reader.MoveToNextAttribute())
          {
            switch (reader.Name)
            {
              case “bornDate”:
                bornDate = reader.ReadContentAsDateTime();
                break;
              case “diedDate”:
                diedDate = reader.ReadContentAsDateTime();
                break;
            }
          }
 
          while (reader.Read())
          {
            if (reader.NodeType == XmlNodeType.Element
                && reader.Name == “Name”)
            {
              personName = reader.ReadElementContentAsString();
              break;
            }
          }
          Console.WriteLine(“{0} was born in {1} and died in {2}”,
                            personName,
                            bornDate.ToShortDateString(),
                            diedDate.ToShortDateString());
        }
      }
 
      return reader;
    }

    private static void Main(string[] args)
    {
      var xmlUri = “People.xml”;
      var reader = DisplayRootElement(xmlUri);
      reader = DisplayPeopleWithDates(reader);
      Console.ReadLine();
    }

Root element name is: People
Winston Churchill was born in 30/11/1874 and died in 24/01/1965
Indira Gandhi was born in 19/11/1917 and died in 31/10/1984
John F. Kennedy was born in 29/05/1917 and died in 22/11/1963

    private static XmlReader DisplayPeopleWithDates(XmlReader reader)
    {
      while (reader.Read())

        if (reader.NodeType == XmlNodeType.Element
            && reader.Name == “Person”)
        {
          DateTime bornDate = new DateTime();
          DateTime diedDate = new DateTime();
          var personName = string.Empty;

          while (reader.MoveToNextAttribute())
          {
            switch (reader.Name)
            {
              case “bornDate”:
                bornDate = reader.ReadContentAsDateTime();
                break;
              case “diedDate”:
                diedDate = reader.ReadContentAsDateTime();
                break;
            }
          }

          while (reader.Read())
          {
            if (reader.NodeType == XmlNodeType.Element
                && reader.Name == “Name”)
            {
              personName = reader.ReadElementContentAsString();
              break;
            }
          }

          Console.WriteLine(“{0} was born in {1} and died in {2}”,
                            personName,
                            bornDate.ToShortDateString(),
                            diedDate.ToShortDateString());

The preceding Try It Out example made use of the XmlNodeType enumeration. The most common test is for elements but there are times when you are targeting other content types. The full list of values returned by XmlReader is shown in Table 11-9.

TABLE 11.9: XmlNodeType Enumeration

There are other members of the enumeration, such as Document, but these are never returned by the XmlReader.

So far you’ve used the basic XmlReader.Create() method to get a standard XmlTextReader. In the next section you see how you can use the XmlReaderSettings class to more tightly control how the reader will work.

Using XmlReaderSettings

Many questions can arise when parsing and reading XML, for example:

• How do you want to treat whitespace?
• Do you want validation?
• If you do want validation, where are the relevant schemas?
• Do you want attention paid to any document type definition?
• Are you interested in comments, or can they be ignored?
• What should be done with the stream after reading? Should it be closed or left open?
• How do you provide credentials to access secured online resources?

All these questions, along with others, can be answered by using the XmlReaderSettings class — to create a new instance of the class, set the appropriate properties, and then pass it as a second argument to the XmlReader.Create() method.

For example, suppose you want to ignore any comments in the document; you are not going to do anything with them so they’ll only get in the way. The following code shows how to do this:

var settings = new XmlReaderSettings();
settings.IgnoreComments = true;
var reader = XmlReader.Create(xmlUri, settings);

The next example shows a more complicated scenario: how to provide credentials for a secured online resource. Any time an XmlReader needs to access a resource, it uses an XmlResolver. The built-in resolver uses the credentials of the account running the code, which may not be sufficient. You can access the resolver and change the credentials via the XmlReaderSettings in the following manner:

var settings = new XmlReaderSettings();
var resolver = new XmlUrlResolver();
var credentials = new Syystem.Net.NetworkCredential(username,
                                                    password,
                                                    domainName);
resolver.Credentials = credentials;
settings.XmlResolver = resolver;
var reader = XmlReader.Create(xmlUri, settings);

---

NOTE You can use a standard string to specify the password, but you should really use the SecureString class, which makes sure that the data is wiped from memory as soon as is practical.

---

The next activity illustrates another common scenario: how to use an XmlReader to validate a document. You’ll see how you need to specify in advance that you want a validating reader and how any validation errors are handled.

---

TRY IT OUT: Validating a Document with XmlReader

This Try It Out will show you how to validate a document using XmlReader. You’ll see how to use the XmlReaderSettings class to specify that you want validation and what validation method is required. You’ll then see how validation messages are reported when reading an invalid document.

1. If you are using the full version of Visual Studio in the XmlReaderDemo solution, right-click the solution icon and choose Add New Project. If using the Express version then close any existing projects and choose File New Project.

2. Choose a Windows Console Application and call it ValidationDemo.

3. Within the project add a new item, an XML file named PeopleWithNamespace.xml.

4. Copy the XML from the People.xml in Listing 11-1 file and add the following namespace declaration to the document element to put all the elements into a default namespace:

<People xmlns=”http://wrox.com/namespaces/BeginningXml/People”>

5. Add another new file to the project, this time an XSD schema, and call it PeopleWithNamespace.xsd.

6. Add the code in Listing 11-7 to the XSD.

LISTING 11-7: PeopleWithNamespace.xsd

<?xml version=”1.0” encoding=”utf-8”?>
<xs:schema attributeFormDefault=”unqualified”
           elementFormDefault=”qualified”
           targetNamespace=”http://wrox.com/namespaces/BeginningXml/People”
           xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
  <xs:element name=”People”>
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs=”unbounded” name=”Person”>
          <xs:complexType>
            <xs:sequence>
              <xs:element name=”Name” type=”xs:string” />
              <xs:element name=”Description” type=”xs:string” />
            </xs:sequence>
            <xs:attribute name=”bornDate” type=”xs:date” use=”required” />
            <xs:attribute name=”diedDate” type=”xs:date” use=”required” />
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

7. Make sure that Copy to Output Directory property for both these files is set to Copy If Newer.

8. Open Program.cs and replace the code with the code in Listing 11-8.

LISTING 11-8: Program.cs (in project ValidationDemo)

using System;
using System.Xml;
using System.Xml.Schema;
 
namespace ValidationDemo
{
  internal class Program
  {
    private static void Main(string[] args)
    {
      var xmlUri = “PeopleWithNamespace.xml”;
      var targetNamespace =
         “http://wrox.com/namespaces/BeginningXml/People”;
      var schemaUri = “PeopleWithNamespace.xsd”;
      ValidateDocument(xmlUri, targetNamespace, schemaUri);
      Console.ReadLine();
    }
 
    private static void ValidateDocument(string uri,
                                         string targetNamespace,
                                         string schemaUri)
    {
      var schemaSet = new XmlSchemaSet();
      schemaSet.Add(targetNamespace, schemaUri);
      var settings = new XmlReaderSettings();
      settings.ValidationType = ValidationType.Schema;
      settings.Schemas = schemaSet;
      settings.ValidationEventHandler += ValidationCallback;
      var reader = XmlReader.Create(uri, settings);
      while (reader.Read()) ;
      Console.WriteLine(“Validation complete.”);
    }
 
    private static void ValidationCallback(object sender,
                                           ValidationEventArgs e)
    {
      Console.WriteLine(
            “Validation Error: {0}
	Line number {1}, position {2}.”,
                        e.Message,
                        e.Exception.LineNumber,
                        e.Exception.LinePosition);
    }
  }
}

9. Right-click the project and set it as the startup project for the solution as shown in Figure 11-3.

FIGURE 11-3

10. Save (Ctrl+Shift+S) and build (Ctrl+Shift+B) the project and run with F5.

11. You should see the following message in the console:

Validation complete.

12. Modify PeopleWithNamespace.xml by removing the diedDate attribute from the second <Person> element, as shown here:

  <Person bornDate=”1917-11-19”>
    <Name>Indira Gandhi</Name>

13. Rerun the solution. This time you should see a message reporting a validation error as follows:

Validation Error: The required attribute 'diedDate' is missing.
        Line number 9, position 4.
Validation complete.

How It Works

ValidateDocument begins by setting up an XmlSchemaSet that will hold the necessary schema for validating your document. In this case there is only one, PeopleWithNamespace.xsd. You add this using the Add() method, which specifies the target namespace, http://wrox.com/namespaces/BeginningXml/People, and the path to the schema. The corresponding code follows:

    private static void ValidateDocument(string uri,
                                         string targetNamespace,
                                         string schemaUri)
    {
      var schemaSet = new XmlSchemaSet();
      schemaSet.Add(targetNamespace, schemaUri);
      // method continues

The next stage involves creating an XmlReaderSettings object and specifying the ValidationType. This defaults to ValidationType.None. In the following code you set it to ValidationType.Schema, which means that instead of the XmlReader.Create() method returning an XmlTextReader, you’ll get an XsdValidatingReader. Then you set the settings’ Schemas property to be the XmlSchemaSet previously created:

      var settings = new XmlReaderSettings();
      settings.ValidationType = ValidationType.Schema;
      settings.Schemas = schemaSet;

The next step is to provide a method that is called whenever a validation error occurs; here the method is named ValidationCallback:

      settings.ValidationEventHandler += ValidationCallback;

The last lines of the method create the XmlReader, passing in the all-important settings, and then call the Read() method in the familiar while loop. Notice how you are not doing anything extra within the loop; this is just to make sure the whole XML document is read and validated:

      var reader = XmlReader.Create(uri, settings);
      while (reader.Read()) ;
      Console.WriteLine(“Validation complete.”);

The callback that handles any errors is fairly straightforward, shown here:

    private static void ValidationCallback(object sender,
                                           ValidationEventArgs e)
    {
      Console.WriteLine(“Validation Error: {0}
	Line number {1}, position {2}”,
                        e.Message,
                        e.Exception.LineNumber,
                        e.Exception.LinePosition);
    }
  }

Whenever an error occurs, the method is called with the familiar .NET signature of the sender as an object and an EventArgs. In this case, the EventArgs is of type ValidationEventArgs and provides both a Message property, which is the reason the validation failed, and an Exception property, which can be used to garner more details. In this case the line number and position of the error is extracted. If you wanted more detail, you could cast the sender object to an XmlReader and use properties such as Name to find out which node was being read when the error occurred.

---

Now that you’ve covered most of the standard scenarios in reading data, using Read() to move through the XML and returning content from elements and attributes, next you’ll look at the role of the XmlResolver more deeply and see how you can limit where external resources are loaded from.

Controlling External Resources

You saw earlier how an XmlReaderSettings class has a property, XmlResolver, which, by default, returns an instance of an XmlUrlResolver. By default, the XmlUrlResolver handles requests for files using the file:// and http:// protocols, but it’s possible to write your own class that inherits from XmlResolver, which knows how to handle other ones. The XmlResolver class is also used when transforming XML using the System.Xml.Xsl.CompiledTransform, again to govern how external resources are dealt with. A common requirement when loading or especially transforming a file is to have access to data that resides in a traditional SQL database. Many people have therefore written XmlResolvers that can do this. Most of them allow you to specify a resource such as the following:

sql://executeProcedure?name=GetAllCustomers&City=Seattle

This would cause the data returned by the procedure — all customers who reside in Seattle — to be embedded in the XML.

Another common request is to be able to call a web service. This can be achieved in a limited way if the service is a RESTful one that only uses the querystring to provide data, but is impossible to do so where a post is required, as is the case for most SOAP-based services.

Both of the preceding scenarios involve writing your own implementation of XmlResolver, but there is another case that is so common that Microsoft has done the work for you. This is when you want to restrict access to external files, normally based on where they reside. Why would you want to do this? The common reason is that you are accepting XML files from a third party. Maybe your web orders are sent from other businesses using a business-to-business (B2B) system and you need to process these. Although it’s legitimate for these files to contain references to external resources (maybe a schema, a DTD, or an entity), these resources should only reside on servers that have been approved beforehand. To prevent the chance of infected files getting on to your servers, or to prevent a denial of service (DoS) attack, it’s essential to have a way of limiting the locations from where files are retrieved.

---

NOTE A DoS attack is one which tries to use all the resources on a machine by either issuing an extremely large number of requests or by injecting very large files into the processing pipeline.

---

For these and related reasons, Microsoft offers the XmlSecureResolver class, whereby you can easily restrict which domains can be accessed.

For this scenario, assume that any external resources can only come from two specific URLs, http://myWebServer.com and http://myDataServer.com. Now perform the following steps:

var permission = new WebPermission(PermissionState.None);

permission.AddPermission(NetworkAccess.Connect, “http://myWebServer.com”);
permission.AddPermission(NetworkAccess.Connect, “http://myDataServer.com”);

var permissionSet = new PermissionSet(PermissionSet.None);
permissionSet.AddPermission(permission);

var resolver = new XmlSecureResolver(new XmlUrlResolver(), permissionSet);

var settings = new XmlReaderSettings();
settings.XmlResolver = resolver;
var reader = XmlReader.Create(xmlUri, settings);

SUMMARY

• There are two new methods for processing XML: SAX and .NET’s XmlReader.
• SAX is an event-driven paradigm whereby the SAX parser fires events when different types of content are found. Registered listeners can react to these events.
• In XmlReader the programmer instigates moving through the document and stops when the target content is reached.

EXERCISES

Answers to the exercises can be found in Appendix A.

WHAT YOU LEARNED IN THIS CHAPTER