org.openxml.x3p
Interface ErrorReport


public abstract interface ErrorReport
extends ErrorHandler

The error report facility is an implementation of the SAX error handler. It is activated by SAX error events, but rather than just throwing an exception, is capable of recording errors in an ordered error list, and returning the errors as formatted messages. It can also be used to report errors from X3P processors.

All errors are reported, stored and retrieved as SAX exceptions. Errors reported by a parser are likely to derive from SAXParseException, but the application should not assume all errors extend this class.

Some applications are interested in stopping at the first error and can request that the parsing/processing throw a SAX exception at the first error (not warning) they encounter. Other applications are interested in recovering from as many errors as possible, with only fatal errors stopping the parsing/processing. The application can then obtain an ordered list of errors including their location and description, for example, for the purpose of printing a log or error list in a GUI component.

When used with the OpenXML parser and compatible processors, each error is given a level number. Two parameters are used to control response to errors at different levels.

The report level determines which errors are to be recorded and reported back to the application. The three most common values are #REPORT_WARNING which reports all errors and warnings, REPORT_ALL_ERRORS which reports all errors but no warnings, and REPORT_NOTHING which supresses reporting.

The stop level determines which error level will stop the parser/processor by throwing a SAX exception. The three most common values are STOP_AT_NO_ERROR which will only stop if a fatal error is encountered (fatal errors are non recoverable), STOP_AT_FIRST_ERROR which will stop at the first error encountered, and #STOP_AT_CONTENT_ERROR which will swallow all parsing errors, but stop at a content, processing or general error.

When used with any other parser or SAX event driver processor, all errors are reported at GENERAL level, so the #STOP_AT_CONTENT_ERROR resolution is meaningless.

Once errors have been accumulated, they can be retrieved by the application in a variety of ways. The application should always be interested in the last error recorded, if no exception was thrown. The application can retrieve the error list one by one, either as exceptions, formatted messages, or error level. The application can also request an array of errors (exceptions or formatted messages) at a given level.

The formatting of the error message consists of the error location, it's level and it's message. When parsing the location is likely to include the document's name (system identifier), line number and column within the line. When processing the location is likely to include a node or element's location in the document tree.

Version:
$Revision: 1.1 $ $Date: 1999/04/18 01:56:36 $
Author:
Assaf Arkin
See Also:
ErrorHandler, SAXException

Field Summary
static int CONTENT
          Document content error.
static int FATAL
          Fatal error after which processing cannot continue.
static int GENERAL
          Generic error.
static int PROCESSING
          Generic document processing error.
static int REPORT_ALL_ERRORS
          Report all errors but no warnings.
static int REPORT_NOTHING
          Ignore all errors, nothing is reported.
static int REPORT_WITH_WARNING
          Report all errors and warnings.
static int STOP_AT_CONTENT
          Stop at first content error.
static int STOP_AT_FATAL
          Stop at fatal error only.
static int STOP_AT_FIRST_ERROR
          Stop at error encountered.
static int STOP_AT_NO_ERROR
          Stop at no error (except fatal).
static int STOP_AT_PROCESSING
          Stop at first processing error.
static int STOP_AT_VALIDITY
          Stop at first validity error.
static int STOP_AT_WELL_FORMED
          Stop at first well formed error.
static int VALIDITY
          Document validity error.
static int WARNING
          Warning.
static int WELL_FORMED
          Well formed document error level.
 
Method Summary
 void fatalError(java.lang.Exception except)
          Report a fatal exception derived from an exception.
 int getCount()
          Returns the number of errors contained in this report.
 int getErrorLevel(int index)
          Returns the error level of the numbered error.
 SAXException getException(int index)
          Returns the error's exception.
 SAXException getLastException()
          Return the last error exception.
 java.lang.String getLastMessage()
          Return the last error as formatted message.
 java.lang.String getMessage(int index)
          Returns formatted error message.
 boolean isReporting(int errorLevel)
          True if errors in this level are to be reported.
 SAXException[] listExceptions(int fromErrorLevel)
          Returns a list of error exceptions.
 java.lang.String[] listMessages(int fromErrorLevel)
          Returns a list of error messages.
 void reportError(int errorLevel, Node node, SAXException except)
          Report a processing error at the specified level.
 void reportError(int errorLevel, SAXParseException except)
          Report a parse error at the specified level.
 void reportError(int errorLevel, java.lang.String location, SAXException except)
          Report a processing error at the specified level.
 
Methods inherited from interface org.xml.sax.ErrorHandler
error, fatalError, warning
 

Field Detail

WARNING

public static final int WARNING
Warning. By definition warnings do not convey any error status, they merely point at the potential for an error. Usually warnings are not reported and they cannot be stopped at.

WELL_FORMED

public static final int WELL_FORMED
Well formed document error level. This error level indicates that the source XML document is not well formed (e.g. attribute value not quoted). Well formed errors are very common in HTML files, but should generally not occur in XML files. Generally the parser will report but not stop at well formed errors.

VALIDITY

public static final int VALIDITY
Document validity error. This error level indicates that the document is not valid according to the specified content model. Validitiy errors are thrown by a validating parser or a validating processor, and usually result in corrective action (such as adding or removing an element). Generally the parser will report but not stop at validity errors.

CONTENT

public static final int CONTENT
Document content error. This error level indicates an error in the actual document content, given that the document is properly constructed. A content error is likely to be reported by a document processor (e.g. XSL, XQL) that relies on the content to convey meaningful information.

PROCESSING

public static final int PROCESSING
Generic document processing error. This error level indicates an error that occurs while processing the document, but is not related directly to the document content. For example, an XSL processor may report internal errors in this way, while reporting XSL template errors using the content error level.

GENERAL

public static final int GENERAL
Generic error. This error level has no special meaning except that errors reported in this level are not considered fatal, and thus, might be corrected and ignored.

This is the default error level, if none is specified (e.g. when using this report as a SAX error handler).


FATAL

public static final int FATAL
Fatal error after which processing cannot continue. This error level is the most serve, in that, after a fatal error has occured, processing must stop. Fatal errors are reported and are always thrown. A fatal error can be an IO exception opening a document file, or it can be a runtime exception (e.g. null pointer), or it can be any other exception from which the processor cannot recover and continue processing.

REPORT_WITH_WARNING

public static final int REPORT_WITH_WARNING
Report all errors and warnings. Using this report level, every error and warning generated will be reported and can later be retrieved from this report.

REPORT_ALL_ERRORS

public static final int REPORT_ALL_ERRORS
Report all errors but no warnings. Using this report level, every error generated will be reported and can later be retrieved from this report. Warnings are ignored.

REPORT_NOTHING

public static final int REPORT_NOTHING
Ignore all errors, nothing is reported. This report level is generally used in two cases: a) when the application is not interested in reading any errors and assumes all operations will complete successfuly, b) when the application uses STOP_AT_FIRST_ERROR but is not interested in warnings. We do not recommend a) as an approach to application design.

STOP_AT_WELL_FORMED

public static final int STOP_AT_WELL_FORMED
Stop at first well formed error. Will stop when the first well formed error is encountered, but will also stop at all other error levels.

This level is used when the document must be correct, or else there is no point in handling it.


STOP_AT_VALIDITY

public static final int STOP_AT_VALIDITY
Stop at first validity error. Will stop when the first validity error is encountered, will not stop for well formed errors, but will stop for content and processing errors.

This level is used when the document must be valid, or else there is no point in handling it.


STOP_AT_CONTENT

public static final int STOP_AT_CONTENT
Stop at first content error. Will stop when the first content error is encountered, will not stop for well formed or validity errors, but will stop for processing errors.

STOP_AT_PROCESSING

public static final int STOP_AT_PROCESSING
Stop at first processing error. Will stop when the first processing error is encountered, will not stop for well formed, validity or content errors.

STOP_AT_FATAL

public static final int STOP_AT_FATAL
Stop at fatal error only. The first fatal error will always stop the processing. Using this stop level simply reports but do not stop at lower error levels.

This level is used when the application assumes that all errors can be properly corrected, or when the application reports all errors not just the last one.


STOP_AT_FIRST_ERROR

public static final int STOP_AT_FIRST_ERROR
Stop at error encountered. This level is used when the application wishes to assure that there are absolutely no errors, but does not both to recover from them or check the error report.

This level is equivalent to STOP_AT_WELL_FORMED.


STOP_AT_NO_ERROR

public static final int STOP_AT_NO_ERROR
Stop at no error (except fatal). This level is used when the application assumes that all errors are recoverable, or prefers to get a full report at the end of processing. Fatal errors will always stop the processing.

This level is equivalent to STOP_AT_FATAL.

Method Detail

reportError

public void reportError(int errorLevel,
                        java.lang.String location,
                        SAXException except)
                 throws SAXException
Report a processing error at the specified level. A textual string is used to identify the error's location. It is reported and possibly thrown based on the error level.
Parameters:
errorLevel - The error level to report
location - The location at which the error occured
except - The exception to be reported
Throws:
SAXException - Will throw the exception if set to stop at this error level

reportError

public void reportError(int errorLevel,
                        Node node,
                        SAXException except)
                 throws SAXException
Report a processing error at the specified level. A document tree node is used to identify the error's location in the document. It is reported and possibly thrown based on the error level.
Parameters:
errorLevel - The error level to report
node - The document tree node at which the error occured
except - The exception to be reported
Throws:
SAXException - Will throw the exception if set to stop at this error level

reportError

public void reportError(int errorLevel,
                        SAXParseException except)
                 throws SAXException
Report a parse error at the specified level. The parse exception already contains the error's location in the source document. It is reported and possibly thrown based on the error level.
Parameters:
errorLevel - The error level to report
except - The exception to be reported
Throws:
SAXException - Will throw the exception if set to stop at this error level

fatalError

public void fatalError(java.lang.Exception except)
                throws SAXException
Report a fatal exception derived from an exception. The exception is usually an I/O or runtime exception, which is transformed to and reported as a fatal error. This method will always throw an exception.
Parameters:
except - The exception to be reported as fatal
Throws:
SAXException - The exception is reported and thrown as this SAX exception

isReporting

public boolean isReporting(int errorLevel)
True if errors in this level are to be reported. This method can be used to determine if this report is interested in an error of a particular level (e.g. warnings are often ignored).
Parameters:
erroLevel - The error level to be reported
Returns:
True if interested in this error level

getLastException

public SAXException getLastException()
Return the last error exception. This is the last error reported to this facility, even if it was not stored; it will not be a warning.
Returns:
The error as exception

getLastMessage

public java.lang.String getLastMessage()
Return the last error as formatted message. This is the last error reported to this facility, even if it was not stored; it will not be a warning. The error message is formatted to contain the location of the error and the description of the message. The formatted string is returned in the current locale.
Returns:
The formatted message

listMessages

public java.lang.String[] listMessages(int fromErrorLevel)
Returns a list of error messages. The returned list is in the same order in which the errors were reported. To selectively view errors, set fromErrorLevel to a value that is higher than a WARNING.
Parameters:
fromErrorLevel - Return only errors of this or higher error level
Returns:
List of error message (could be empty)

listExceptions

public SAXException[] listExceptions(int fromErrorLevel)
Returns a list of error exceptions. The returned list is in the same order in which the errors were reported. To selectively view errors, set fromErrorLevel to a value that is higher than a WARNING.
Parameters:
fromErrorLevel - Return only errors of this or higher error level
Returns:
List of errors (could be empty)

getCount

public int getCount()
Returns the number of errors contained in this report. It is possible that new errors will be added to this report after this method has returned.
Parameters:
Number - of errors in report

getException

public SAXException getException(int index)
Returns the error's exception. Each error is associated with a single SAXException exception, SAXPraseException if the error was generated by a parser.
Parameters:
index - The error message number
Returns:
The error exception

getMessage

public java.lang.String getMessage(int index)
Returns formatted error message. The error message is formatted to contain the location of the error and the description of the message. The formatted string is returned in the current locale.
Parameters:
index - The error message number
Returns:
The formatted message

getErrorLevel

public int getErrorLevel(int index)
Returns the error level of the numbered error. This method can be used to tell if a given error is fatal, warning or other.
Parameters:
index - The error message number
Returns:
The error level