You’ve probably noticed that a lot of the methods so far have been declared to throw DOMException. This class itself is shown in Example 9.15 This is the generic exception for essentially anything that can go wrong while working with DOM ranging from logical errors like making an element one of its own children to implementation bugs. It is a runtime exception that does not have to be caught. However, you should always catch it or declare that your method throws it nonetheless. Conceptually, this should be a checked exception. However, many languages 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 like 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 DOMExceptions. They don’t even throw any subclasses of DOMException. Here, DOM is following C++ conventions rather than Java’s. Where Java tends to differentiate related exceptions through many different subclasses (In Java 1.4, there are more than fifty different subclasses of IOException alone.) DOM uses named short constants to identify the different problems that can arise. This is also useful for language like AppleScript where exceptions aren’t even classes. The exception code is exposed through DOMException’s public code field. The codes have the following meanings:
Something tried to put more than two billion characters into one string. This one isn’t 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.
An attempt was made to add a node where it can’t go; e.g. making an element a child of a text node, an attribute a child of an element, adding a second root element to a document, or trying to make an element its own grandpa.
A rare exception thrown by the splitText() method of a Text object if you try split the text before the beginning or after the end of the node.
You tried to add an existing Attr to a new element without removing it from the old element first.
The class that implements the DOM interface does not support the requested method, even though you’d normally expect it to.
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 form feed. 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.
The class that implements the DOM interface cannot change the object in the requested way, even though you’d normally expect it to; e.g. it ran out of space for more child nodes.
The implementation class that backs the DOM interface you’re using has gotten confused, and cannot perform the requested operation. This would generally indicate a bug in the implementation.
The namespace prefixes or URIs specified are somehow incorrect; e.g. the qualified name contains multiple colons, or the qualified name has a prefix but the namespace URI is null, or the prefix xml but the namespace URI is not http://www.w3.org/XML/1998/namespace.
A referenced node is not present in the document; e.g. you tried to remove an attribute the element does not have or tried to insert a node before another node that is no longer in the document.
The implementation does not support the requested object type. For example, you tried to create a CDATA section node using an HTML document implementation.
You tried 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.
You tried to change a read-only node. The most common reason a node is read-only is because it’s a descendant of an entity reference node.
You tried to set a value to a string that’s illegal in context; e.g. 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.
You tried 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 you have 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 DOM can prevent programs from using error codes other than those listed here, the W3C has reserved all possible error codes for their own use. If you need something not listed here, write 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 less object-oriented languages than Java doesn’t mean you shouldn’t do this in your pure Java code.)
| Copyright 2001, 2002 Elliotte Rusty Harold | elharo@metalab.unc.edu | Last Modified January 20, 2002 |
| Up To Cafe con Leche |