Chapter 4. Advanced SAX

4.1.2.1. Validation

The most common feature you'll use is the validation feature. The URI for this guy is http://xml.org/sax/features/validation, and not surprisingly, it turns validation on or off in the parser. For example, if you want to turn on validation in the parsing example from the last chapter (remember the Swing viewer?), make this change in the SAXTreeViewer.java source file:

    public void buildTree(DefaultTreeModel treeModel, 
                          DefaultMutableTreeNode base, String xmlURI) 
        throws IOException, SAXException {

        // Create instances needed for parsing
        XMLReader reader = 
            XMLReaderFactory.createXMLReader(vendorParserClass);
        ContentHandler jTreeContentHandler = 
            new JTreeContentHandler(treeModel, base);
        ErrorHandler jTreeErrorHandler = new JTreeErrorHandler( );

        // Register content handler
        reader.setContentHandler(jTreeContentHandler);

        // Register error handler
        reader.setErrorHandler(jTreeErrorHandler);
 
        // Request validation
        reader.setFeature("http://xml.org/sax/features/validation", true);

        // Parse
        InputSource inputSource = 
            new InputSource(xmlURI);
        reader.parse(inputSource);
    }

Compile these changes, and run the example program. Nothing happens, right? Not surprising; the XML we've looked at so far is all valid with respect to the DTD supplied. However, it's easy enough to fix that. Make the following change to your XML file (notice that the element in the DOCTYPE declaration no longer matches the actual root element, since XML is case-sensitive):

<?xml version="1.0"?>
<!DOCTYPE Book SYSTEM "DTD/JavaXML.dtd">

<!-- Java and XML Contents -->
<book xmlns="http://www.oreilly.com/javaxml2"
      xmlns:ora="http://www.oreilly.com"
>

Now run your program on this modified document. Because validation is turned on, you should get an ugly stack trace reporting the error. Of course, because that's all that our error handler methods do, this is precisely what we want:

C:\javaxml2\build>java javaxml2.SAXTreeViewer 
    c:\javaxml2\ch04\xml\contents.xml
**Parsing Error**
  Line:    7
  URI:     file:///c:/javaxml2/ch04/xml/contents.xml
  Message: Document root element "book", must match DOCTYPE root "Book".
org.xml.sax.SAXException: Error encountered
        at javaxml2.JTreeErrorHandler.error(SAXTreeViewer.java:445)
[Nasty Stack Trace to Follow...]

Remember, turning validation on or off does not affect DTD processing; I talked about this in the last chapter, and wanted to remind you of this subtle fact. To get a better sense of this, turn off validation (comment out the feature setting, or supply it the "false" value), and run the program on the modified XML. Even though the DTD is processed, as seen by the resolved OReillyCopyright entity reference, no errors occur. That's the difference between processing a DTD and validating an XML document against that DTD. Memorize, understand, and recite this to yourself; it will save you hours of confusion in the long run.

4.1.2.2. Namespaces

Next to validation, you'll most commonly deal with namespaces. There are two features related to namespaces: one that turns namespace processing on or off, and one that indicates whether namespace prefixes should be reported as attributes. The two are essentially tied together, and you should always "toggle" both, as shown in Table 4-2.

Table 4-2. Toggle values for namespace-related features

Value for namespace processing	Value for namespace prefix reporting
True	False
False	True

This should make sense: if namespace processing is on, the xmlns-style declarations on elements should not be exposed to your application as attributes, as they are only useful for namespace handling. However, if you do not want namespace processing to occur (or want to handle it on your own), you will want these xmlns declarations reported as attributes so you can use them just as you would use other attributes. However, if these two fall out of sync (both are true, or both are false), you can end up with quite a mess!

Consider writing a small utility method to ensure these two features stay in sync with each other. I often use the method shown here for this purpose:

private void setNamespaceProcessing(XMLReader reader, boolean state) 
    throws SAXNotSupportedException, SAXNotRecognizedException {

    reader.setFeature(
        "http://xml.org/sax/features/namespaces", state);
    reader.setFeature(
        "http://xml.org/sax/features/namespace-prefixes", !state);
}

This maintains the correct setting for both features, and you can now simply call this method instead of two setFeature( ) invocations in your own code. Personally, I've used this feature less than ten times in about two years; the default values (processing namespaces as well as not reporting prefixes as attributes) almost always work for me. Unless you are writing low-level applications that either don't need namespaces or can use the speed increase obtained from not processing namespaces, or you need to handle namespaces on your own, I wouldn't worry too much about either of these features.

This code brings up a rather important aspect of features and properties, though: invoking the feature and property methods can result in SAXNotSupportedExceptions and SAXNotRecognizedExceptions. These are both in the org.xml.sax package, and need to be imported in any SAX code that uses them. The first indicates that the parser knows about the feature or property but doesn't support it. You won't run into this much in even average quality parsers, but it is commonly used when a standard property or feature is not yet coded in. So invoking setFeature( ) on the namespace processing feature on a parser in development might result in a SAXNotSupportedException. The parser recognizes the feature, but doesn't have the ability to perform the requested processing. The second exception most commonly occurs when using vendor-specific features and properties (covered in the next section), and then switching parser implementations. The new implementation won't know anything about the other vendor's features or properties, and will throw a SAXNotRecognizedException.

You should always explicitly catch these exceptions so you can deal with them. Otherwise, you end up losing valuable information about what happened in your code. For example, let me show you a modified version of the code from the last chapter that tries to set up various features, and how that changes the exception-handling architecture:

    public void buildTree(DefaultTreeModel treeModel, 
                          DefaultMutableTreeNode base, String xmlURI) 
        throws IOException, SAXException {
            
        String featureURI = "";

        try {
            // Create instances needed for parsing
            XMLReader reader = 
                XMLReaderFactory.createXMLReader(vendorParserClass);
            ContentHandler jTreeContentHandler = 
                new JTreeContentHandler(treeModel, base);
            ErrorHandler jTreeErrorHandler = new JTreeErrorHandler( );

            // Register content handler
            reader.setContentHandler(jTreeContentHandler);

            // Register error handler
            reader.setErrorHandler(jTreeErrorHandler);
            
            /** Deal with features **/
            featureURI = "http://xml.org/sax/features/validation";

            // Request validation
            reader.setFeature(featureURI, true);
            
            // Namespace processing - on
            featureURI = "http://xml.org/sax/features/namespaces";
            setNamespaceProcessing(reader, true);
            
            // Turn on String interning
            featureURI = "http://xml.org/sax/features/string-interning";
            reader.setFeature(featureURI, true);
            
            // Turn off schema processing
            featureURI = 
                "http://apache.org/xml/features/validation/schema";
            reader.setFeature(featureURI, false);

            // Parse
            InputSource inputSource = 
                new InputSource(xmlURI);
            reader.parse(inputSource);
        } catch (SAXNotRecognizedException e) {
            System.out.println("The parser class " + vendorParserClass +
                " does not recognize the feature URI " + featureURI);
            System.exit(0);
        } catch (SAXNotSupportedException e) {
            System.out.println("The parser class " + vendorParserClass +
                " does not support the feature URI " + featureURI);
            System.exit(0);                
        }
    }

By dealing with these exceptions as well as other special cases, you give the user better information and improve the quality of your code.

4.1.2.3. Interning and entities

The three remaining SAX-defined features are fairly obscure. The first, http://xml.org/sax/features/string-interning, turns string interning on or off. By default this is false (off) in most parsers. Setting it to true means that every element name, attribute name, namespace URI and prefix, and other strings have java.lang.String.intern() invoked on them. I'm not going to get into great detail about interning here; if you don't know what it is, check out Sun's Javadoc on the method at http://java.sun.com/j2se/1.3/docs/api/index.html. In a nutshell, every time a string is encountered, Java attempts to return an existing reference for the string in the current string pool, instead of (possibly) creating a new String object. Sounds like a good thing, right? Well, the reason it's off by default is most parsers have their own optimizations in place that can outperform string interning. My advice is to leave this setting alone; many people have spent weeks tuning things like this so you don't have to mess with them.

The other two features determine whether textual entities are expanded and resolved (http://xml.org/sax/features/external-general-entities), and whether parameter entities are included (http://xml.org/sax/features/external-parameter-entities) when parsing occurs. These are set to true for most parsers, as they deal with all the entities that XML has to offer. Again, I recommend you leave these settings as is, unless you have a specific reason for disabling entity handling.

4.1.2.4. DOM nodes and literal strings

The two standard SAX properties are a little less clear in their usage. In both cases, the properties are more useful for obtaining values, whereas with features the common use is to set values. Additionally, both properties are more helpful in error handling than in any general usage. And finally, both properties provide access to what is being parsed at a given time. The first, identified by the URI http://xml.org/sax/properties/dom-node, returns the current DOM node being processed, or the root DOM node if parsing isn't occurring. Of course, I haven't really talked about DOM yet, but this will make more sense in the next two chapters. The second property, identified by the URI http://xml.org/sax/properties/xml-string, returns the literal string of characters being processed. You'll find varying support for these properties in various parsers, showing that many parser implementers find these properties of arguable use as well. For example, Xerces does not support the xml-string property, to avoid having to buffer the input document (at least in that specific way). On the other hand, it does support the dom-node property so that you can turn a SAX parser into (essentially) a DOM tree iterator.