org.openxml.parser

Interface ErrorReport

All Superinterfaces:

ErrorHandler

All Known Implementing Classes:

ErrorReportImpl

public 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 SAXException, 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_WITH_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 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 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.

Author:

Assaf Arkin

See Also:

ErrorHandler, SAXException

Field Summary

Fields

Modifier and Type	Field and Description
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

Modifier and Type	Method and Description
void	fatalError(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.
String	getLastMessage() Return the last error as formatted message.
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.
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, SAXException except) Report a parse error at the specified level.
void	reportError(int errorLevel, 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

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.

See Also:

Constant Field Values

WELL_FORMED

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.

See Also:

Constant Field Values

VALIDITY

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.

See Also:

Constant Field Values

CONTENT

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.

See Also:

Constant Field Values

PROCESSING

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.

See Also:

Constant Field Values

GENERAL

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).

See Also:

Constant Field Values

FATAL

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.

See Also:

Constant Field Values

REPORT_WITH_WARNING

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.

See Also:

Constant Field Values

REPORT_ALL_ERRORS

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.

See Also:

Constant Field Values

REPORT_NOTHING

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.

See Also:

Constant Field Values

STOP_AT_WELL_FORMED

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.

See Also:

Constant Field Values

STOP_AT_VALIDITY

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.

See Also:

Constant Field Values

STOP_AT_CONTENT

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.

See Also:

Constant Field Values

STOP_AT_PROCESSING

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.

See Also:

Constant Field Values

STOP_AT_FATAL

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.

See Also:

Constant Field Values

STOP_AT_FIRST_ERROR

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.

See Also:

Constant Field Values

STOP_AT_NO_ERROR

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.

See Also:

Constant Field Values

Method Detail

reportError

void reportError(int errorLevel,
                 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

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

void reportError(int errorLevel,
                 SAXException 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

void fatalError(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

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

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

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

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

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

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

SAXException getException(int index)

Returns the error's exception. Each error is associated with a single SAXException exception, SAXParseException if the error was generated by a parser.

Parameters:

index - The error message number

Returns:

The error exception

getMessage

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

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