If http://xml.org/sax/features/external-general-entities is true, then the parser resolves all external general entity references. If it’s false, it does not. If the parser is validating, then this feature is required to be true.

The default value is parser-dependent. Not all parsers are able to resolve external entity references. Attempting to set this to true with a parser that cannot resolve external entity references will throw a SAXNotRecognizedException.

If http://xml.org/sax/features/external-parameter-entities is true, then the parser resolves all external parameter entity references. If it’s false, it does not. If the parser is validating, then this feature is required to be true.

The default value of this feature is parser-dependent. Not all parsers are able to resolve external entity references. Attempting to set this to true with a parser that cannot resolve external entity references will throw a SAXNotRecognizedException.

If http://xml.org/sax/features/string-interning is true, then the parser internalizes all XML names using the intern() method of the String class before passing them to the various callback methods. Thus if there are 100 different paragraph elements in your document, the parser will only use one "paragraph" string for all 100 start-tags and 100 end-tags rather than 200 separate strings. This can save memory as well as allowing you to compare element names using the == operator instead of the equals() method. Besides element names, this also affects attribute names, entity names, notation names, namespace prefixes, and namespace URIs. The default value is parser-dependent.

If http://xml.org/sax/features/validation is true, then the parser validates the document against its DTD. Of course not all parsers are capable of doing this. Attempting to set http://xml.org/sax/features/validation to true for a parser that doesn’t know how to validate will throw a SAXNotRecognizedException.

Since validation requires resolving all external entity references, setting http://xml.org/sax/features/validation to true automatically sets http://xml.org/sax/features/external-general-entities and http://xml.org/sax/features/external-parameter-entities to true as well.

The default value of this feature is allegedly parser-dependent, though I’ve yet to encounter a parser that turns it on by default.

Example 7.9 is a program that uses this feature to validate documents. As well as setting the http://xml.org/sax/features/validation feature to true, it’s also necessary to register an ErrorHandler object that can receive messages about validity errors.

import org.xml.sax.*;
import org.xml.sax.helpers.XMLReaderFactory;
import java.io.IOException;


public class SAXValidator implements ErrorHandler {
  
  // Flag to check whether any errors have been spotted.
  private boolean valid = true;
  
  public boolean isValid() {
    return valid; 
  }
  
  // If this handler is used to parse more than one document, 
  // its initial state needs to be reset between parses.
  public void reset() {
    // Assume document is valid until proven otherwise
    valid = true; 
  }
  
  public void warning(SAXParseException exception) {
    
    System.out.println("Warning: " + exception.getMessage());
    System.out.println(" at line " + exception.getLineNumber() 
     + ", column " + exception.getColumnNumber());
    // Well-formedness is a prerequisite for validity
    valid = false;
    
  }
  
  public void error(SAXParseException exception) {
     
    System.out.println("Error: " + exception.getMessage());
    System.out.println(" at line " + exception.getLineNumber() 
     + ", column " + exception.getColumnNumber());
    // Unfortunately there's no good way to distinguish between
    // validity errors and other kinds of non-fatal errors 
    valid = false;
    
  }
  
  public void fatalError(SAXParseException exception) {
     
    System.out.println("Fatal Error: " + exception.getMessage());
    System.out.println(" at line " + exception.getLineNumber() 
     + ", column " + exception.getColumnNumber()); 
     
  }
  

  public static void main(String[] args) {
  
    if (args.length <= 0) {
      System.out.println("Usage: java SAXValidator URL");
      return;
    }
    String document = args[0];
    
    try {
      XMLReader parser = XMLReaderFactory.createXMLReader();
      SAXValidator handler = new SAXValidator();
      parser.setErrorHandler(handler);
      // Turn on validation. 
      parser.setFeature(
       "http://xml.org/sax/features/validation", true);
      parser.parse(document);
      if (handler.isValid()) {
        System.out.println(document + " is valid.");
      }
      else {
        // If the document isn't well-formed, an exception has
        // already been thrown and this has been skipped.
        System.out.println(document + " is well-formed.");
      }
    }
    catch (SAXParseException e) {
      System.out.print(document + " is not well-formed at ");
      System.out.println("Line " + e.getLineNumber() 
       + ", column " +  e.getColumnNumber() );
    }
    catch (SAXException e) {
      System.out.println("Could not check document because " 
       + e.getMessage());
    }
    catch (IOException e) { 
      System.out.println(
       "Due to an IOException, the parser could not check " 
       + document
      ); 
    }
  
  }

}

Here’s the beginning of the output from running it across the Docbook XML source code for an early version of this chapter:

%java -Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser SAXValidator
 xmlreader.xml
Error: Element type "xinclude:include" must be declared.
 at line 344, column 92
Error: Attribute "href" must be declared for 
 element type "xinclude:include".
 at line 344, column 92
Error: Attribute "parse" must be declared for 
 element type "xinclude:include".
 at line 344, column 92
Error: The content of element type "programlisting" must match 
"(#PCDATA|footnoteref|xref|abbrev|acronym|citation|citerefentry
|citetitle|emphasis|firstterm|foreignphrase|glossterm|footnote
|phrase|quote|trademark|wordasword|link|olink|ulink|action
|application|classname|methodname|interfacename|exceptionname
|ooclass|oointerface|ooexception|command|computeroutput|database
|email|envar|errorcode|errorname|errortype|filename|function
|guibutton|guiicon|guilabel|guimenu|guimenuitem|guisubmenu
|hardware|interface|keycap|keycode|keycombo|keysym|literal
|constant|markup|medialabel|menuchoice|mousebutton|option
|optional|parameter|prompt|property|replaceable|returnvalue
|sgmltag|structfield|structname|symbol|systemitem|token|type
|userinput|varname|anchor|author|authorinitials|corpauthor
|modespec|othercredit|productname|productnumber|revhistory|remark
|subscript|superscript|inlinegraphic|inlinemediaobject
|inlineequation|synopsis|cmdsynopsis|funcsynopsis|classsynopsis
|fieldsynopsis|constructorsynopsis|destructorsynopsis
|methodsynopsis|indexterm|beginpage|co|lineannotation)*".
 at line 344, column 110
…
xmlreader.xml is well-formed.

SAXValidator is complaining about the XInclude elements I use to merge in source code examples like Example 7.9. These are not expected by the Docbook DTD. They need to be replaced before the file becomes valid. Once I do that, the merged file (ch07.xml) is valid:

%java -Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser SAXValidator
 ch07.xml
ch07.xml is valid.

http://xml.org/sax/properties/xml-string is a read-only property that contains the string of text corresponding to the current SAX event. For example, in the startElement() method, this property would contain the actual start-tag that caused the method invocation.

This property can be used in a very straightforward program that echoes an XML document onto a Writer, as shown in Example 7.10. Assuming a validating parser, the parsing process merges a document that was originally split across multiple parsed entities into a single entity. Here each callback method in the ContentHandler simply invokes a private method that writes out the current value of the http://xml.org/sax/properties/xml-string property.

import org.xml.sax.*;
import org.xml.sax.helpers.XMLReaderFactory;
import java.io.*;


public class DocumentMerger implements ContentHandler {

  private XMLReader parser;
  private Writer out;
  
  public DocumentMerger(XMLReader parser, Writer out) {
    this.parser = parser;
    this.out = out;   
  }
  
  private void output() throws SAXException {
    
    try {
      String s = (String) parser.getProperty(
       "http://xml.org/sax/properties/xml-string");
      out.write(s);
    }
    catch (IOException e) {
      throw new SAXException("Nested IOException", e);  
    }    
    
  }
    
  public void setDocumentLocator(Locator locator) {}
  
  public void startDocument() throws SAXException {
    this.output();
  }
  public void endDocument() throws SAXException {
    this.output();
  }
  
  public void startPrefixMapping(String prefix, String uri)
   throws SAXException {
    this.output();
  }
  
  public void endPrefixMapping(String prefix) 
   throws SAXException {
    this.output();
  }
  
  public void startElement(String namespaceURI, String localName,
   String qualifiedName, Attributes atts) throws SAXException {
    this.output();
  }
  
  public void endElement(String namespaceURI, String localName,
   String qualifiedName) throws SAXException {
    this.output();
  }
  
  public void characters(char[] text, int start, int length)
   throws SAXException {
    this.output();
  }
  
  public void ignorableWhitespace(char[] text, int start, 
   int length) throws SAXException {
    this.output();
  }
  
  public void processingInstruction(String target, String data)
   throws SAXException {
    this.output();
  }
  
   
  public void skippedEntity(String name)
   throws SAXException {
    this.output();
  }

  public static void main(String[] args) {
      
    if (args.length <= 0) {
      System.out.println(
       "Usage: java DocumentMerger url"
      );
      return;
    }
          
    try {
      XMLReader parser = XMLReaderFactory.createXMLReader();
      
      // Since this just writes onto the console, it's best
      // to use the system default encoding, which is what
      // we get by not specifying an explicit encoding here.
      Writer out = new OutputStreamWriter(System.out);
      ContentHandler handler = new DocumentMerger(parser, out);
      parser.setContentHandler(handler);
    
      parser.parse(args[0]);
      
      out.flush();
      out.close();
    }
    catch (Exception e) {
      System.err.println(e); 
    }
  
  }   
  
}

The document that's output may not be quite the same as the document that was read. Character references will have been resolved. General entity references will probably have been resolved. Parts of the prolog, especially the DOCTYPE declaration, may be missing. Attributes that were read in from defaults in the DTD will be explicitly specified. However, the complete information content of the original document should be present, even if the form is different.

The biggest issue with this program is finding a parser that recognizes the http://xml.org/sax/properties/xml-string property. In my tests, Xerces 1.4.3, Crimson, and Ælfred all threw a SAXNotRecognizedException or a SAXNotSupportedException. I have not yet found a parser that supports this property, and there's some suspicion in the SAX community that defining it in the first place may have been` a mistake.

The http://xml.org/sax/properties/dom-node property contains the org.w3c.dom.Node object corresponding to the current SAX event. For example, in the startElement() and endElement() methods, this property contains an org.w3c.dom.Element object representing that element. In the characters() method, this property contains the org.w3c.dom.Text object which contained the characters from which the text had been read.

Lexical events are those ephemera of parsing that don’t really mean anything. In some sense, they really aren’t part of the document’s information. Comments are the most obvious example. However, lexical data also includes entity boundaries, CDATA section delimiters, and the DOCTYPE declaration. What unifies all these is that they really don’t matter 99.9% of the time. Unfortunately, there’s that annoying 0.1% when you really do care about some lexical detail you’d normally ignore.

Parsers are not required to report lexical data; but if they want to do so, SAX provides a standard callback interface they can use, LexicalHandler, shown in Example 7.11. However, this interface is optional. Parsers are not required to support it. Notice that it is in the org.xml.sax.ext package, not the core org.xml.sax package.

package org.xml.sax.ext;

public interface LexicalHandler {

  public void startDTD(String name, String publicId, 
   String systemId) throws SAXException;
  public void endDTD() throws SAXException;

  public void startEntity(String name)
   throws SAXException;
  public void endEntity(String name) throws SAXException;

  public void startCDATA() throws SAXException;
  public void endCDATA() throws SAXException;

  public void comment(char[] text, int start, int length)
   throws SAXException;

}

Because parsers are not required to support the LexicalHandler interface, it can’t be registered with a setLexicalHandler() method in XMLReader like the other callback interfaces. Instead, it’s set as the value of the http://xml.org/sax/properties/lexical-handler property.

For example, Example 7.12 is a concrete implementation of LexicalHandler that dumps comments from an XML document onto System.out.

import org.xml.sax.*;
import org.xml.sax.ext.LexicalHandler;
import org.xml.sax.helpers.XMLReaderFactory;
import java.io.IOException;


public class CommentReader implements LexicalHandler {

  public void comment (char[] text, int start, int length)
   throws SAXException {

    String comment = new String(text, start, length);
    System.out.println(comment);

  }

  public static void main(String[] args) {

    // set up the parser
    XMLReader parser;
    try {
      parser = XMLReaderFactory.createXMLReader();
    }
    catch (SAXException e) {
      System.err.println("Error: could not locate a parser.");
      System.err.println(
       "Try setting the org.xml.sax.driver system property to "
       + "the fully package qualified name of your parser class."
      );
      return;
    }

    // turn on comment handling
    try {
      LexicalHandler handler = new CommentReader();
      parser.setProperty(
       "http://xml.org/sax/properties/lexical-handler", handler);
    }
    catch (SAXNotRecognizedException e) {
      System.err.println(
       "Installed XML parser does not provide lexical events...");
      return;
    }
    catch (SAXNotSupportedException e) {
      System.err.println(
       "Cannot turn on comment processing here");
      return;
    }

    if (args.length == 0) {
      System.out.println("Usage: java CommentReader URL");
    }

    // start parsing...
    try {
      parser.parse(args[0]);
    }
    catch (SAXParseException e) { // well-formedness error
      System.out.println(args[0] + " is not well formed.");
      System.out.println(e.getMessage()
       + " at line " + e.getLineNumber()
       + ", column " + e.getColumnNumber());
    }
    catch (SAXException e) { // some other kind of error
      System.out.println(e.getMessage());
    }
    catch (IOException e) {
      System.out.println("Could not read " + args[0]
       + " because of the IOException " + e);
    }

  }

  // do-nothing methods not needed in this example
  public void startDTD(String name, String publicId, 
   String systemId) throws SAXException {}
  public void endDTD() throws SAXException {}
  public void startEntity(String name) throws SAXException {}
  public void endEntity(String name) throws SAXException {}
  public void startCDATA() throws SAXException {}
  public void endCDATA() throws SAXException {}

}

The main() method builds an XMLReader, constructs an instance of CommentReader, and uses setFeature() to make this CommentReader the parser’s LexicalHandler. Then it parses the document indicated on the command line.

It’s amusing to run this across the XML source for various W3C specifications. For example, Here’s the output when the XML version of the XML 1.0 specification, second edition, is fed into CommentReader:

%java CommentReader http://www.w3.org/TR/2000/REC-xml-20001006.xml
ArborText, Inc., 1988-2000, v.4002
 ...............................................................
 XML specification DTD .........................................
 ...............................................................

TYPICAL INVOCATION:
#  <!DOCTYPE spec PUBLIC
#       "-//W3C//DTD Specification V2.1//EN"
#       "http://www.w3.org/XML/1998/06/xmlspec-v21.dtd">

PURPOSE:
  This XML DTD is for W3C specifications and other technical reports.
  It is based in part on the TEI Lite and Sweb DTDs.
…      

The comments you’re seeing are actually from the DTD used by the XML specification. Comments and processing instructions in the DTD, both internal and external subsets, are reported to their respective callback methods, just like comments and processing instructions in the instance document.

Example 7.12 is a pure LexicalHandler that does not implement any of the other SAX callback interfaces like ContentHandler. However, it’s not uncommon to implement several callback interfaces in one class. Among other advantages, that makes it a lot easier to write programs that rely on information that’s available in different interfaces.

The http://xml.org/sax/properties/declaration-handler property identifies the parser’s DeclHandler. DeclHandler, summarized in Example 7.13, is an optional interface in the org.xml.sax.ext package used by parsers to report those parts of the DTD that don’t affect the content of instance documents, specifically ELEMENT, ATTLIST and parsed ENTITY declarations. Together with the information reported by the DTDHandler, this gives you enough information to reproduce a parsed document’s DTD. The reproduced DTD may not be exactly the same as the original DTD. For instance, parameter entities will have been resolved and only the first declaration of each general entity will be reported. Nonetheless, the model represented by the entire DTD should be intact.

package org.xml.sax.ext;

public interface DeclHandler {

  public void elementDecl(String name, String model)
   throws SAXException;
  public void attributeDecl(String elementName, 
   String attributeName, String type, String mode, 
   String defaultValue) throws SAXException;
  public void internalEntityDecl(String name, String value) 
   throws SAXException;
  public void externalEntityDecl(String name, String publicID, 
   String systemID) throws SAXException;

}

Example 7.14 is a little DeclHandler I whipped up to help me make sense out of heavily modular, very customizable DTDs like XHTML 1.1 or SMIL 2.0. It takes advantage of the fact that all parameter entity references and conditional sections are replaced before the methods of DeclHandler are called. It implements the DeclHandler interface with methods that copy each declaration onto System.out. However, because parameter entity references and conditional sections are resolved before these methods are invoked, it outputs a single monolithic DTD. I can see, for example, exactly what the content model for an element such as blockquote really is without having to manually trace the parameter entity references through seven separate modules, and figuring out which modules are likely to be included and which ignored.

import org.xml.sax.*;
import org.xml.sax.ext.DeclHandler;
import org.xml.sax.helpers.XMLReaderFactory;
import java.io.IOException;


public class DTDMerger implements DeclHandler {

  public void elementDecl(String name, String model)
   throws SAXException {
    System.out.println("<!ELEMENT " + name + " " + model + " >");
  }
  
  public void attributeDecl(String elementName, 
   String attributeName, String type, String mode, 
   String defaultValue) throws SAXException {
     
    System.out.print("<!ATTLIST ");
    System.out.print(elementName);
    System.out.print(" ");
    System.out.print(attributeName);
    System.out.print(" ");
    System.out.print(type);
    System.out.print(" ");
    if (mode != null) {
      System.out.print(mode + " ");
    }
    if (defaultValue != null) {
      System.out.print('"' + defaultValue + "\" ");
    }
    System.out.println(">");   
     
  }
  
  public void internalEntityDecl(String name, 
   String value) throws SAXException {
     
    if (!name.startsWith("%")) { // ignore parameter entities
      System.out.println("<!ENTITY " + name + " \"" 
       + value + "\">");        
    }
    
  }
  
  public void externalEntityDecl(String name, 
   String publicID, String systemID) throws SAXException {
     
    if (!name.startsWith("%")) { // ignore parameter entities
      if (publicID != null) { 
        System.out.println("<!ENTITY " + name + " PUBLIC \"" 
         + publicID + "\" \"" + systemID + "\">");        
      
      }
      else {
        System.out.println("<!ENTITY " + name + " SYSTEM \"" 
         + systemID + "\">");        
      }
    }
    
  }

  public static void main(String[] args) {

    if (args.length <= 0) {
      System.out.println("Usage: java DTDMerger URL");
      return;
    }
    String document = args[0];
    
    XMLReader parser = null;
    try {
      parser = XMLReaderFactory.createXMLReader();
      DeclHandler handler = new DTDMerger();
      parser.setProperty(
       "http://xml.org/sax/properties/declaration-handler", 
       handler);
      parser.parse(document);
    }
    catch (SAXNotRecognizedException e) {
      System.err.println(parser.getClass() 
       + " does not support declaration handlers.");
    }
    catch (SAXNotSupportedException e) {
      System.err.println(parser.getClass() 
       + " does not support declaration handlers.");

    }
    catch (SAXException e) {
      System.err.println(e);
      // As long as we finished with the DTD we really don't care
    }
    catch (IOException e) { 
      System.out.println(
       "Due to an IOException, the parser could not check " 
       + document
      ); 
    }
   
  }
   
}

I ran this program across the start of an XHTML document (actually the XHTML 1.1 specification itself, though that detail doesn’t really matter since it’s the DTD we care about here, not the instance document. In fact, the instance document doesn’t even need to be well-formed as long as the error isn’t spotted until after the DOCTYPE declaration has been read.) Here’s the beginning of the merged DTD:

%java DTDMerger http://www.w3.org/TR/xhtml11
<!ATTLIST a onfocus CDATA #IMPLIED >
<!ATTLIST a onblur CDATA #IMPLIED >
<!ATTLIST form onsubmit CDATA #IMPLIED >
<!ATTLIST form onreset CDATA #IMPLIED >
<!ATTLIST label onfocus CDATA #IMPLIED >
…

If what you really want to know is the content specification for a particular element type, the output from this program is a lot easier to read than the original DTD. For example, here’s the original ELEMENT declaration for the p element:

<!ENTITY % p.element  "INCLUDE" >
<![%p.element;[
<!ENTITY % p.content
     "( #PCDATA | %Inline.mix; )*" >
<!ENTITY % p.qname  "p" >
<!ELEMENT %p.qname;  %p.content; >
<!-- end of p.element -->]]>

Now here’s the merged version:

<!ELEMENT p 
  (#PCDATA|br|span|em|strong|dfn|code|samp|kbd|var|cite|abbr
   |acronym|q|tt|i|b|big|small|sub|sup|bdo|a|img|map|object|input
   |select|textarea|label|button|ruby|ins|del|script|noscript)* >

I think you’ll agree the second version is a lot easier to follow and understand. There are good and valid reasons to write the original DTD in the form used by the first declaration. However, that’s just not a form you want to present to a human being instead of a computer.