ErrorReport (NetPhantom® 8.0 Java API Specification)

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

All Methods Instance Methods Abstract Methods
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:
    errorLevel - 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.
    Returns:
    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

Interface ErrorReport

Field Summary

Method Summary

Methods inherited from interface org.xml.sax.ErrorHandler

Field Detail

WARNING

WELL_FORMED

VALIDITY

CONTENT

PROCESSING

GENERAL

FATAL

REPORT_WITH_WARNING

REPORT_ALL_ERRORS

REPORT_NOTHING

STOP_AT_WELL_FORMED

STOP_AT_VALIDITY

STOP_AT_CONTENT

STOP_AT_PROCESSING

STOP_AT_FATAL

STOP_AT_FIRST_ERROR

STOP_AT_NO_ERROR

Method Detail

reportError

reportError

reportError

fatalError

isReporting

getLastException

getLastMessage

listMessages

listExceptions

getCount

getException

getMessage

getErrorLevel