Top Contents Index Glossary

Using the Validating Parser

By now, you have done a lot of experimenting with the nonvalidating parser. It's time to have a look at the validating parser and find out what happens when you use it to parse the sample presentation.

Two things to understand about the validating parser at the outset are:

1. The DTD is required.
2. Since the DTD is present, the ignorableWhitespace method is invoked whenever the DTD makes that possible.

Changing Parsers

The first step is modify the Echo program so that it uses the validating parser instead of the nonvalidating parser.

Note:
The code in this section is contained in Echo10.java.

To use the validating parser, make the changes highlighted below:

// Get an instance of the non-validating parser.
Parser parser;
parser = ParserFactory.makeParser (
            "com.sun.xml.parser.ValidatingParser"
         );
parser.setDocumentHandler ( new Echo() );

Using an Environment Variable

You can also set things up so that you can change the parser at will, without having it hard coded into the program. The sample programs use this technique, which depends on the fact that the zero-argument method ParserFactory.makeParser() uses the environment variable com.sun.xml.parser, if it is defined. You can specify the value for the environment variable on the command line, like this:

> java -Dorg.xml.sax.parser=com.sun.xml.parser.ValidatingParser ...

Experimenting with Validation Errors

To see what happens when the XML document does not specify a DTD, remove the DOCTYPE statement from the XML file and run the Echo program on it.

Note:
The output shown here is contained in Echo10-01.log.

The result you see looks like this:

<?xml version='1.0' encoding='UTF-8'?>
** Warning, line 5, uri file:...
   Valid documents must have a <!DOCTYPE declaration.
** Parsing error, line 5, uri file: ...

So now you know that a DTD is a requirement for a valid document. That makes sense. So what happens when you run the parser on your current version of the slide presentation, with the DTD specified?

Note:
The output shown here is contained in Echo10-07.log.

This time, the parser gives the following error message:

** Parsing error, line 28, uri file:...
   Element "slide" does not allow "item" here.

This error occurs because the definition of the slide element requires a title. That element is not optional, and the copyright slide does not have one. To fix the problem, add the question mark highlighted below to make title an optional element:

<!ELEMENT slide (image?, title?, item*)>

Now what happens when you run the program?

Note:
You could also remove the copyright slide, which produces the same result shown below, as reflected in Echo10-06.log.

The answer is that everything runs fine, until the parser runs into the <em> tag contained in the overview slide. Since that tag was not defined in the DTD, the attempt to validate the document fails. The output looks like this:

...
    ELEMENT: <title>
    CHARS:   Overview
    END_ELM: </title>
    ELEMENT: <item>
    CHARS:   Why ** Parsing error, line 24, uri file:...
Element "item" does not allow "em" -- (#PCDATA|item)
org.xml.sax.SAXParseException: Element "item" does not allow "em" -- (#PCDATA|item)
       at com.sun.xml.parser.Parser.error(Parser.java:2798)
...

The error message identifies the part of the DTD that caused validation to fail. In this case it is the line that defines an item element as (#PCDATA | item).

Exercise: Make a copy of the file and remove all occurrences of <em> from it. Can the file be validated now? (In the next section, you'll learn how to define parameter entries so that we can use XHTML in the elements we are defining as part of the slide presentation.)

Error Handling in the Validating Parser

It is important to recognize that the only reason an exception is thrown when the file fails validation is as a result of the error-handling code you entered in the early stages of this tutorial. That code is reproduced below:

static class MyErrorHandler extends HandlerBase
{
    public void error (SAXParseException e)
    throws SAXParseException
    {
        throw e;
    }
    ...
} 

If that exception is not thrown, the validation errors are simply ignored.

Exercise: Try commenting out the line that throws the exception. What happens when you run the parser now?

In general, a SAX parsing error is a validation error, although we have seen that it can also be generated if the file specifies a version of XML that the parser is not prepared to handle. The thing to remember is that your application will not generate a validation exception unless you supply an error handler like the one above.

Top Contents Index Glossary