SAX Parse exception

An error message is not particularly helpful when no indication is given as to where the error was detected in the XML document. To a greater or lesser extent, depending on the type of error concerned, all errors could be traced to an exact point in the data, and this information is often of vital assistance for correcting such errors.

Line and character position

Most parsers count linefeed characters as the document is parsed, so can report which line of text the error occurred on (note that this feature alone supplies a very good reason for including linefeeds in the text when writing XML data).

Some parsers may even keep track of the number of characters they have read from the current line, so can provide even more precise information:

ERROR: Line 35, Char 92 - missing end-tag '</Para>'

Entity containing error

To complicate matters, a single XML data stream may be derived from a number of data sources (which reference each other using external entities), and the line number alone is not sufficient in these cases. It is necessary to know which source file or stream the parser was working through at the time.

For example, an error reported to be on line 53 could have occurred in any of the entities used in a document that has at least this many lines. Without the name of the entity concerned, it would be necessary to look at them all for the error.

SAXParse interface

The parser can tell the application the entity, line number and character number of the warning or error using an object that implements the SAXParseInterface. This interface defines the following methods:

int     getLineNumber();
int     getColumnNumber();
String  getSystemId();
String  getPublicId();

Note that this interface is unchanged in SAX 2.0.

Most of these methods are self-explanatory, given the discussion above. The getLineNumber method returns the line number of the error ('-1' if this information is not available). The getSystemId and getPublicId methods return their respective source location information types. The getColumnNumber method returns the number of the column where the error occurred (again, '-1' if not available). The term 'column' is used here to mean the character position within the line (which can be thought of as a 'row').

Example

The following example shows this information being used to provide a more informative error message:

Locator myLocator;
...
public void error(SAXParseException err)
{
  int ln = err.getLineNumber();
  int ch = err.getColumnNumber();
  String ent = err.getSystemID();

  System.out.println( "ERROR (" + err + ")" +
                      " at " + ln + ":" + ch +
                      " in file " + ent );
}