DOMException

You've probably noticed that many of the methods so far have been declared to throw a DOMException . This class shown in Example 9.15 is the generic exception for essentially anything that can go wrong while working with DOMfrom logical errors like making an element one of its own children to implementation bugs . Although it is a runtime exception that does not have to be caught, I nonetheless recommend that you always catch it or declare that your method throws it. Conceptually, this should be a checked exception; however, many languages that DOM supports, including C++ and Python, don't have checked exceptions, so DOM uses runtime exceptions in order to keep the semantics of the various methods as similar as possible across languages.

Example 9.15 The DOMException Class

 package org.w3c.dom; public class DOMException extends RuntimeException {   public DOMException(short code, String message);   public short code;   public static final short INDEX_SIZE_ERR              = 1;   public static final short DOMSTRING_SIZE_ERR          = 2;   public static final short HIERARCHY_REQUEST_ERR       = 3;   public static final short WRONG_DOCUMENT_ERR          = 4;   public static final short INVALID_CHARACTER_ERR       = 5;   public static final short NO_DATA_ALLOWED_ERR         = 6;   public static final short NO_MODIFICATION_ALLOWED_ERR = 7;   public static final short NOT_FOUND_ERR               = 8;   public static final short NOT_SUPPORTED_ERR           = 9;   public static final short INUSE_ATTRIBUTE_ERR         = 10;   public static final short INVALID_STATE_ERR           = 11;   public static final short SYNTAX_ERR                  = 12;   public static final short INVALID_MODIFICATION_ERR    = 13;   public static final short NAMESPACE_ERR               = 14;   public static final short INVALID_ACCESS_ERR          = 15; } 

DOMException is the only exception that DOM standard methods throw. DOM methods don't throw IOException , IllegalArgumentException , SAXException , or any other exceptions you may be familiar with from Java. In a few cases, the implementation classes may throw a different exception, especially NullPointerException ; and methods in non-DOM support classes such as org.apache. xerces.parser.DOMParser or javax.xml.transform.dom.DOMResult can most certainly throw these exceptions. However, the DOM methods themselves don't throw them.

Not only do DOM methods only throw DOMException s. They don't even throw any subclasses of DOMException . Here, DOM is following C++ conventions rather than Java conventions. Whereas Java tends to differentiate related exceptions through many different subclasses, ^[2] DOM uses named short constants to identify the different problems that can arise. This is also useful for languages like AppleScript in which exceptions aren't even classes. The exception code is exposed through DOMException 's public code field. The codes are defined as follows :

^[2] In Java 1.4, there are more than 50 different subclasses of IOException alone.

DOMException.DOMSTRING_SIZE_ERR

Something tried to put more than 2 billion characters into one string, not too likely in Java. (If you're trying to stuff that much text into one string, you're going to have other problems long before DOM complains.) This exception is really meant for other languages with much smaller maximum string sizes.

DOMException.HIERARCHY_REQUEST_ERR

An attempt was made to add a node where it can't go; for example, making an element a child of a text node, making an attribute a child of an element, adding a second root element to a document, or trying to make an element its own grandpa.

DOMException.INDEX_SIZE_ERR

A rare exception thrown by the splitText() method of a Text object resulting from an attempt to split the text before the beginning or after the end of the node.

DOMException.INUSE_ATTRIBUTE_ERR

An attempt was made to add an existing Attr to a new element without removing it from the old element first.

DOMException.INVALID_ACCESS_ERR

The class that implements the DOM interface does not support the requested method, even though you'd normally expect it to.

DOMException.INVALID_CHARACTER_ERR

A Unicode character was used where it isn't allowed; for example, an element name contained a dollar sign or a text node value contained a formfeed. Many DOM implementations miss at least some problems that can occur with invalid characters. This exception is not thrown as often as it should be.

DOMException.INVALID_MODIFICATION_ERR

The class that implements the DOM interface cannot change the object in the requested way, even though you'd normally expect it to; for example, it ran out of space for more child nodes.

DOMException.INVALID_STATE_ERR

The implementation class that backs the DOM interface being used has gotten confused and cannot perform the requested operation. This would generally indicate a bug in the implementation.

DOMException.NAMESPACE_ERR

The namespace prefixes or URIs specified are somehow incorrect; for example, the qualified name contains multiple colons, or the qualified name has a prefix but the namespace URI is null, or it has the prefix xml but the namespace URI is not http://www.w3.org/XML/1998/namespace .

DOMException.NOT_FOUND_ERR

A referenced node is not present in the document; for example, an attempt was made to remove an attribute the element does not have, or to insert a node before another node that is no longer in the document.

DOMException.NOT_SUPPORTED_ERR

The implementation does not support the requested object type; for example, an attempt was made to create a CDATA section node using an HTML document implementation.

DOMException.NO_DATA_ALLOWED_ERR

An attempt was made to set the value of an element, document, document fragment, document type, entity, entity reference, or notation node. These kinds of nodes always have null values.

DOMException.NO_MODIFICATION_ALLOWED_ERR

An attempt was made to change a read-only node. The most common reason for a node to be read-only is that it's a descendant of an entity reference node.

DOMException.SYNTAX_ERR

An attempt was made to set a value to a string that's illegal in context; for example, a comment value that contains the double hyphen -- or a CDATA section that contains the CDATA section end delimiter ]]> . In practice, most implementations do not watch for these sorts of syntax errors and do not throw this exception.

DOMException.WRONG_DOCUMENT_ERR

An attempt was made to insert or add a node into a document other than its owner (the document that originally created the node). DOM does not allow nodes to change documents. Instead it's necessary to use the importNode() method in the new Document to make a copy of the node you want to move.

Although there's no way for DOM to prevent programs from using error codes other than those listed here, the W3C has reserved all possible error codes for its own use. If you need something not listed here, I recommend writing your own exception class or subclass DOMException . ( Just because DOM doesn't make full use of an object-oriented exception mechanism for reasons of compatibility with languages less object-oriented than Java doesn't mean you shouldn't do this in your pure Java code.)