Managing Errors

The DataDirect XML Converters API provides the following ways to manage errors in your applications:

■	“EDI Analyzer”

■	“ConverterListener Interface”

■	“EDIConverterListener Interface”

■	“EDIConverterException Interface”

NOTE: These features are implemented only for the EDI XML Converter.

EDI Analyzer

The EDI Analyzer API allows you to analyze an EDI stream for errors that can cause the XML Converter to throw an exception before converting the EDI stream to XML. A report generated by the EDI Analyzer in XML format identifies and describes any errors. The EDI Analyzer also automatically generates Accept/Reject messages that can be forwarded to the EDI sender.

The EDI Analyzer API is supported for EDI-to-XML conversions only (not vice versa).

See Chapter 3, “Analyzing EDI-to-XML Conversions” for more information on the EDI Analyzer API.

ConverterListener Interface

In an application, it is not always necessary for warnings and errors to throw exceptions and stop the conversion process. You may want to simply make the application aware that a problem has occurred and allow it to recover (or not) from the warning or the error.

The ConverterListener interface allows you to intercept warnings, errors, and fatal errors and manage them separately. The default action is to ignore warnings and to throw exceptions for errors and fatal errors.

Processing can resume after both warnings and errors. For example, if an exception is not thrown, processing continues. If an error occurs, it is possible that other errors will cascade from the first. Fatal errors can be reported, but on their return, a ConverterException is always thrown by the EDI XML Converter engine. The exception that is thrown is an instance of ConverterException or one of its subclasses such as ConverterArgumentException.

Example

See “Example 8” for an example of registering a ConverterListener.

EDIConverterListener Interface

The EDIConverterListener is a specialized version of ConverterListener; its methods provide detailed information about error conditions. The invalidCharacter() method, for example, is called when a character does not match the specified encoding in the EDI stream. Similarly, unknownCodeListValue() is called when a codelist validation fails.

EDIConverterException Interface

Typically, EDI-based conversions are more complex than other types of conversions (those for CSV and tab-delimited files, for example). By providing more contextual information about where a problem has occurred, the EDI XML Converter allows you to capture the error and return standard EDI messages back to the sender of the message. For example, you can return CONTRL (for EDIFACT), 997 (for X12), 999 (for HIPAA), or ACK (for HL7).

The EDIConverterException is a specialized version of ConverterException that contains extra information about the context of errors in EDI files. When a ConverterException is thrown while processing an EDI file, or when a ConverterListener is registered and a warning(), error(), or fatalError() is called, the exception that is thrown is probably EDIConverterException. This exception contains the following methods to probe the context of the specific error – GetContentData(), getControlData(), getData(), and getError(). Processing can recover from both warnings and errors; however, fatal errors always stop the processing.

Error Diagnostics

Full context information is provided when an error is encountered in the EDI file, including the error number according to the local EDI dialect. For example, many EDIFACT errors are recorded in the 0085 element codelist, and if an error matches one of those, it is reported as such.