|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 |
public static final int WARNING
public static final int WELL_FORMED
public static final int VALIDITY
public static final int CONTENT
public static final int PROCESSING
public static final int GENERAL
This is the default error level, if none is specified (e.g. when using this report as a SAX error handler).
public static final int FATAL
public static final int REPORT_WITH_WARNING
public static final int REPORT_ALL_ERRORS
public static final int REPORT_NOTHING
STOP_AT_FIRST_ERROR
but is not interested in warnings. We
do not recommend a) as an approach to application design.public static final int STOP_AT_WELL_FORMED
This level is used when the document must be correct, or else there is no point in handling it.
public static final int STOP_AT_VALIDITY
This level is used when the document must be valid, or else there is no point in handling it.
public static final int STOP_AT_CONTENT
public static final int STOP_AT_PROCESSING
public static final int STOP_AT_FATAL
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.
public static final int STOP_AT_FIRST_ERROR
This level is equivalent to STOP_AT_WELL_FORMED
.
public static final int STOP_AT_NO_ERROR
This level is equivalent to STOP_AT_FATAL
.
Method Detail |
public void reportError(int errorLevel, java.lang.String location, SAXException except) throws SAXException
errorLevel
- The error level to reportlocation
- The location at which the error occuredexcept
- The exception to be reportedpublic void reportError(int errorLevel, Node node, SAXException except) throws SAXException
errorLevel
- The error level to reportnode
- The document tree node at which the error occuredexcept
- The exception to be reportedpublic void reportError(int errorLevel, SAXParseException except) throws SAXException
errorLevel
- The error level to reportexcept
- The exception to be reportedpublic void fatalError(java.lang.Exception except) throws SAXException
except
- The exception to be reported as fatalpublic boolean isReporting(int errorLevel)
erroLevel
- The error level to be reportedpublic SAXException getLastException()
public java.lang.String getLastMessage()
public java.lang.String[] listMessages(int fromErrorLevel)
WARNING
.fromErrorLevel
- Return only errors of this or higher
error levelpublic SAXException[] listExceptions(int fromErrorLevel)
WARNING
.fromErrorLevel
- Return only errors of this or higher
error levelpublic int getCount()
Number
- of errors in reportpublic SAXException getException(int index)
SAXException
exception, SAXPraseException
if the error was generated by a parser.index
- The error message numberpublic java.lang.String getMessage(int index)
index
- The error message numberpublic int getErrorLevel(int index)
index
- The error message number
|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |