Handling XML binding error and warning messages

XML specifications define errors and warnings. You handle them by writing and declaring an XML error handler. The API for exceptions defines what the XML parser returns. The exception handler uses the SAX protocol.

About this task

There are three types of error in the XML specification: error, fatal error and warning.

An error is a violation of the rules in the specification. In this case, the XML parser is allowed to recover from the error and continue processing.
A fatal error is any error that causes an XML document to be no longer well formed. In this case, the XML parser is not allowed to continue normal processing. It might, however, keep processing the XML document to search for further errors.
A warning is generated in situations that are not necessarily an error, but something has occurred that the document author might like to know about. For example, when an XML type is bound on a XOM type, its XOM name might have been changed if it already exists in the XOM. This modification is notified as a warning.

The package ilog.rules.xml defines the error classes and exceptions returned by an XML file parser.

The IlrXmlError interface defines the base error or warning returned by an XML parser.
The IlrXmlErrorException class defines the exception thrown by an XML parser when errors occur.
The IlrXmlFatalErrorException class defines the exception thrown by an XML parser when fatal errors occur.

In most cases, you pass a schema, an XML document, and a handler object to the XML driver, which processes the XML and invokes the appropriate methods.

Diagram showing the main APIs for XML binding

A user handler that is linked to a Simple API for XML (SAX) parser is notified of any SAX event during the parsing of a schema or an XML document. SAX is the protocol that most servlets and network-oriented programs use to transmit and receive XML documents because it is the fastest and least memory-intensive mechanism that is currently available for dealing with XML documents.

Rather than building a complete representation of the XML document, the SAX parser executes a series of events as it reads the document from beginning to end. These events are passed to the event handler, which provides access to the contents of the document.

Procedure

To implement and declare an XML error handler:

Use the IlrXmlErrorHandler interface to filter or declare new errors during XML parsing.
Implement the IlrXmlErrorHandler interface and declare it to an XML driver during its initialization to activate the XML binding error handling process.
Use the methods processWarning and or processError to send errors andwarnings to this handler.
Declare and memorize notified errors and warnings by calling the IlrXmlErrorManager methods.

Implement a simple user error handler, using following code:

Public class MyXmlErrorHandler
Implements IlrXmlErrorHandler
{    
    IlrXmlErrorManager manager = null;
    void processWarning ( IlrXmlError error ) throws 
IlrXmlFatalErrorException
    {       
       manager.insertError ( error, this );
    }    
    void processError ( IlrXmlError error ) throws IlrXmlFatalErrorException 
    {       
       manager.insertError ( error, this );    
    }    
    ...
    void setErrorManager ( IlrXmlErrorManager manager )    
    {       
       this.manager = manager;    
    }
}

The handler transforms any XML warning into an error.

Build a new XML driver with the previous error handler using the following code:

// configuration setting
IlrResources resource = new IlrResources();
resource.put( "ilog.rules.xml.errorHandlerClass", "MyXmlErrorHandler" );
...
IlrXmlHelper.createDataDriver(resource);