Presents your 
XML E-NEWSLETTER for April 9, 2003

<------------------------------------------->

HANDLE DOM EXCEPTIONS IN JAVA

When working with Java-based XML parsers, you are often faced with
handling exceptions. Some exceptions are simple to handle, while others 
are more difficult. In this article, we'll look at some common exceptions 
seen while working with XML documents and explore how to manage them.

DOM EXCEPTIONS

When parsing with a DOM parser, the XML document is processed all at
once and stored in memory. The in-memory object is referred to as a Document
Object Model--which is basically an object-oriented approach to
accessing the underlying XML document. Many things can go wrong with the
processing of XML documents under DOM.

Most DOM-oriented exceptions occur as an instance of the DOMException
class. This class supports 15 different, specific exception conditions.
Each condition is specified as a member of the DOMException class called
code. In addition to the code member, the DOMException class contains a set
of 15 static members, which are used to determine the condition of the exception.

The 15 conditions are:

* DOMSTRING_SIZE_ERR
* HIERARCHY_REQUEST_ERR
* INDEX_SIZE_ERR
* INUSE_ATTRIBUTE_ERR
* INVALID_ACCESS_ERR
* INVALID_CHARACTER_ERR
* INVALID_MODIFICATION_ERR
* INVALID_STATE_ERR
* NAMESPACE_ERR
* NO_DATA_ALLOWED_ERR
* NO_MODIFICATION_ALLOWED_ERR
* NOT_FOUND_ERR
* NOT_SUPPORTED_ERR
* SYNTAX_ERR
* WRONG_DOCUMENT_ERR

When a DOMException is thrown, you won't know which of these conditions
caused the exception without examining the code in the exception object.
In order to process the exception appropriately, you'll need to determine
which condition caused the exception.

LISTING A shows a sample Java program that fails when creating a new DOM document:

Listing A: DOMFail.Java
import org.apache.xerces.dom.*;
import org.w3c.dom.*;

public class DOMFail {

    public static void main(String[] args) {
        Document  doc = new DocumentImpl();
        Element rootElement;

        try{
            rootElement = doc.createElement("Order");
            rootElement.setAttribute("<id", "109823");
            doc.appendChild( rootElement );
        } catch (DOMException e) {
            switch(e.code) {
                case DOMException.DOMSTRING_SIZE_ERR:
                    break;
                case DOMException.HIERARCHY_REQUEST_ERR:
                    break;
                case DOMException.INDEX_SIZE_ERR:
                    break;
                case DOMException.INUSE_ATTRIBUTE_ERR:
                    break;
                case DOMException.INVALID_ACCESS_ERR:
                    break;
                case DOMException.INVALID_CHARACTER_ERR:
                    System.out.println("There is an invalid character");
                    break;
                case DOMException.INVALID_MODIFICATION_ERR:
                    break;
                case DOMException.INVALID_STATE_ERR:
                    break;
                case DOMException.NAMESPACE_ERR:
                    break;
                case DOMException.NO_DATA_ALLOWED_ERR:
                    break;
                case DOMException.NO_MODIFICATION_ALLOWED_ERR:
                    break;
                case DOMException.NOT_FOUND_ERR:
                    break;
                case DOMException.NOT_SUPPORTED_ERR:
                    break;
                case DOMException.SYNTAX_ERR:
                    break;
                case DOMException.WRONG_DOCUMENT_ERR:
                    break;
                default:
                    System.out.println("Unknown DOM exception");
                    break;
            }
        }
    }
}

Notice that we use a switch mechanism to determine which condition is
met. This way we can easily test each condition until we find the correct one.

In this example, we've placed a message in the condition for an invalid
character. When you compile and run this example, you'll see the message
There is an invalid character. You'll want to handle each condition
appropriately, rather than just leaving the condition empty.

You may want to extract the conditional exception handling and place it
in its own method or even its own class. That way, you could have simpler
exception handling in your code. For example, we might create a new
class called DOMExceptionHandler, as shown in LISTING B:

Listing B: DOMExceptionHandler.Java
import org.w3c.dom.*;

public class DOMExceptionHandler {
    public static void HandleDOMException(DOMException e) {
        if (e != null) {
            switch(e.code) {
                case DOMException.DOMSTRING_SIZE_ERR:
                    break;
                case DOMException.HIERARCHY_REQUEST_ERR:
                    break;
                case DOMException.INDEX_SIZE_ERR:
                    break;
                case DOMException.INUSE_ATTRIBUTE_ERR:
                    break;
                case DOMException.INVALID_ACCESS_ERR:
                    break;
                case DOMException.INVALID_CHARACTER_ERR:
                    System.out.println("There is an invalid character");
                    break;
                case DOMException.INVALID_MODIFICATION_ERR:
                    break;
                case DOMException.INVALID_STATE_ERR:
                    break;
                case DOMException.NAMESPACE_ERR:
                    break;
                case DOMException.NO_DATA_ALLOWED_ERR:
                    break;
                case DOMException.NO_MODIFICATION_ALLOWED_ERR:
                    break;
                case DOMException.NOT_FOUND_ERR:
                    break;
                case DOMException.NOT_SUPPORTED_ERR:
                    break;
                case DOMException.SYNTAX_ERR:
                    break;
                case DOMException.WRONG_DOCUMENT_ERR:
                    break;
                default:
                    System.out.println("Unknown DOM exception");
                    break;
            }
        }
    }  
}

Now that we have a special handler class for our DOM exceptions, we can
call it from within our processing code. LISTING C shows a revision of
our DOMFail class that uses our new DOMExceptionHandler class:

Listing C: DOMFail2.Java
import org.apache.xerces.dom.*;
import org.w3c.dom.*;

public class DOMFail2 {

    public static void main(String[] args) {
        Document  doc = new DocumentImpl();
        Element rootElement;

        try{
            rootElement = doc.createElement("Order");
            rootElement.setAttribute("<id", "109823");
            doc.appendChild( rootElement );
        } catch (DOMException e) {
            DOMExceptionHandler.HandleDOMException(e);
        }
    }
}

This new class is much simpler than our original DOMFail class. It also
enables us to more easily reuse our exception handler code. Instead of
cutting and pasting the handler code each time we need it, we now just 
call the DOMExceptionHandler class.

Brian Schaffner is an associate director for Fujitsu Consulting. He provides
architecture, design, and development support for Fujitsu's Technology
Consulting practice.
----------------------------------------