SAXException may not always be the exception you want to throw, however. For example, suppose you’re parsing a document containing an XML digital signature, and the endElement() method notices that the Base-64 encoded text provided in the P element, which represents the prime modulus of a DSA key, does not decode to a prime number like it’s supposed to. You naturally want to throw a java.security.InvalidKeyException to warn the client application of this. However, endElement() cannot throw a java.security.InvalidKeyException, only a SAXException In this case, you wrap the exception you really want to throw inside a SAXException and throw the SAXException instead. For example,

Exception nestedException 
 = new InvalidKeyException("Modulus is not prime!");
SAXException e = new SAXException(nestedException);
throw e;

The code that catches the SAXException can retrieve the original exception using the getException() method. For example, the client application method might indeed be declared to throw an InvalidKeyException so you could cast the nested exception to its real type and throw it into the appropriate catch block elsewhere in the call chain.

catch (SAXException e) { 
  Exception rootCause = e.getException();
  if (rootCause == null) {
    // handle it as an XML problem...
  }
  else {
    if (rootCause instanceof InvalidKeyException) {
      InvalidKeyException ike = (InvalidKeyException) rootCause;
      throw ike;
    }
    else if (rootCause instanceof SomeOtherException) {
      SomeOtherException soe = (SomeOtherException) rootCause;
      throw soe;  
    }
    …
  }
}

SAX defines several more specific subclasses of SAXException for specific problems, though most methods are only declared to throw a generic SAXException. These subclasses include SAXParseException, SAXNotRecognizedException, and SAXNotSupportedException. In addition parsers can extend SAXException with their own custom subclasses, though few do this.

A SAXParseException indicates a fatal error, error, or warning in an XML document. The parse() method of the XMLReader interface throws this when it encounters a well-formedness error. SAXParseException is also passed as an argument to the methods of the ErrorHandler interface to signal any of the three kinds of problems an XML document may contain.

Besides the usual exception methods like getMessage() and printStackTrace() that SAXParseException inherits from its superclasses, it provides methods to get the public ID and system ID of the file where the well-formedness error occurs (Remember, XML documents that use external parsed entities can be broken up over multiple separate files.) and the line number and column number where the well-formedness error appears within that file.

package org.xml.sax;

public class SAXParseException extends SAXException {
    
  public SAXParseException(String message, Locator locator)
  public SAXParseException(String message, Locator locator,
	 Exception e) 
  public SAXParseException(String message, String publicID, 
   String systemID, int lineNumber, int columnNumber)
  public SAXParseException(String message, String publicID, 
   String systemID, int lineNumber, int columnNumber, 
   Exception e)
   
  public String getPublicId()
  public String getSystemId()
  public int    getLineNumber()
  public int    getColumnNumber()
    
}

The lines and column numbers reported by the parser for the problem may not always be perfectly accurate. Nonetheless, they should be close to where the problem begins or ends. (Some parsers give the line and column numbers for the start-tag of a problem element. Others give the give the line and column numbers for the end-tag.) If the document is so malformed that the parser can’t even begin working with it, especially if it isn’t an XML document at all, then the parser will probably indicate that the error occurred at line -1, column -1.

Example 7.6 enhances last chapter’s SAXChecker program so that it reports the line numbers of any well-formedness errors. Since there are two catch blocks, one for SAXParseException and one for the more generic SAXException, it’s possible to distinguish between well-formedness errors and other problems such as not being able to find the right XMLReader implementation class.

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


public class BetterSAXChecker {

  public static void main(String[] args) {
  
    if (args.length <= 0) {
      System.out.println("Usage: java BetterSAXChecker URL");
      return;
    }
    String document = args[0];
    
    try {
      XMLReader parser = XMLReaderFactory.createXMLReader();
      parser.parse(document);
      System.out.println(document + " is well-formed.");
    }
    catch (SAXParseException e) {
      System.out.print(document + " is not well-formed at ");
      System.out.print("Line " + e.getLineNumber() 
       + ", column " +  e.getColumnNumber() );
      System.out.println(" in the entity " + e.getSystemId());
    }
    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 output I got when I first ran it across my Cafe con Leche home page. The first time I did not specify a parser which produced a generic SAXException. The second time I corrected that mistake, and a SAXParseException signaled a well-formedness error.

%java BetterSAXChecker http://www.cafeconleche.org
Could not check document because System property 
 org.xml.sax.driver not specified      
%java -Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser 
 BetterSAXChecker http://www.cafeconleche.org
http://www.cafeconleche.org is not well-formed at Line 64, 
column 64 in the entity http://www.cafeconleche.org/

XML includes a few errors that fall into a gray area. These are errors but neither fatal well-formedness errors nor non-fatal validity errors. The most common such error is an ambiguous content model in an element declaration. For example, consider this declaration which states that an Actor can have between 0 and 2 Parts:

<!ELEMENT Actor (Part?, Part?)>

The problem occurs with an Actor element that has one Part like this:

<Actor>
  <Part>Cyrano</Part>
</Actor>

Does this one Part match the first Part in the content model or the second? There’s no way to tell. Some parsers have trouble with this construct while other parsers don’t notice any problem at all. The XML specification says this is an error, but does not classify it as a fatal error.

Different parsers treat these not necessarily fatal errors differently. Some parsers throw a SAXParseException when one is encountered. Other parsers let them pass without comment. And still others report them in a different way but not throw an exception. For maximum compatibility, try to design your DTDs and instance documents so these are not a problem.